DEV Community: Aatif G.

ElevenLabs vs Deepgram Aura: Text-to-Speech Implementation Guide in .NET 8

Aatif G. — Wed, 17 Dec 2025 15:16:22 +0000

Introduction

This guide shows you how to implement Text-to-Speech using ElevenLabs and Deepgram Aura in a .NET 8 application, with support for streaming audio and voice customization.

Interface Definition

public interface ITTSProvider
{
    Task<byte[]> SynthesizeAsync(string text, VoiceOptions? options = null);
    IAsyncEnumerable<byte[]> StreamSynthesizeAsync(string text, VoiceOptions? options = null);
    Task<List<Voice>> GetAvailableVoicesAsync();
}

public record VoiceOptions(
    string? VoiceId = null,
    float? Speed = null,
    float? Pitch = null,
    AudioFormat Format = AudioFormat.PCM16);

public record Voice(string Id, string Name, string Description, string? PreviewUrl);

public enum AudioFormat
{
    PCM16,
    MP3,
    OGG
}

ElevenLabs Implementation

Setup

dotnet add package ElevenLabs

Configuration

// appsettings.json
{
  "ElevenLabs": {
    "ApiKey": "your-api-key",
    "DefaultVoice": "Rachel",
    "Model": "eleven_turbo_v2"
  }
}

Implementation

using ElevenLabs;
using ElevenLabs.Models;

public class ElevenLabsTTSProvider : ITTSProvider
{
    private readonly ElevenLabsClient _client;
    private readonly string _defaultVoice;
    private readonly string _model;
    private readonly ILogger<ElevenLabsTTSProvider> _logger;

    public ElevenLabsTTSProvider(
        IConfiguration configuration,
        ILogger<ElevenLabsTTSProvider> logger)
    {
        var apiKey = configuration["ElevenLabs:ApiKey"];
        _defaultVoice = configuration["ElevenLabs:DefaultVoice"] ?? "Rachel";
        _model = configuration["ElevenLabs:Model"] ?? "eleven_turbo_v2";
        _client = new ElevenLabsClient(apiKey);
        _logger = logger;
    }

    public async Task<byte[]> SynthesizeAsync(string text, VoiceOptions? options = null)
    {
        var voiceId = options?.VoiceId ?? _defaultVoice;

        var request = new TextToSpeechRequest
        {
            Text = text,
            ModelId = _model,
            VoiceSettings = new VoiceSettings
            {
                Stability = 0.5,
                SimilarityBoost = 0.75,
                Style = 0.0,
                UseSpeakerBoost = true
            }
        };

        var outputFormat = MapAudioFormat(options?.Format ?? AudioFormat.PCM16);

        using var audioStream = await _client.TextToSpeech.ConvertAsync(
            voiceId,
            request,
            outputFormat);

        using var memoryStream = new MemoryStream();
        await audioStream.CopyToAsync(memoryStream);

        _logger.LogInformation(
            "Generated {Bytes} bytes of audio for text length {Length}",
            memoryStream.Length,
            text.Length);

        return memoryStream.ToArray();
    }

    public async IAsyncEnumerable<byte[]> StreamSynthesizeAsync(
        string text,
        VoiceOptions? options = null)
    {
        var voiceId = options?.VoiceId ?? _defaultVoice;

        var request = new TextToSpeechRequest
        {
            Text = text,
            ModelId = _model,
            VoiceSettings = new VoiceSettings
            {
                Stability = 0.5,
                SimilarityBoost = 0.75
            }
        };

        var outputFormat = MapAudioFormat(options?.Format ?? AudioFormat.PCM16);

        await using var audioStream = await _client.TextToSpeech.ConvertStreamAsync(
            voiceId,
            request,
            outputFormat);

        var buffer = new byte[4096];
        int bytesRead;

        while ((bytesRead = await audioStream.ReadAsync(buffer, 0, buffer.Length)) > 0)
        {
            var chunk = new byte[bytesRead];
            Array.Copy(buffer, chunk, bytesRead);
            yield return chunk;
        }
    }

    public async Task<List<Voice>> GetAvailableVoicesAsync()
    {
        var voices = await _client.Voices.GetAllAsync();

        return voices.Select(v => new Voice(
            Id: v.VoiceId,
            Name: v.Name,
            Description: v.Description ?? string.Empty,
            PreviewUrl: v.PreviewUrl
        )).ToList();
    }

    private string MapAudioFormat(AudioFormat format)
    {
        return format switch
        {
            AudioFormat.PCM16 => "pcm_16000",
            AudioFormat.MP3 => "mp3_44100_128",
            AudioFormat.OGG => "ogg_opus",
            _ => "pcm_16000"
        };
    }
}

Deepgram Aura Implementation

Setup

dotnet add package Deepgram

Configuration

// appsettings.json
{
  "Deepgram": {
    "ApiKey": "your-api-key",
    "DefaultVoice": "aura-asteria-en"
  }
}

Implementation

using Deepgram;
using Deepgram.Models;

public class DeepgramTTSProvider : ITTSProvider
{
    private readonly DeepgramClient _client;
    private readonly string _defaultVoice;
    private readonly ILogger<DeepgramTTSProvider> _logger;

    public DeepgramTTSProvider(
        IConfiguration configuration,
        ILogger<DeepgramTTSProvider> logger)
    {
        var apiKey = configuration["Deepgram:ApiKey"];
        _defaultVoice = configuration["Deepgram:DefaultVoice"] ?? "aura-asteria-en";
        _client = new DeepgramClient(apiKey);
        _logger = logger;
    }

    public async Task<byte[]> SynthesizeAsync(string text, VoiceOptions? options = null)
    {
        var speakOptions = new SpeakOptions
        {
            Model = options?.VoiceId ?? _defaultVoice,
            Encoding = MapAudioFormat(options?.Format ?? AudioFormat.PCM16),
            SampleRate = 16000
        };

        var response = await _client.Speak.v("1").Synthesize(
            new TextSource(text),
            speakOptions);

        _logger.LogInformation(
            "Generated audio for text length {Length}",
            text.Length);

        return response.Data;
    }

    public async IAsyncEnumerable<byte[]> StreamSynthesizeAsync(
        string text,
        VoiceOptions? options = null)
    {
        var speakOptions = new SpeakOptions
        {
            Model = options?.VoiceId ?? _defaultVoice,
            Encoding = MapAudioFormat(options?.Format ?? AudioFormat.PCM16),
            SampleRate = 16000
        };

        await using var stream = await _client.Speak.v("1").SynthesizeStream(
            new TextSource(text),
            speakOptions);

        var buffer = new byte[4096];
        int bytesRead;

        while ((bytesRead = await stream.ReadAsync(buffer, 0, buffer.Length)) > 0)
        {
            var chunk = new byte[bytesRead];
            Array.Copy(buffer, chunk, bytesRead);
            yield return chunk;
        }
    }

    public async Task<List<Voice>> GetAvailableVoicesAsync()
    {
        // Deepgram Aura voices (as of 2024)
        return await Task.FromResult(new List<Voice>
        {
            new Voice("aura-asteria-en", "Asteria", "Female, warm and friendly", null),
            new Voice("aura-luna-en", "Luna", "Female, professional", null),
            new Voice("aura-stella-en", "Stella", "Female, energetic", null),
            new Voice("aura-athena-en", "Athena", "Female, clear", null),
            new Voice("aura-hera-en", "Hera", "Female, authoritative", null),
            new Voice("aura-orion-en", "Orion", "Male, deep", null),
            new Voice("aura-arcas-en", "Arcas", "Male, neutral", null),
            new Voice("aura-perseus-en", "Perseus", "Male, confident", null),
            new Voice("aura-angus-en", "Angus", "Male, friendly", null),
            new Voice("aura-orpheus-en", "Orpheus", "Male, smooth", null),
            new Voice("aura-helios-en", "Helios", "Male, warm", null),
            new Voice("aura-zeus-en", "Zeus", "Male, powerful", null)
        });
    }

    private string MapAudioFormat(AudioFormat format)
    {
        return format switch
        {
            AudioFormat.PCM16 => "linear16",
            AudioFormat.MP3 => "mp3",
            AudioFormat.OGG => "opus",
            _ => "linear16"
        };
    }
}

Dependency Injection Setup

// Program.cs
builder.Services.AddSingleton<ITTSProvider, ElevenLabsTTSProvider>();
// OR
builder.Services.AddSingleton<ITTSProvider, DeepgramTTSProvider>();

Usage Examples

Basic Text-to-Speech

[ApiController]
[Route("api/[controller]")]
public class SpeechController : ControllerBase
{
    private readonly ITTSProvider _tts;

    [HttpPost("synthesize")]
    public async Task<IActionResult> Synthesize([FromBody] SynthesizeRequest request)
    {
        var options = new VoiceOptions(
            VoiceId: request.VoiceId,
            Format: AudioFormat.MP3);

        var audioData = await _tts.SynthesizeAsync(request.Text, options);

        return File(audioData, "audio/mpeg", "speech.mp3");
    }

    [HttpGet("voices")]
    public async Task<IActionResult> GetVoices()
    {
        var voices = await _tts.GetAvailableVoicesAsync();
        return Ok(voices);
    }
}

public record SynthesizeRequest(string Text, string? VoiceId);

Streaming Audio via WebSocket

[HttpGet("stream")]
public async Task StreamAudio([FromQuery] string text, [FromQuery] string? voiceId)
{
    if (!HttpContext.WebSockets.IsWebSocketRequest)
    {
        HttpContext.Response.StatusCode = 400;
        return;
    }

    using var webSocket = await HttpContext.WebSockets.AcceptWebSocketAsync();

    var options = new VoiceOptions(VoiceId: voiceId);

    await foreach (var audioChunk in _tts.StreamSynthesizeAsync(text, options))
    {
        await webSocket.SendAsync(
            new ArraySegment<byte>(audioChunk),
            WebSocketMessageType.Binary,
            true,
            CancellationToken.None);
    }

    await webSocket.CloseAsync(
        WebSocketCloseStatus.NormalClosure,
        "Completed",
        CancellationToken.None);
}

Real-time Conversation with Streaming

public class ConversationStreamHandler
{
    private readonly INLPProvider _nlp;
    private readonly ITTSProvider _tts;

    public async IAsyncEnumerable<byte[]> ProcessAndSynthesize(string userMessage)
    {
        // Stream NLP response tokens
        await foreach (var token in _nlp.StreamResponseAsync(userMessage))
        {
            // Convert each token to speech immediately
            await foreach (var audioChunk in _tts.StreamSynthesizeAsync(token))
            {
                yield return audioChunk;
            }
        }
    }
}

Voice Customization

Custom Voice Settings (ElevenLabs)

public class CustomVoiceService
{
    private readonly ElevenLabsClient _client;

    public async Task<byte[]> SynthesizeWithEmotionAsync(
        string text,
        string emotion)
    {
        var voiceSettings = emotion.ToLower() switch
        {
            "excited" => new VoiceSettings
            {
                Stability = 0.3,
                SimilarityBoost = 0.9,
                Style = 0.8,
                UseSpeakerBoost = true
            },
            "calm" => new VoiceSettings
            {
                Stability = 0.8,
                SimilarityBoost = 0.6,
                Style = 0.2,
                UseSpeakerBoost = false
            },
            "professional" => new VoiceSettings
            {
                Stability = 0.7,
                SimilarityBoost = 0.7,
                Style = 0.0,
                UseSpeakerBoost = true
            },
            _ => new VoiceSettings()
        };

        var request = new TextToSpeechRequest
        {
            Text = text,
            ModelId = "eleven_turbo_v2",
            VoiceSettings = voiceSettings
        };

        using var audioStream = await _client.TextToSpeech.ConvertAsync(
            "Rachel",
            request,
            "pcm_16000");

        using var memoryStream = new MemoryStream();
        await audioStream.CopyToAsync(memoryStream);
        return memoryStream.ToArray();
    }
}

Audio Post-Processing

Normalize Volume

public class AudioProcessor
{
    public byte[] NormalizeVolume(byte[] audioData, float targetLevel = 0.8f)
    {
        var samples = new short[audioData.Length / 2];
        Buffer.BlockCopy(audioData, 0, samples, 0, audioData.Length);

        // Find peak
        float peak = samples.Max(s => Math.Abs(s));
        float scale = (short.MaxValue * targetLevel) / peak;

        // Normalize
        for (int i = 0; i < samples.Length; i++)
        {
            samples[i] = (short)Math.Clamp(samples[i] * scale, short.MinValue, short.MaxValue);
        }

        var result = new byte[audioData.Length];
        Buffer.BlockCopy(samples, 0, result, 0, audioData.Length);
        return result;
    }
}

Format Conversion

public class AudioConverter
{
    public byte[] ConvertPCMToMP3(byte[] pcmData, int sampleRate = 16000)
    {
        // Using NAudio
        using var pcmStream = new MemoryStream(pcmData);
        using var reader = new RawSourceWaveStream(
            pcmStream,
            new WaveFormat(sampleRate, 16, 1));

        using var mp3Stream = new MemoryStream();
        using var writer = new LameMP3FileWriter(mp3Stream, reader.WaveFormat, 128);

        reader.CopyTo(writer);
        return mp3Stream.ToArray();
    }
}

Error Handling and Fallback

public class FallbackTTSProvider : ITTSProvider
{
    private readonly ITTSProvider _primary;
    private readonly ITTSProvider _fallback;
    private readonly ILogger<FallbackTTSProvider> _logger;

    public async Task<byte[]> SynthesizeAsync(string text, VoiceOptions? options = null)
    {
        try
        {
            return await _primary.SynthesizeAsync(text, options);
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Primary TTS failed, using fallback");
            return await _fallback.SynthesizeAsync(text, options);
        }
    }

    public async IAsyncEnumerable<byte[]> StreamSynthesizeAsync(
        string text,
        VoiceOptions? options = null)
    {
        IAsyncEnumerable<byte[]> stream;
        try
        {
            stream = _primary.StreamSynthesizeAsync(text, options);
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Primary TTS streaming failed, using fallback");
            stream = _fallback.StreamSynthesizeAsync(text, options);
        }

        await foreach (var chunk in stream)
        {
            yield return chunk;
        }
    }
}

Caching for Performance

public class CachedTTSProvider : ITTSProvider
{
    private readonly ITTSProvider _provider;
    private readonly IDistributedCache _cache;
    private readonly ILogger<CachedTTSProvider> _logger;

    public async Task<byte[]> SynthesizeAsync(string text, VoiceOptions? options = null)
    {
        var cacheKey = GenerateCacheKey(text, options);

        var cached = await _cache.GetAsync(cacheKey);
        if (cached != null)
        {
            _logger.LogInformation("Cache hit for text: {Text}", text.Substring(0, 20));
            return cached;
        }

        var audio = await _provider.SynthesizeAsync(text, options);

        await _cache.SetAsync(
            cacheKey,
            audio,
            new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow = TimeSpan.FromHours(24)
            });

        return audio;
    }

    private string GenerateCacheKey(string text, VoiceOptions? options)
    {
        var optionsHash = options != null
            ? $"{options.VoiceId}_{options.Format}"
            : "default";
        return $"tts:{optionsHash}:{ComputeHash(text)}";
    }

    private string ComputeHash(string text)
    {
        using var sha256 = SHA256.Create();
        var bytes = Encoding.UTF8.GetBytes(text);
        var hash = sha256.ComputeHash(bytes);
        return Convert.ToBase64String(hash);
    }
}

Testing

public class TTSProviderTests
{
    [Fact]
    public async Task Synthesize_ValidText_ReturnsAudio()
    {
        // Arrange
        var mockConfig = new Mock<IConfiguration>();
        mockConfig.Setup(x => x["ElevenLabs:ApiKey"]).Returns("test-key");

        var provider = new ElevenLabsTTSProvider(
            mockConfig.Object,
            Mock.Of<ILogger<ElevenLabsTTSProvider>>());

        // Act
        var audio = await provider.SynthesizeAsync("Hello world");

        // Assert
        Assert.NotEmpty(audio);
        Assert.True(audio.Length > 1000); // Reasonable audio size
    }

    [Fact]
    public async Task StreamSynthesize_ValidText_ReturnsChunks()
    {
        // Arrange
        var provider = CreateTestProvider();
        var chunks = new List<byte[]>();

        // Act
        await foreach (var chunk in provider.StreamSynthesizeAsync("Hello"))
        {
            chunks.Add(chunk);
        }

        // Assert
        Assert.NotEmpty(chunks);
        Assert.True(chunks.Sum(c => c.Length) > 1000);
    }
}

Performance Benchmarks

Based on production testing:

Provider	Latency (first chunk)	Quality	Cost per 1K chars
ElevenLabs	300-500ms	Excellent	$0.18-0.30
Deepgram Aura	200-350ms	Very Good	$0.015
Azure Neural	400-600ms	Very Good	$0.015
Google WaveNet	500-700ms	Excellent	$0.016

Best Practices

Stream when possible: Reduces perceived latency by 50%
Cache common phrases: "Hello", "How can I help", etc.
Pre-generate audio: For known responses in menu systems
Normalize volume: Ensure consistent audio levels
Handle errors gracefully: Always have a fallback provider

Comparison

Feature	ElevenLabs	Deepgram Aura
Latency	300-500ms	200-350ms
Quality	★★★★★	★★★★☆
Voice Cloning	Yes	No
Streaming	Yes	Yes
Pricing	See here	See here
Best For	Premium quality	Low latency

Related Artciles

This Article is a part of Guide to Voice-based Applications on Medium.

Questions? Drop them in the comments!

OpenAI vs Claude: NLP Implementation Guide in .NET 8

Aatif G. — Wed, 17 Dec 2025 15:08:39 +0000

Introduction

This guide shows you how to implement Natural Language Processing using OpenAI GPT and Anthropic Claude in a .NET 8 application, with support for streaming responses and function calling.

Interface Definition

public interface INLPProvider
{
    Task<string> GenerateResponseAsync(string userMessage, List<ChatMessage>? history = null);
    IAsyncEnumerable<string> StreamResponseAsync(string userMessage, List<ChatMessage>? history = null);
    Task<FunctionCallResult> GenerateWithFunctionsAsync(string userMessage, List<Function> functions);
}

public record ChatMessage(string Role, string Content);

public record Function(string Name, string Description, object Parameters);

public record FunctionCallResult(string Response, string? FunctionName, string? FunctionArguments);

OpenAI GPT Implementation

Setup

dotnet add package OpenAI

Configuration

// appsettings.json
{
  "OpenAI": {
    "ApiKey": "your-api-key",
    "Model": "gpt-4-turbo-preview",
    "MaxTokens": 1000
  }
}

Implementation

using OpenAI;
using OpenAI.Chat;

public class OpenAINLPProvider : INLPProvider
{
    private readonly ChatClient _client;
    private readonly string _model;
    private readonly int _maxTokens;
    private readonly ILogger<OpenAINLPProvider> _logger;

    public OpenAINLPProvider(
        IConfiguration configuration,
        ILogger<OpenAINLPProvider> logger)
    {
        var apiKey = configuration["OpenAI:ApiKey"];
        _model = configuration["OpenAI:Model"] ?? "gpt-4-turbo-preview";
        _maxTokens = int.Parse(configuration["OpenAI:MaxTokens"] ?? "1000");
        _client = new ChatClient(_model, apiKey);
        _logger = logger;
    }

    public async Task<string> GenerateResponseAsync(
        string userMessage,
        List<ChatMessage>? history = null)
    {
        var messages = BuildMessages(userMessage, history);

        var options = new ChatCompletionOptions
        {
            MaxTokens = _maxTokens,
            Temperature = 0.7f
        };

        var completion = await _client.CompleteChatAsync(messages, options);
        var response = completion.Value.Content[0].Text;

        _logger.LogInformation("Generated response: {Response}", response);
        return response;
    }

    public async IAsyncEnumerable<string> StreamResponseAsync(
        string userMessage,
        List<ChatMessage>? history = null)
    {
        var messages = BuildMessages(userMessage, history);

        var options = new ChatCompletionOptions
        {
            MaxTokens = _maxTokens,
            Temperature = 0.7f
        };

        await foreach (var update in _client.CompleteChatStreamingAsync(messages, options))
        {
            foreach (var contentPart in update.ContentUpdate)
            {
                if (!string.IsNullOrEmpty(contentPart.Text))
                {
                    yield return contentPart.Text;
                }
            }
        }
    }

    public async Task<FunctionCallResult> GenerateWithFunctionsAsync(
        string userMessage,
        List<Function> functions)
    {
        var messages = new List<OpenAI.Chat.ChatMessage>
        {
            new SystemChatMessage("You are a helpful assistant with access to functions."),
            new UserChatMessage(userMessage)
        };

        var tools = functions.Select(f => ChatTool.CreateFunctionTool(
            f.Name,
            f.Description,
            BinaryData.FromObjectAsJson(f.Parameters)
        )).ToList();

        var options = new ChatCompletionOptions();
        foreach (var tool in tools)
        {
            options.Tools.Add(tool);
        }

        var completion = await _client.CompleteChatAsync(messages, options);
        var firstChoice = completion.Value.Content[0];

        if (completion.Value.FinishReason == ChatFinishReason.ToolCalls)
        {
            var toolCall = completion.Value.ToolCalls[0];
            return new FunctionCallResult(
                Response: completion.Value.Content[0].Text ?? string.Empty,
                FunctionName: toolCall.FunctionName,
                FunctionArguments: toolCall.FunctionArguments.ToString()
            );
        }

        return new FunctionCallResult(
            Response: completion.Value.Content[0].Text,
            FunctionName: null,
            FunctionArguments: null
        );
    }

    private List<OpenAI.Chat.ChatMessage> BuildMessages(
        string userMessage,
        List<ChatMessage>? history)
    {
        var messages = new List<OpenAI.Chat.ChatMessage>
        {
            new SystemChatMessage("You are a helpful voice assistant.")
        };

        if (history != null)
        {
            foreach (var msg in history)
            {
                messages.Add(msg.Role.ToLower() switch
                {
                    "user" => new UserChatMessage(msg.Content),
                    "assistant" => new AssistantChatMessage(msg.Content),
                    _ => new SystemChatMessage(msg.Content)
                });
            }
        }

        messages.Add(new UserChatMessage(userMessage));
        return messages;
    }
}

Anthropic Claude Implementation

Setup

dotnet add package Anthropic.SDK

Configuration

// appsettings.json
{
  "Anthropic": {
    "ApiKey": "your-api-key",
    "Model": "claude-3-5-sonnet-20241022",
    "MaxTokens": 1000
  }
}

Implementation

using Anthropic.SDK;
using Anthropic.SDK.Messaging;

public class ClaudeNLPProvider : INLPProvider
{
    private readonly AnthropicClient _client;
    private readonly string _model;
    private readonly int _maxTokens;
    private readonly ILogger<ClaudeNLPProvider> _logger;

    public ClaudeNLPProvider(
        IConfiguration configuration,
        ILogger<ClaudeNLPProvider> logger)
    {
        var apiKey = configuration["Anthropic:ApiKey"];
        _model = configuration["Anthropic:Model"] ?? "claude-3-5-sonnet-20241022";
        _maxTokens = int.Parse(configuration["Anthropic:MaxTokens"] ?? "1000");
        _client = new AnthropicClient(apiKey);
        _logger = logger;
    }

    public async Task<string> GenerateResponseAsync(
        string userMessage,
        List<ChatMessage>? history = null)
    {
        var messages = BuildMessages(userMessage, history);

        var request = new MessageRequest
        {
            Model = _model,
            MaxTokens = _maxTokens,
            Messages = messages,
            System = "You are a helpful voice assistant."
        };

        var response = await _client.Messages.CreateAsync(request);
        var content = response.Content[0].Text;

        _logger.LogInformation("Generated response: {Response}", content);
        return content;
    }

    public async IAsyncEnumerable<string> StreamResponseAsync(
        string userMessage,
        List<ChatMessage>? history = null)
    {
        var messages = BuildMessages(userMessage, history);

        var request = new MessageRequest
        {
            Model = _model,
            MaxTokens = _maxTokens,
            Messages = messages,
            System = "You are a helpful voice assistant.",
            Stream = true
        };

        await foreach (var chunk in _client.Messages.StreamAsync(request))
        {
            if (chunk.Type == "content_block_delta" && chunk.Delta?.Text != null)
            {
                yield return chunk.Delta.Text;
            }
        }
    }

    public async Task<FunctionCallResult> GenerateWithFunctionsAsync(
        string userMessage,
        List<Function> functions)
    {
        var messages = BuildMessages(userMessage, null);

        var tools = functions.Select(f => new Tool
        {
            Name = f.Name,
            Description = f.Description,
            InputSchema = f.Parameters
        }).ToList();

        var request = new MessageRequest
        {
            Model = _model,
            MaxTokens = _maxTokens,
            Messages = messages,
            System = "You are a helpful assistant with access to tools.",
            Tools = tools
        };

        var response = await _client.Messages.CreateAsync(request);

        if (response.StopReason == "tool_use" && response.Content.Any(c => c.Type == "tool_use"))
        {
            var toolUse = response.Content.First(c => c.Type == "tool_use");
            return new FunctionCallResult(
                Response: response.Content.FirstOrDefault(c => c.Type == "text")?.Text ?? string.Empty,
                FunctionName: toolUse.Name,
                FunctionArguments: toolUse.Input?.ToString()
            );
        }

        return new FunctionCallResult(
            Response: response.Content[0].Text,
            FunctionName: null,
            FunctionArguments: null
        );
    }

    private List<Message> BuildMessages(string userMessage, List<ChatMessage>? history)
    {
        var messages = new List<Message>();

        if (history != null)
        {
            foreach (var msg in history)
            {
                messages.Add(new Message
                {
                    Role = msg.Role.ToLower() == "user" ? "user" : "assistant",
                    Content = msg.Content
                });
            }
        }

        messages.Add(new Message { Role = "user", Content = userMessage });
        return messages;
    }
}

Dependency Injection Setup

// Program.cs
builder.Services.AddSingleton<INLPProvider, OpenAINLPProvider>();
// OR
builder.Services.AddSingleton<INLPProvider, ClaudeNLPProvider>();

Usage Examples

Basic Conversation

[ApiController]
[Route("api/[controller]")]
public class ConversationController : ControllerBase
{
    private readonly INLPProvider _nlp;

    [HttpPost("chat")]
    public async Task<IActionResult> Chat([FromBody] ChatRequest request)
    {
        var response = await _nlp.GenerateResponseAsync(request.Message, request.History);
        return Ok(new { response });
    }
}

public record ChatRequest(string Message, List<ChatMessage>? History);

Streaming Response

[HttpPost("stream")]
public async Task StreamChat([FromBody] ChatRequest request)
{
    Response.ContentType = "text/event-stream";

    await foreach (var token in _nlp.StreamResponseAsync(request.Message, request.History))
    {
        await Response.WriteAsync($"data: {token}\n\n");
        await Response.Body.FlushAsync();
    }
}

Function Calling Example

[HttpPost("book-room")]
public async Task<IActionResult> BookRoom([FromBody] BookingRequest request)
{
    var functions = new List<Function>
    {
        new Function(
            Name: "check_availability",
            Description: "Check room availability for given dates",
            Parameters: new
            {
                type = "object",
                properties = new
                {
                    check_in = new { type = "string", description = "Check-in date (YYYY-MM-DD)" },
                    check_out = new { type = "string", description = "Check-out date (YYYY-MM-DD)" },
                    room_type = new { type = "string", description = "Type of room requested" }
                },
                required = new[] { "check_in", "check_out" }
            }
        ),
        new Function(
            Name: "create_booking",
            Description: "Create a new room booking",
            Parameters: new
            {
                type = "object",
                properties = new
                {
                    guest_name = new { type = "string" },
                    check_in = new { type = "string" },
                    check_out = new { type = "string" },
                    room_type = new { type = "string" }
                },
                required = new[] { "guest_name", "check_in", "check_out", "room_type" }
            }
        )
    };

    var result = await _nlp.GenerateWithFunctionsAsync(request.Message, functions);

    if (result.FunctionName != null)
    {
        // Execute the function
        var functionResult = await ExecuteFunction(result.FunctionName, result.FunctionArguments);
        return Ok(new { result.Response, functionResult });
    }

    return Ok(new { result.Response });
}

public record BookingRequest(string Message);

Context Management

public class ConversationManager
{
    private readonly IDistributedCache _cache;
    private readonly INLPProvider _nlp;

    public async Task<string> ProcessMessage(string sessionId, string userMessage)
    {
        // Retrieve conversation history
        var history = await GetConversationHistory(sessionId);

        // Generate response
        var response = await _nlp.GenerateResponseAsync(userMessage, history);

        // Update history
        history.Add(new ChatMessage("user", userMessage));
        history.Add(new ChatMessage("assistant", response));

        // Trim if too long (keep last 20 messages)
        if (history.Count > 20)
        {
            history = history.TakeLast(20).ToList();
        }

        // Save updated history
        await SaveConversationHistory(sessionId, history);

        return response;
    }

    private async Task<List<ChatMessage>> GetConversationHistory(string sessionId)
    {
        var cached = await _cache.GetStringAsync($"conv:{sessionId}");
        return cached != null
            ? JsonSerializer.Deserialize<List<ChatMessage>>(cached) ?? new()
            : new List<ChatMessage>();
    }

    private async Task SaveConversationHistory(string sessionId, List<ChatMessage> history)
    {
        var json = JsonSerializer.Serialize(history);
        await _cache.SetStringAsync(
            $"conv:{sessionId}",
            json,
            new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow = TimeSpan.FromHours(1)
            });
    }
}

Error Handling with Retry

public class ResilientNLPProvider : INLPProvider
{
    private readonly INLPProvider _provider;
    private readonly ILogger<ResilientNLPProvider> _logger;

    public async Task<string> GenerateResponseAsync(
        string userMessage,
        List<ChatMessage>? history = null)
    {
        var retryPolicy = Policy
            .Handle<Exception>()
            .WaitAndRetryAsync(3, retryAttempt =>
                TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)),
                onRetry: (exception, timeSpan, retryCount, context) =>
                {
                    _logger.LogWarning(
                        "Retry {RetryCount} after {TimeSpan}. Error: {Error}",
                        retryCount, timeSpan, exception.Message);
                });

        return await retryPolicy.ExecuteAsync(async () =>
            await _provider.GenerateResponseAsync(userMessage, history));
    }

    // Similar implementations for other methods...
}

Performance Optimization

Caching Common Responses

public class CachedNLPProvider : INLPProvider
{
    private readonly INLPProvider _provider;
    private readonly IMemoryCache _cache;

    public async Task<string> GenerateResponseAsync(
        string userMessage,
        List<ChatMessage>? history = null)
    {
        // Only cache simple queries without history
        if (history != null && history.Any())
        {
            return await _provider.GenerateResponseAsync(userMessage, history);
        }

        var cacheKey = $"nlp:{userMessage.ToLowerInvariant()}";

        if (_cache.TryGetValue(cacheKey, out string? cachedResponse))
        {
            return cachedResponse!;
        }

        var response = await _provider.GenerateResponseAsync(userMessage);

        _cache.Set(cacheKey, response, TimeSpan.FromMinutes(5));

        return response;
    }
}

Testing

public class NLPProviderTests
{
    [Fact]
    public async Task GenerateResponse_SimpleQuery_ReturnsText()
    {
        // Arrange
        var mockConfig = new Mock<IConfiguration>();
        mockConfig.Setup(x => x["OpenAI:ApiKey"]).Returns("test-key");
        mockConfig.Setup(x => x["OpenAI:Model"]).Returns("gpt-4");

        var provider = new OpenAINLPProvider(
            mockConfig.Object,
            Mock.Of<ILogger<OpenAINLPProvider>>());

        // Act
        var response = await provider.GenerateResponseAsync("Hello");

        // Assert
        Assert.NotEmpty(response);
    }

    [Fact]
    public async Task StreamResponse_SimpleQuery_ReturnsTokens()
    {
        // Arrange
        var provider = CreateTestProvider();
        var tokens = new List<string>();

        // Act
        await foreach (var token in provider.StreamResponseAsync("Hello"))
        {
            tokens.Add(token);
        }

        // Assert
        Assert.NotEmpty(tokens);
    }
}

Comparison

Feature	OpenAI GPT-4	Claude 3.5 Sonnet
Speed	500-800ms	400-700ms
Context	128K tokens	200K tokens
Function Calling	Yes	Yes (Tools)
Pricing	See here	See here
Best For	Complex reasoning	Instruction following

This Article is a part of Guide to Voice-based Applications on Medium.

Questions? Drop them in the comments!

Deepgram vs AssemblyAI: Speech-to-Text Implementation in .NET 8

Aatif G. — Wed, 17 Dec 2025 14:59:23 +0000

Introduction

This guide shows you how to implement real-time Speech-to-Text using Deepgram and AssemblyAI in a .NET 8 application. Both providers offer excellent accuracy and low latency, but with different strengths.

Deepgram Implementation

Deepgram excels at low-latency streaming transcription, perfect for real-time conversations.

Setup

dotnet add package Deepgram

Configuration

// appsettings.json
{
  "Deepgram": {
    "ApiKey": "your-api-key"
  }
}

Interface Definition

public interface ISTTProvider
{
    Task<string> TranscribeAsync(Stream audioStream);
    IAsyncEnumerable<string> StreamTranscribeAsync(Stream audioStream);
}

Implementation

using Deepgram;
using Deepgram.Models;

public class DeepgramSTTProvider : ISTTProvider
{
    private readonly DeepgramClient _client;
    private readonly ILogger<DeepgramSTTProvider> _logger;

    public DeepgramSTTProvider(
        IConfiguration configuration,
        ILogger<DeepgramSTTProvider> logger)
    {
        _client = new DeepgramClient(configuration["Deepgram:ApiKey"]);
        _logger = logger;
    }

    public async Task<string> TranscribeAsync(Stream audioStream)
    {
        var options = new PrerecordedTranscriptionOptions
        {
            Model = "nova-2",
            Language = "en-US",
            Punctuate = true,
            Diarize = false
        };

        var response = await _client.Transcription.Prerecorded.TranscribeAsync(
            new UrlSource("STREAM"),
            options);

        return response.Results.Channels[0].Alternatives[0].Transcript;
    }

    public async IAsyncEnumerable<string> StreamTranscribeAsync(Stream audioStream)
    {
        var options = new LiveTranscriptionOptions
        {
            Model = "nova-2",
            Language = "en-US",
            Punctuate = true,
            InterimResults = true,
            Endpointing = 300 // ms of silence before finalizing
        };

        using var connection = _client.CreateLiveTranscriptionConnection(options);
        var transcriptBuffer = new StringBuilder();
        var transcriptReady = new TaskCompletionSource<string>();

        connection.TranscriptReceived += (sender, transcript) =>
        {
            if (transcript.IsFinal)
            {
                var text = transcript.Channel.Alternatives[0].Transcript;
                _logger.LogInformation("Final transcript: {Text}", text);
                transcriptReady.TrySetResult(text);
            }
        };

        connection.ConnectionError += (sender, error) =>
        {
            _logger.LogError("Connection error: {Error}", error.Message);
            transcriptReady.TrySetException(new Exception(error.Message));
        };

        await connection.StartConnectionAsync();

        // Stream audio in chunks
        var buffer = new byte[8192];
        int bytesRead;
        while ((bytesRead = await audioStream.ReadAsync(buffer, 0, buffer.Length)) > 0)
        {
            await connection.SendAsync(buffer.Take(bytesRead).ToArray());
        }

        await connection.FinishAsync();

        var result = await transcriptReady.Task;
        yield return result;
    }
}

AssemblyAI Implementation

AssemblyAI offers advanced features like speaker diarization and sentiment analysis.

Setup

dotnet add package AssemblyAI

Implementation

using AssemblyAI;
using AssemblyAI.Transcripts;

public class AssemblyAISTTProvider : ISTTProvider
{
    private readonly AssemblyAIClient _client;
    private readonly ILogger<AssemblyAISTTProvider> _logger;

    public AssemblyAISTTProvider(
        IConfiguration configuration,
        ILogger<AssemblyAISTTProvider> logger)
    {
        _client = new AssemblyAIClient(configuration["AssemblyAI:ApiKey"]);
        _logger = logger;
    }

    public async Task<string> TranscribeAsync(Stream audioStream)
    {
        // Upload audio
        var uploadUrl = await _client.Files.UploadAsync(audioStream);

        // Create transcript
        var transcript = await _client.Transcripts.TranscribeAsync(new TranscriptParams
        {
            AudioUrl = uploadUrl,
            LanguageCode = TranscriptLanguageCode.En,
            PunctuationEnabled = true,
            FormatTextEnabled = true,
            SpeakerLabelsEnabled = true // Diarization
        });

        // Wait for completion
        transcript = await _client.Transcripts.WaitUntilReadyAsync(transcript.Id);

        return transcript.Text;
    }

    public async IAsyncEnumerable<string> StreamTranscribeAsync(Stream audioStream)
    {
        using var realtime = _client.Realtime.CreateTranscriber();
        var transcripts = new List<string>();

        realtime.SessionBegins += (sender, e) =>
        {
            _logger.LogInformation("Session started: {SessionId}", e.SessionId);
        };

        realtime.PartialTranscriptReceived += (sender, transcript) =>
        {
            _logger.LogDebug("Partial: {Text}", transcript.Text);
        };

        realtime.FinalTranscriptReceived += (sender, transcript) =>
        {
            _logger.LogInformation("Final: {Text}", transcript.Text);
            transcripts.Add(transcript.Text);
        };

        realtime.ErrorReceived += (sender, error) =>
        {
            _logger.LogError("Error: {Error}", error.Error);
        };

        await realtime.ConnectAsync();

        // Stream audio
        var buffer = new byte[8192];
        int bytesRead;
        while ((bytesRead = await audioStream.ReadAsync(buffer, 0, buffer.Length)) > 0)
        {
            await realtime.SendAudioAsync(buffer.Take(bytesRead).ToArray());
        }

        await realtime.CloseAsync();

        foreach (var transcript in transcripts)
        {
            yield return transcript;
        }
    }
}

Dependency Injection Setup

// Program.cs
builder.Services.AddSingleton<ISTTProvider, DeepgramSTTProvider>();
// OR
builder.Services.AddSingleton<ISTTProvider, AssemblyAISTTProvider>();

Usage Example

[ApiController]
[Route("api/[controller]")]
public class TranscriptionController : ControllerBase
{
    private readonly ISTTProvider _stt;

    public TranscriptionController(ISTTProvider stt)
    {
        _stt = stt;
    }

    [HttpPost("transcribe")]
    public async Task<IActionResult> Transcribe(IFormFile audio)
    {
        using var stream = audio.OpenReadStream();
        var transcript = await _stt.TranscribeAsync(stream);
        return Ok(new { transcript });
    }

    [HttpPost("stream")]
    public async Task StreamTranscribe()
    {
        if (!HttpContext.WebSockets.IsWebSocketRequest)
            return;

        using var webSocket = await HttpContext.WebSockets.AcceptWebSocketAsync();
        var audioStream = new MemoryStream();

        // Receive audio via WebSocket
        var buffer = new byte[1024 * 4];
        while (webSocket.State == WebSocketState.Open)
        {
            var result = await webSocket.ReceiveAsync(
                new ArraySegment<byte>(buffer),
                CancellationToken.None);

            if (result.MessageType == WebSocketMessageType.Binary)
            {
                await audioStream.WriteAsync(buffer, 0, result.Count);
            }
            else if (result.MessageType == WebSocketMessageType.Close)
            {
                break;
            }
        }

        audioStream.Position = 0;
        await foreach (var transcript in _stt.StreamTranscribeAsync(audioStream))
        {
            var response = Encoding.UTF8.GetBytes(transcript);
            await webSocket.SendAsync(
                new ArraySegment<byte>(response),
                WebSocketMessageType.Text,
                true,
                CancellationToken.None);
        }
    }
}

Error Handling with Fallback

public class FallbackSTTProvider : ISTTProvider
{
    private readonly ISTTProvider _primary;
    private readonly ISTTProvider _fallback;
    private readonly ILogger<FallbackSTTProvider> _logger;

    public FallbackSTTProvider(
        IEnumerable<ISTTProvider> providers,
        ILogger<FallbackSTTProvider> logger)
    {
        var providerList = providers.ToList();
        _primary = providerList[0];
        _fallback = providerList[1];
        _logger = logger;
    }

    public async Task<string> TranscribeAsync(Stream audioStream)
    {
        try
        {
            return await _primary.TranscribeAsync(audioStream);
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Primary STT failed, using fallback");
            audioStream.Position = 0; // Reset stream
            return await _fallback.TranscribeAsync(audioStream);
        }
    }

    public async IAsyncEnumerable<string> StreamTranscribeAsync(Stream audioStream)
    {
        IAsyncEnumerable<string> stream;
        try
        {
            stream = _primary.StreamTranscribeAsync(audioStream);
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Primary STT failed, using fallback");
            audioStream.Position = 0;
            stream = _fallback.StreamTranscribeAsync(audioStream);
        }

        await foreach (var transcript in stream)
        {
            yield return transcript;
        }
    }
}

Testing

public class STTProviderTests
{
    [Fact]
    public async Task Transcribe_ValidAudio_ReturnsText()
    {
        // Arrange
        var mockConfig = new Mock<IConfiguration>();
        mockConfig.Setup(x => x["Deepgram:ApiKey"]).Returns("test-key");

        var provider = new DeepgramSTTProvider(
            mockConfig.Object,
            Mock.Of<ILogger<DeepgramSTTProvider>>());

        var audioStream = File.OpenRead("test-audio.wav");

        // Act
        var result = await provider.TranscribeAsync(audioStream);

        // Assert
        Assert.NotEmpty(result);
    }
}

Performance Tips

Use streaming for real-time: StreamTranscribeAsync for live conversations
Batch processing: Use TranscribeAsync for recorded audio
Audio format: PCM16 at 16kHz for best results
Buffer size: 8KB chunks for optimal streaming
Endpointing: 300ms works well for natural pauses

Comparison

Feature	Deepgram	AssemblyAI
Latency	200-400ms	300-500ms
Accuracy	Excellent	Excellent
Diarization	Optional	Built-in
Pricing	See here	See here
Best For	Speed	Features

This Article is a part of Guide to Voice-based Applications on Medium.

Questions? Drop them in the comments!

HierarchyId in SQL Server and EF Core 8 - Modeling Hierarchical Data

Aatif G. — Tue, 28 Oct 2025 04:14:29 +0000

Hierarchical data is everywhere—from product categories and organizational charts to nested comments and file systems. SQL Server introduced the HierarchyId data type in SQL Server 2008, offering a compact and efficient way to represent tree structures. Now, with Entity Framework Core 8 in .NET 8, developers can use HierarchyId natively in their C# models.

Let’s explore how this works and why it matters.

🧠 What Is HierarchyId?

HierarchyId is a system-defined SQL Server data type that encodes a node's position in a hierarchy. It stores the path from the root to the node using a compact binary format, enabling fast traversal, sorting, and querying.

Example Paths:

/ → Root
/1/ → First child of root
/1/3/ → Third child of the first child

🧱 SQL Server Capabilities

Depth-first ordering: Nodes are stored and compared in depth-first order.
Efficient indexing: Children of a node are stored close together.
Built-in methods:
- GetAncestor()
- GetDescendant()
- IsDescendantOf()
- GetLevel()

These methods allow you to query and manipulate tree structures without recursive joins.

🧬 EF Core 8 Integration

.NET 8 brings native support for HierarchyId in EF Core 8, eliminating the need for manual conversions or raw SQL.

✅ Example Model:

public class Category
{
    public int Id { get; set; }
    public HierarchyId Path { get; set; }
}

modelBuilder.Entity<Category>()
    .Property(c => c.Path)
    .HasColumnType("hierarchyid");

✅ Querying Descendants:

var descendants = context.Categories
    .Where(c => c.Path.IsDescendantOf(parent.Path))
    .ToList();

EF Core translates this into SQL using the native IsDescendantOf() method.

🧭 Use Cases

Product categories with nested subcategories
Organizational charts with departments and roles
Menu structures for dynamic navigation
Multi-tenant config trees with scoped overrides

🛠️ Tips for Using `HierarchyId`

Use GetDescendant() to generate new child paths
Index the HierarchyId column for fast traversal
Avoid deep nesting beyond 892 bytes (SQL Server limit)
Use depth-first sorting for hierarchical display

🧾 Final Thoughts

With SQL Server’s mature HierarchyId and EF Core 8’s native support, modeling hierarchical data is now clean, efficient, and fully integrated into .NET 8. Whether you're building admin panels, category trees, or nested workflows, this feature unlocks powerful new patterns for scalable design.

🔍 Want More on .NET 8?

HierarchyId is just one piece of the puzzle. .NET 8 brings major upgrades across ASP.NET Core, EF Core, and the runtime—like native AOT compilation, Blazor unification, complex types, primitive collections, and powerful new C# 12 syntax.

Explore detailed .NET 8 breakdown here

Customizing the Stubborn Int'l Phone

Aatif G. — Fri, 26 Sep 2025 05:09:52 +0000

I was building a polished Bootstrap form including a phone number input, when Copilot suggested to use the popular intl-tel-input plugin:

document.addEventListener("DOMContentLoaded", function () {
    const input = document.querySelector("#Form_Phone");
    const iti = window.intlTelInput(input, {
        initialCountry: "pk",
        preferredCountries: ["pk", "sa", "tr", "ae", "bd"],
        separateDialCode: false,
        nationalMode: false, // forces international format
        autoHideDialCode: false, // keeps dial code visible
        utilsScript: "https://cdnjs.cloudflare.com/ajax/libs/intl-tel-input/17.0.8/js/utils.js"
});

It looked nice initially but then I ran into a frustrating visual bug. The phone field looked misaligned despite using the same css for all other fields in the same form:

Not only that, the dial codes appeared scattered, and the dropdown seemed washed out when expanded:

It got even annoying when I tried to fix by applying d-flex, d-block w-100 and whatever to make it stretched.
Another problem was the scattered country codes, which I just hid by using:

const countryItems = document.querySelectorAll(".iti__country-list .iti__country");
countryItems.forEach(item => {
const dialCode = item.querySelector(".iti__dial-code");
if (dialCode) {
    dialCode.style.display = "none"; // hide dial code
}
});

I somehow managed to clear up the scattered dialing codes:

But the width issue was still there, I kept trying different CSS tweaks, Bootstrap classes to apply colour, enforce width, apply container box etc. but nothing helped.

The Breakthrough

Meanwhile I also realised that the dropdown is supposed to show country names as well, and those in my case were shown in white or too light, making them almost invisible. That was the reason dialing codes were "scattered", they were seen at random distance form their respective flags because of the long and short country names in between the flag and dialing code.

Now I was dealing with two challenges, readability and alignment to my form.

The One-Line Fix

After a long diagnostic chat with Copilot and some research, I figured the CSS class responsible for this:

.iti.iti--allow-dropdown {
    width: 100%;
    color:maroon;
}

This small fix:

Forced full width alignment
Restored readable text color
Fixed the illusion of scattered dial codes

No wrappers. No hacks. Just clarity.

Width ✅

Readability ✅

Why This Matters

This bug wasn't just cosmetic — it undermined the user experience and made the form feel broken. And the fix wasn't just about layout — it was about visibility. By understanding how the plugin injects its markup and how inherited styles can silently break it, I was able to solve the problem at its root, using its own CSS class instead of applying generic wrapper or anything.

Sometimes, it is just one line - at the right spot.

Serilog: Runtime Control and Auto-Elevated Logging

Aatif G. — Sun, 07 Sep 2025 04:31:26 +0000

Logging is more than just writing messages to a file.. it’s the nervous system of your application. It tells you what went wrong, when, and often why. In production systems, logging becomes a lifeline for diagnosing issues, tracking user behavior, and maintaining operational clarity.

But logging isn’t just about volume, it’s about control. Too little, and you’re flying blind. Too much, and you’re drowning in noise.

Enter Serilog, a structured logging library for .NET that brings clarity, flexibility, and power to your logging strategy. Unlike traditional loggers, Serilog treats logs as rich data — not just strings — making it easy to filter, query, and route logs to multiple destinations.

Serilog offers:

Structured logging with named properties
Flexible sinks to write logs to files, consoles, databases, cloud services, and more
Runtime control over log levels
Custom filtering to avoid flooding external systems
Extensibility to integrate your own sinks — log targets

Whether you're debugging a flaky feature or monitoring critical errors in production, in this article, we’ll explore how to achieve control over Serilog — without redeploying or restarting your app.

Utilizing the above features of Serilog, we will explore how to:

Dynamically control Serilog’s log level at runtime using LoggingLevelSwitch
Expose log level control via an admin dashboard or API
Auto-elevate logging during exceptions and revert after a timeout
Push filtered logs to AWS SNS using a custom sink

Runtime Log Level Control

Let's start by configuring Serilog in the application

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console()
    .CreateLogger();

Add a level switch and register it (Dependency Injection)

var levelSwitch = new LoggingLevelSwitch(LogEventLevel.Error);
builder.Services.AddSingleton(levelSwitch);

The Serilog setup will become like:

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.ControlledBy(levelSwitch)
    .WriteTo.Console()
    .WriteTo.File("logs/log.txt")
    .CreateLogger();

Next, use this level switch in the app to control log level when needed:

levelSwitch.MinimumLevel = LogEventLevel.Information;

Exposing Log Level Control via API

Since now we have a switch, we can use or expose it via some API to be invoked directly or from some Admin dashboard.

Define a new controller, or add this to existing admin level set of APIs

[ApiController]
[Route("api/logging")]
public class LoggingController : ControllerBase
{
    private readonly LoggingLevelSwitch _levelSwitch;

    public LoggingController(LoggingLevelSwitch levelSwitch)
    {
        _levelSwitch = levelSwitch;
    }

    [HttpPost("set-level")]
    public IActionResult SetLevel([FromQuery] string level)
    {
        _levelSwitch.MinimumLevel = Enum.Parse<LogEventLevel>(level, true);
        return Ok($"Log level set to {level}");
    }
}

Log Level Control from Admin Dashboard

The above-mentioned API can be invoked from some frontend / dashboard.

A toggle dropdown:

<select onChange={e => setLogLevel(e.target.value)}>
  <option value="Error">Error</option>
  <option value="Information">Information</option>
  <option value="Debug">Debug</option>
</select>

API Call:

const setLogLevel = async (level) => {
  await fetch(`/api/logging/set-level?level=${level}`, { method: "POST" });
};

This will give your team real-time control over logging verbosity.. without redeploys.

Auto-Elevate Logging on Exceptions

Not just via API, we can also use the log level switch silently in our app, for example in case of some fatal error.
Let's use the switch in global exception handler of the app:

public class GlobalExceptionMiddleware
{
    private readonly RequestDelegate _next;
    private readonly LoggingLevelSwitch _levelSwitch;

    public GlobalExceptionMiddleware(RequestDelegate next, LoggingLevelSwitch levelSwitch)
    {
        _next = next;
        _levelSwitch = levelSwitch;
    }

    public async Task Invoke(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (Exception ex)
        {
            _levelSwitch.MinimumLevel = LogEventLevel.Information;

            Log.Error(ex, "Unhandled exception occurred");
            //add elevation message in logs
            Log.Information("Log level elevated to Info");
            _ = Task.Delay(TimeSpan.FromMinutes(5)).ContinueWith(_ =>
            {
                Log.Information("Log level reverted to Error");
                _levelSwitch.MinimumLevel = LogEventLevel.Error;
            });

            context.Response.StatusCode = 500;
            await context.Response.WriteAsync("Something went wrong.");
        }
    }
}

Note: The Log.Information(...) must come before setting the level back to 'Error', or it won’t be emitted.

Don't forget to register the middleware:

app.UseMiddleware<GlobalExceptionMiddleware>();

How can log level elevation help debugging?
We can use Log.Information(...) at different points in our app for traceability, but the log level set to Error will not emit these messages in logs until we change the log level. Then these info messages in logs will help us finding out where things broke, particularly in background jobs.

Setting up and using a Custom Sink

Sink is any target where you want Serilog to send logs to, it can be a file, a message queue or some cloud notification service.
In our example, we will create a sink which will send logs to AWS SNS topic.

public class AwsSnsSink : ILogEventSink
{
    private readonly IAmazonSimpleNotificationService _snsClient;
    private readonly string _topicArn;

    public AwsSnsSink(IAmazonSimpleNotificationService snsClient, string topicArn)
    {
        _snsClient = snsClient;
        _topicArn = topicArn;
    }

    public void Emit(LogEvent logEvent)
    {
        var message = logEvent.RenderMessage();
        _snsClient.PublishAsync(new PublishRequest
        {
            TopicArn = _topicArn,
            Message = $"{logEvent.Timestamp}: {logEvent.Level} - {message}"
        });
    }
}

builder.Services.AddAWSService<IAmazonSimpleNotificationService>();
builder.Services.AddSingleton(levelSwitch);

var snsClient = builder.Services.BuildServiceProvider().GetRequiredService<IAmazonSimpleNotificationService>();
var topicArn = builder.Configuration["AWS:SnsTopicArn"];

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.ControlledBy(levelSwitch)
    .WriteTo.Console()
    .WriteTo.File("logs/log.txt")
    .WriteTo.Sink(new AwsSnsSink(snsClient, topicArn))
    .CreateLogger();

Make sure your AWS credentials and region are configured via environment variables or appsettings.json.

Filtering to Avoid Flooding SNS

Now that we have a custom sink to receive logs, we have to be careful about the cost of that cloud service and not to flood the topic. Too much noise will also be expensive.

We can modify the Emit method of the sink class:

public void Emit(LogEvent logEvent)
{
     if (logEvent.Level < LogEventLevel.Warning) return;

     //continue sending
}

Or we can add the filter in Serilog setup in Program.cs

...
    .WriteTo.Logger(lc => lc
    .Filter.ByIncludingOnly(le => le.Level >= LogEventLevel.Warning)
    WriteTo.Sink(new AwsSnsSink(snsClient, topicArn))
...

This ensures only Warning, Error, and Fatal logs reach SNS — keeping this option cost effective and cloud pipeline lean and meaningful.

Conclusion

With Serilog’s LoggingLevelSwitch, you gain runtime control over logging verbosity. Combine that with custom sinks and smart filtering, and you’ve got a logging pipeline that’s both developer-friendly and production-safe.

Whether you're pushing logs to AWS SNS, Slack, or a custom dashboard, this architecture gives you the flexibility to observe, debug, and scale — without drowning in log noise.

Using JSON data types with .NET EF Core

Aatif G. — Wed, 06 Aug 2025 17:38:42 +0000

Since v7, Entity Framework has provided support for JSON data types in the database, it means we can map JSON to classes and query JSON fields in our Linq queries.
However PostgreSQL has been supporting column type: json since more than a decade, they even have another variant, column type: jsonb.

Here we will not go into details about the difference between json and jsonb: just keep in mind that json is stored as is in string format preserving the fields order and white spaces, but jsonb is stored in binary and it also allows indexing on json fields.

Let's create a small .Net Web API project using PostgreSQL at the backend with some json and jsonb types.
Before starting, take a look at the project dependencies:

First of all, we will create a table in our PostgreSQL db, it will have two special fields, of type json and jsonb.

CREATE TABLE IF NOT EXISTS public."user"
(
    "createdAt" timestamp without time zone NOT NULL DEFAULT now(),
    fullname character varying COLLATE pg_catalog."default",
    email character varying COLLATE pg_catalog."default",
    address json,
    addressb jsonb,
    id bigint NOT NULL GENERATED ALWAYS AS IDENTITY ( INCREMENT 1 START 1 MINVALUE 1 MAXVALUE 9223372036854775807 CACHE 1 )
)

TABLESPACE pg_default;

ALTER TABLE IF EXISTS public."user"
    OWNER to postgres;

Now define the EF model class with sub elements (JSON objects).

public class User : BaseEntity
{
    public string fullname { get; set; }
    public string email { get; set; }
    public Address address { get; set; }
    public Address addressb { get; set; }     
}
public class Address
{
    public string street { get; set; }
    public string city { get; set; }
    public string zipcode { get; set; }
}

For database operations, we will use inheritance to avoid repeated code, basic CRUD operations will be done in a parent service class (GenericService) using parent model class and an interface.
(You can find the base model class/interface in the project folder)

public class DBContext : DbContext
{
    public DbSet<User> user  { get; set; }

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
        => optionsBuilder.UseNpgsql("Connection_String");

}//class

Let's create a new class for database operations, inheriting the parent class.

public class GenericService<Entity> where Entity : class, IBaseEntity
{
    private readonly DBContext _context;

    public GenericService(DBContext dbContext)
    {
        _context = dbContext;
    }

    //Delete the entity by id
    public async Task<bool> Delete(long id)
    {
        try
        {
             var entity = await GetById(id);
             _context.Set<Entity>().Remove(entity);
             var deleteCount = await _context.SaveChangesAsync();

             return deleteCount > 0 ? true : false;
        }
        catch (Exception ex)
        { 
             throw ex; 
        }
    }
}

UserService class will have the methods called by the Controller like GET, PUT, DELETE etc.

public class UserService : GenericService<User>
{
    private readonly DBContext dbcontext;

    public UserService(DBContext dbcontext) : base(dbcontext)
    {
        this.dbcontext = dbcontext;
    }

    public async Task<bool> DeleteUserById(long userId)
    {
        try
        {
            return await Delete(userId);
        }
        catch (Exception ex)
        {
            throw ex;
        }
    }
}

You will notice that we have not done anything specific for the JSON types in the context class yet. We will define the JSON mapping in OnModelCreating() method of the context.

modelBuilder.Entity<User>().OwnsOne(o => o.address, sa =>
{
    sa.ToJson(); // Maps address to a JSON column
});

modelBuilder.Entity<User>().OwnsOne(o => o.addressb, sa =>
{
    sa.ToJson(); // Maps addressb to a JSON column
});

This will allow us to query json fields e.g. zipcode in the address object in our EF code like this:

dbcontext.user.Where(x => x.addressb.zipcode == zip)

We will also follow the same nested object pattern to poplate User object to update or create record in DB.

User? newUser = new();

newUser.addressb = new Address
{
    street = street,
    city = city,
    zipcode = zip
};

newUser.address = new Address
{
    street = street,
    city = city,
    zipcode = zip
};
newUser.email = email;
newUser.fullname = fullname;
newUser.createdAt = DateTime.Now.ToUniversalTime();

await Update(newUser); //Generic method in Parent class

Dependency Injection

We have to define our Context and Service class in Program.cs

builder.Services.AddTransient<DBContext>();
builder.Services.AddTransient<UserService>();

I have added some endpoints to the controller for basic CRUD operations on the User table.

Before closing, here are some observations made while buidling the projest:

The entity / db table must have a primary key.
In some cases, you can also use annotations with type, then you may not need to add .OwnsOne(..) in the Context.

[Column(TypeName = "jsonb")]
public string address { get; set; }

That is it, I hope it will help someone. The project can be downloaded from here.

Want More on .NET 8?

JSON support is one of the many major upgrades brought by .NET 8. Here is more to C# 12 and EF Core 8 which you can read in my .NET 8 breakdown article.

DEV Community: Aatif G.

ElevenLabs vs Deepgram Aura: Text-to-Speech Implementation Guide in .NET 8

Introduction

Interface Definition

ElevenLabs Implementation

Setup

Configuration

Implementation

Deepgram Aura Implementation

Setup

Configuration

Implementation

Dependency Injection Setup

Usage Examples

Basic Text-to-Speech

Streaming Audio via WebSocket

Real-time Conversation with Streaming

Voice Customization

Custom Voice Settings (ElevenLabs)

Audio Post-Processing

Normalize Volume

Format Conversion

Error Handling and Fallback

Caching for Performance

Testing

Performance Benchmarks

Best Practices

Comparison

Related Artciles

OpenAI vs Claude: NLP Implementation Guide in .NET 8

Introduction

Interface Definition

OpenAI GPT Implementation

Setup

Configuration

Implementation

Anthropic Claude Implementation

Setup

Configuration

Implementation

Dependency Injection Setup

Usage Examples

Basic Conversation

Streaming Response

Function Calling Example

Context Management

Error Handling with Retry

Performance Optimization

Caching Common Responses

Testing

Comparison

Related Articles

Deepgram vs AssemblyAI: Speech-to-Text Implementation in .NET 8

Introduction

Deepgram Implementation

Setup

Configuration

Interface Definition

Implementation

AssemblyAI Implementation

Setup

Implementation

Dependency Injection Setup

Usage Example

Error Handling with Fallback

Testing

Performance Tips

Comparison

Related Articles

HierarchyId in SQL Server and EF Core 8 - Modeling Hierarchical Data

🧠 What Is HierarchyId?

🧱 SQL Server Capabilities

🧬 EF Core 8 Integration

✅ Example Model:

✅ Querying Descendants:

🧭 Use Cases

🛠️ Tips for Using HierarchyId

🧾 Final Thoughts

🔍 Want More on .NET 8?

Customizing the Stubborn Int'l Phone

🛠️ Tips for Using `HierarchyId`