• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar
Sas 101

Sas 101

Master the Art of Building Profitable Software

  • Home
  • Terms of Service (TOS)
  • Privacy Policy
  • About Us
  • Contact Us
  • Show Search
Hide Search

.NET 8

Build Stunning Cross-Platform Apps with .NET MAUI

UnknownX · February 1, 2026 · Leave a Comment

Building Production-Ready Cross-Platform Apps with .NET MAUI

 Executive Summary

.NET MAUI solves a critical problem in modern software development: the need to maintain separate codebases for iOS, Android, macOS, and Windows applications. As a .NET developer, you already possess the skills needed to build native mobile and desktop applications—MAUI eliminates the context-switching burden of learning platform-specific languages and frameworks.

This matters for production because it directly impacts time-to-market, maintenance costs, and code quality. A single shared codebase means bug fixes propagate across all platforms simultaneously, feature development accelerates, and your team stays focused on business logic rather than platform plumbing. For enterprise applications, this translates to reduced technical debt and faster iteration cycles.

## Prerequisites

Before starting, ensure your development environment is properly configured:

– **Visual Studio 2026** (or later) with the .NET MAUI workload installed
– **.NET 10.0 SDK** or later
– **Xcode** (latest version) for macOS/iOS development
– **Android SDK** with API level 21 or higher for Android development
– A working understanding of **C# 12+** and **XAML** markup
– Familiarity with **async/await patterns** and dependency injection

Verify your installation by running:

“`csharp
dotnet –version
dotnet workload list
“`

## Step-by-Step Implementation

### Step 1: Create Your First MAUI Project

Open Visual Studio 2026 and follow this workflow:

1. Click **Create a new project**
2. Search for “MAUI App” in the template search bar
3. Select the **.NET MAUI App** template and click **Next**
4. Enter your project name (e.g., `ProductionMauiApp`) and click **Next**
5. Select **.NET 10.0** in the Framework dropdown
6. Click **Create**

Visual Studio generates a single-project structure containing all platform-specific configurations, resources, and shared code. This unified approach is the foundation of MAUI’s power.

### Step 2: Understanding the Project Structure

Your newly created project contains:

“`
ProductionMauiApp/
├── Platforms/
│ ├── Android/
│ ├── iOS/
│ ├── MacCatalyst/
│ └── Windows/
├── Resources/
│ ├── AppIcon/
│ ├── Fonts/
│ ├── Images/
│ └── Styles/
├── App.xaml
├── App.xaml.cs
├── MainPage.xaml
├── MainPage.xaml.cs
├── MauiProgram.cs
└── ProductionMauiApp.csproj
“`

The **Platforms** folder contains platform-specific code that runs only on its target OS. The **Resources** folder centralizes all assets—images, fonts, and styles—managed in a single location rather than duplicated across platforms.

### Step 3: Configure Your Application Shell

The `MauiProgram.cs` file is your application’s composition root. This is where you configure services, register handlers, and initialize your app:

using Microsoft.Maui;
using Microsoft.Maui.Hosting;
using ProductionMauiApp.Services;
using ProductionMauiApp.ViewModels;
using ProductionMauiApp.Views;

namespace ProductionMauiApp;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        
        builder
            .UseMauiApp()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            })
            // Register platform-specific services
            .ConfigureServices()
            // Configure custom handlers for native customization
            .ConfigureHandlers();

        return builder.Build();
    }

    private static MauiAppBuilder ConfigureServices(this MauiAppBuilder builder)
    {
        // Register your services with dependency injection
        builder.Services.AddSingleton<IProductService, ProductService>();
        builder.Services.AddSingleton<INavigationService, NavigationService>();
        builder.Services.AddSingleton();
        builder.Services.AddSingleton();

        return builder;
    }

    private static MauiAppBuilder ConfigureHandlers(this MauiAppBuilder builder)
    {
        #if ANDROID
        builder.ConfigureEffects(effects =>
        {
            // Android-specific handler customizations
        });
        #endif

        #if IOS
        builder.ConfigureEffects(effects =>
        {
            // iOS-specific handler customizations
        });
        #endif

        return builder;
    }
}

### Step 4: Build Your First Page with MVVM Architecture

Create a clean separation between UI and business logic using the Model-View-ViewModel pattern:

**ProductViewModel.cs:**

using System.Collections.ObjectModel;
using System.Windows.Input;

namespace ProductionMauiApp.ViewModels;

public class ProductViewModel : BaseViewModel
{
    private readonly IProductService _productService;
    private ObservableCollection _products;
    private bool _isLoading;
    private string _searchQuery;

    public ObservableCollection Products
    {
        get => _products;
        set => SetProperty(ref _products, value);
    }

    public bool IsLoading
    {
        get => _isLoading;
        set => SetProperty(ref _isLoading, value);
    }

    public string SearchQuery
    {
        get => _searchQuery;
        set
        {
            if (SetProperty(ref _searchQuery, value))
            {
                SearchCommand.Execute(null);
            }
        }
    }

    public ICommand LoadProductsCommand { get; }
    public ICommand SearchCommand { get; }
    public ICommand RefreshCommand { get; }

    public ProductViewModel(IProductService productService)
    {
        _productService = productService;
        Products = new ObservableCollection();

        LoadProductsCommand = new AsyncRelayCommand(LoadProducts);
        SearchCommand = new AsyncRelayCommand(Search);
        RefreshCommand = new AsyncRelayCommand(Refresh);
    }

    private async Task LoadProducts()
    {
        if (IsLoading)
            return;

        try
        {
            IsLoading = true;
            var products = await _productService.GetProductsAsync();
            
            MainThread.BeginInvokeOnMainThread(() =>
            {
                Products.Clear();
                foreach (var product in products)
                {
                    Products.Add(product);
                }
            });
        }
        catch (Exception ex)
        {
            await Application.Current.MainPage.DisplayAlert(
                "Error",
                $"Failed to load products: {ex.Message}",
                "OK");
        }
        finally
        {
            IsLoading = false;
        }
    }

    private async Task Search()
    {
        if (string.IsNullOrWhiteSpace(SearchQuery))
        {
            await LoadProducts();
            return;
        }

        try
        {
            IsLoading = true;
            var results = await _productService.SearchProductsAsync(SearchQuery);
            
            MainThread.BeginInvokeOnMainThread(() =>
            {
                Products.Clear();
                foreach (var product in results)
                {
                    Products.Add(product);
                }
            });
        }
        finally
        {
            IsLoading = false;
        }
    }

    private async Task Refresh()
    {
        SearchQuery = string.Empty;
        await LoadProducts();
    }
}

public abstract class BaseViewModel : INotifyPropertyChanged
{
    public event PropertyChangedEventHandler PropertyChanged;

    protected bool SetProperty(ref T backingStore, T value, 
        [CallerMemberName] string propertyName = "")
    {
        if (EqualityComparer.Default.Equals(backingStore, value))
            return false;

        backingStore = value;
        OnPropertyChanged(propertyName);
        return true;
    }

    protected void OnPropertyChanged([CallerMemberName] string propertyName = "")
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

**ProductPage.xaml:**




    
        
        
        

        
        

        
        
            
            
                
            

            
                
                    
                        
                        
                            
                            
                            

                            
                            
                                
                                
                                
                                
                                
                            
                        
                    
                
            
        

        
        
            
        
    

### Step 5: Implement Platform-Specific Code

MAUI’s handler system maps cross-platform controls to native components. When you need platform-specific behavior, use conditional compilation:

namespace ProductionMauiApp.Platforms.Android;

public partial class MainActivity : MauiAppCompatActivity
{
    protected override void OnCreate(Bundle savedInstanceState)
    {
        base.OnCreate(savedInstanceState);
        
        // Android-specific initialization
        Window.SetStatusBarColor(Android.Graphics.Color.ParseColor("#007AFF"));
    }
}

#if ANDROID
namespace ProductionMauiApp.Services;

public partial class PlatformService
{
    public string GetDeviceIdentifier()
    {
        var androidId = Android.Provider.Settings.Secure.GetString(
            Android.App.Application.Context.ContentResolver,
            Android.Provider.Settings.Secure.AndroidId);
        
        return androidId;
    }
}
#endif

#if IOS
namespace ProductionMauiApp.Services;

public partial class PlatformService
{
    public string GetDeviceIdentifier()
    {
        return UIKit.UIDevice.CurrentDevice.IdentifierForVendor?.AsString() 
            ?? "unknown";
    }
}
#endif

### Step 6: Implement Dependency Injection and Services

Create a robust service layer that abstracts platform differences:

namespace ProductionMauiApp.Services;

public interface IProductService
{
    Task<IEnumerable> GetProductsAsync();
    Task<IEnumerable> SearchProductsAsync(string query);
    Task GetProductByIdAsync(int id);
}

public class ProductService : IProductService
{
    private readonly HttpClient _httpClient;
    private const string BaseUrl = "https://api.example.com";

    public ProductService(HttpClient httpClient)
    {
        _httpClient = httpClient;
        _httpClient.BaseAddress = new Uri(BaseUrl);
        _httpClient.Timeout = TimeSpan.FromSeconds(30);
    }

    public async Task<IEnumerable> GetProductsAsync()
    {
        try
        {
            var response = await _httpClient.GetAsync("/api/products");
            response.EnsureSuccessStatusCode();

            var json = await response.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<IEnumerable>(json) 
                ?? Enumerable.Empty();
        }
        catch (HttpRequestException ex)
        {
            Debug.WriteLine($"HTTP Error: {ex.Message}");
            throw;
        }
    }

    public async Task<IEnumerable> SearchProductsAsync(string query)
    {
        var encodedQuery = Uri.EscapeDataString(query);
        var response = await _httpClient.GetAsync($"/api/products/search?q={encodedQuery}");
        response.EnsureSuccessStatusCode();

        var json = await response.Content.ReadAsStringAsync();
        return JsonSerializer.Deserialize<IEnumerable>(json) 
            ?? Enumerable.Empty();
    }

    public async Task GetProductByIdAsync(int id)
    {
        var response = await _httpClient.GetAsync($"/api/products/{id}");
        response.EnsureSuccessStatusCode();

        var json = await response.Content.ReadAsStringAsync();
        return JsonSerializer.Deserialize(json) 
            ?? throw new InvalidOperationException("Product not found");
    }
}

public record Product(
    int Id,
    string Name,
    string Description,
    decimal Price,
    string ImageUrl);

## Production-Ready C# Examples

### Implementing Resilient HTTP Communication

namespace ProductionMauiApp.Services;

public class ResilientHttpClientFactory
{
    public static HttpClient CreateHttpClient()
    {
        var handler = new HttpClientHandler();

        #if ANDROID
        // Android-specific SSL configuration
        handler.ServerCertificateCustomValidationCallback = (message, cert, chain, errors) =>
        {
            // Implement certificate pinning for production
            return ValidateCertificatePinning(cert);
        };
        #endif

        var client = new HttpClient(handler)
        {
            Timeout = TimeSpan.FromSeconds(30)
        };

        client.DefaultRequestHeaders.Add("User-Agent", GetUserAgent());
        return client;
    }

    private static string GetUserAgent()
    {
        var version = AppInfo.VersionString;
        var platform = DeviceInfo.Platform.ToString();
        return $"ProductionMauiApp/{version} ({platform})";
    }

    private static bool ValidateCertificatePinning(X509Certificate2 cert)
    {
        // Implement your certificate pinning logic
        const string expectedThumbprint = "YOUR_CERT_THUMBPRINT";
        return cert.Thumbprint == expectedThumbprint;
    }
}

// Register in MauiProgram.cs
builder.Services.AddSingleton(ResilientHttpClientFactory.CreateHttpClient());

### Implementing Offline-First Data Synchronization

namespace ProductionMauiApp.Services;

public interface IDataSyncService
{
    Task SyncAsync();
    Task GetAsync(string key);
    Task SetAsync(string key, T value);
}

public class DataSyncService : IDataSyncService
{
    private readonly IProductService _productService;
    private readonly ISecureStorage _secureStorage;
    private readonly IConnectivity _connectivity;

    public DataSyncService(
        IProductService productService,
        ISecureStorage secureStorage,
        IConnectivity connectivity)
    {
        _productService = productService;
        _secureStorage = secureStorage;
        _connectivity = connectivity;
    }

    public async Task SyncAsync()
    {
        if (!_connectivity.NetworkAccess.HasFlag(NetworkAccess.Internet))
        {
            Debug.WriteLine("No internet connection. Using cached data.");
            return;
        }

        try
        {
            var products = await _productService.GetProductsAsync();
            var json = JsonSerializer.Serialize(products);
            await _secureStorage.SetAsync("products_cache", json);
            await _secureStorage.SetAsync("last_sync", DateTime.UtcNow.ToString("O"));
        }
        catch (Exception ex)
        {
            Debug.WriteLine($"Sync failed: {ex.Message}");
        }
    }

    public async Task GetAsync(string key)
    {
        var json = await _secureStorage.GetAsync(key);
        return string.IsNullOrEmpty(json) 
            ? default 
            : JsonSerializer.Deserialize(json);
    }

    public async Task SetAsync(string key, T value)
    {
        var json = JsonSerializer.Serialize(value);
        await _secureStorage.SetAsync(key, json);
    }
}

## Common Pitfalls & Troubleshooting

### Pitfall 1: UI Updates from Background Threads

**Problem:** Updating UI controls from async operations causes crashes.

**Solution:** Always marshal UI updates to the main thread:

// ❌ Wrong
private async Task LoadData()
{
    var data = await _service.GetDataAsync();
    MyLabel.Text = data; // Crash on non-main thread
}

// ✅ Correct
private async Task LoadData()
{
    var data = await _service.GetDataAsync();
    MainThread.BeginInvokeOnMainThread(() =>
    {
        MyLabel.Text = data;
    });
}

### Pitfall 2: Memory Leaks from Event Handlers

**Problem:** Unsubscribed event handlers prevent garbage collection.

**Solution:** Always unsubscribe in `OnDisappearing`:

public partial class MyPage : ContentPage
{
    private void OnPageLoaded(object sender, EventArgs e)
    {
        _viewModel.PropertyChanged += OnPropertyChanged;
    }

    protected override void OnDisappearing()
    {
        base.OnDisappearing();
        _viewModel.PropertyChanged -= OnPropertyChanged;
    }

    private void OnPropertyChanged(object sender, PropertyChangedEventArgs e)
    {
        // Handle property changes
    }
}

### Pitfall 3: Inefficient CollectionView Rendering

**Problem:** Large lists cause performance degradation.

**Solution:** Implement virtualization and use `RecycleElement`:


    
        
    

### Pitfall 4: Platform-Specific Crashes

**Problem:** Code works on one platform but crashes on another.

**Solution:** Test on actual devices and use platform-specific exception handling:

try
{
    #if ANDROID
    var result = await Android.App.Application.Context
        .GetSystemService(Android.Content.Context.SensorService);
    #elif IOS
    var result = UIKit.UIDevice.CurrentDevice.Orientation;
    #endif
}
catch (PlatformNotSupportedException ex)
{
    Debug.WriteLine($"Feature not available on this platform: {ex.Message}");
}

## Performance & Scalability Considerations

### Implement Lazy Loading for Large Datasets

public class LazyLoadingViewModel : BaseViewModel
{
    private readonly IProductService _productService;
    private int _currentPage = 1;
    private const int PageSize = 20;
    private bool _isLoadingMore;

    public ObservableCollection Products { get; } = new();

    public ICommand LoadMoreCommand { get; }

    public LazyLoadingViewModel(IProductService productService)
    {
        _productService = productService;
        LoadMoreCommand = new AsyncRelayCommand(LoadMore);
    }

    private async Task LoadMore()
    {
        if (_isLoadingMore)
            return;

        try
        {
            _isLoadingMore = true;
            var products = await _productService.GetProductsAsync(
                pageNumber: _currentPage,
                pageSize: PageSize);

            MainThread.BeginInvokeOnMainThread(() =>
            {
                foreach (var product in products)
                {
                    Products.Add(product);
                }
            });

            _currentPage++;
        }
        finally
        {
            _isLoadingMore = false;
        }
    }
}

### Optimize Image Loading with Caching

public class CachedImageService
{
    private readonly HttpClient _httpClient;
    private readonly string _cacheDirectory;

    public CachedImageService(HttpClient httpClient)
    {
        _httpClient = httpClient;
        _cacheDirectory = Path.Combine(
            FileSystem.CacheDirectory, 
            "images");
        
        Directory.CreateDirectory(_cacheDirectory);
    }

    public async Task GetImageAsync(string url)
    {
        var fileName = GenerateFileName(url);
        var filePath = Path.Combine(_cacheDirectory, fileName);

        if (File.Exists(filePath))
        {
            return ImageSource.FromFile(filePath);
        }

        try
        {
            var response = await _httpClient.GetAsync(url);
            response.EnsureSuccessStatusCode();

            var bytes = await response.Content.ReadAsByteArrayAsync();
            await File.WriteAllBytesAsync(filePath, bytes);

            return ImageSource.FromStream(() => new MemoryStream(bytes));
        }
        catch (Exception ex)
        {
            Debug.WriteLine($"Image loading failed: {ex.Message}");
            return null;
        }
    }

    private static string GenerateFileName(string url)
    {
        using var sha256 = System.Security.Cryptography.SHA256.Create();
        var hash = sha256.ComputeHash(Encoding.UTF8.GetBytes(url));
        return Convert.ToHexString(hash) + ".jpg";
    }
}

## Practical Best Practices

### 1. Use Dependency Injection Consistently

Always inject dependencies rather than creating instances directly. This enables testing and loose coupling:

// ❌ Avoid
public class ProductViewModel
{
    private readonly IProductService _service = new ProductService();
}

// ✅ Prefer
public class ProductViewModel
{
    private readonly IProductService _service;

    public ProductViewModel(IProductService service)
    {
        _service = service;
    }
}

### 2. Implement Proper Error Handling

public async Task<Result> ExecuteAsync(Func<Task> operation)
{
    try
    {
        var result = await operation();
        return Result.Success(result);
    }
    catch (HttpRequestException ex)
    {
        return Result.Failure($"Network error: {ex.Message}");
    }
    catch (TaskCanceledException ex)
    {
        return Result.Failure("Request timeout");
    }
    catch (Exception ex)
    {
        Debug.WriteLine($"Unexpected error: {ex}");
        return Result.Failure("An unexpected error occurred");
    }
}

public record Result(bool IsSuccess, T Data, string ErrorMessage)
{
    public static Result Success(T data) => new(true, data, null);
    public static Result Failure(string error) => new(false, default, error);
}

### 3. Use Async/Await Properly

// ❌ Avoid blocking calls
public void LoadData()
{
    var data = _service.GetDataAsync().Result; // Deadlock risk
}

// ✅ Use async all the way
public async Task LoadData()
{
    var data = await _service.GetDataAsync();
}

// ✅ For fire-and-forget operations
#pragma warning disable CS4014
_ = LoadDataAsync();
#pragma warning restore CS4014

### 4. Implement Proper Logging

public interface ILogger
{
    void Debug(string message);
    void Info(string message);
    void Warning(string message);
    void Error(string message, Exception ex = null);
}

public class ConsoleLogger : ILogger
{
    public void Debug(string message) => 
        System.Diagnostics.Debug.WriteLine($"[DEBUG] {message}");

    public void Info(string message) => 
        System.Diagnostics.Debug.WriteLine($"[INFO] {message}");

    public void Warning(string message) => 
        System.Diagnostics.Debug.WriteLine($"[WARN] {message}");

    public void Error(string message, Exception ex = null) => 
        System.Diagnostics.Debug.WriteLine($"[ERROR] {message}\n{ex}");
}

## Conclusion

You now have a comprehensive foundation for building production-ready cross-platform applications with .NET MAUI. The key takeaways are:

– **Single codebase, multiple platforms:** Write once, deploy everywhere with native performance
– **MVVM architecture:** Separate concerns cleanly for maintainability and testability
– **Dependency injection:** Build loosely coupled, testable components
– **Platform-specific code:** Use conditional compilation for platform-unique features
– **Performance optimization:** Implement lazy loading, caching, and efficient data binding

Your next steps should be:

1. Build a small prototype application to solidify these concepts
2. Explore MAUI’s handler system for advanced customization
3. Implement unit tests using xUnit or NUnit
4. Deploy to actual devices (Android emulator, iOS simulator, or physical devices)
5. Monitor performance using platform-specific profiling tools

The MAUI ecosystem continues to evolve with each .NET release. Stay current with official documentation and community resources as you scale your applications.

—

## Frequently Asked Questions

### Q1: How do I handle platform-specific UI customization without duplicating code?

Use MAUI’s handler system to customize native controls. Handlers map cross-platform controls to native components, allowing you to modify behavior per-platform:

builder.ConfigureEffects(effects =>
{
    #if ANDROID
    Microsoft.Maui.Handlers.ButtonHandler.Mapper.AppendToMapping(
        "CustomButton", 
        (handler, view) =>
        {
            handler.PlatformView.SetAllCaps(false);
        });
    #endif
});

### Q2: What’s the best way to handle navigation between pages?

Implement a navigation service abstraction to decouple ViewModels from navigation logic:

public interface INavigationService
{
    Task NavigateToAsync(IDictionary<string, object> parameters = null);
    Task GoBackAsync();
}

public class NavigationService : INavigationService
{
    public async Task NavigateToAsync(IDictionary<string, object> parameters = null)
    {
        var route = typeof(TViewModel).Name.Replace("ViewModel", "");
        await Shell.Current.GoToAsync(route);
    }

    public async Task GoBackAsync()
    {
        await Shell.Current.GoToAsync("..");
    }
}

### Q3: How do I secure sensitive data like API keys and tokens?

Use `SecureStorage` for sensitive information:

public class SecureTokenService
{
    public async Task SaveTokenAsync(string token)
    {
        await SecureStorage.SetAsync("auth_token", token);
    }

    public async Task GetTokenAsync()
    {
        return await SecureStorage.GetAsync("auth_token");
    }

    public async Task DeleteTokenAsync()
    {
        SecureStorage.Remove("auth_token");
    }
}

### Q4: How do I test MAUI applications effectively?

Use unit tests for ViewModels and services, and integration tests for UI:

public class ProductViewModelTests
{
    [Fact]
    public async Task LoadProducts_ShouldPopulateCollection()
    {
        // Arrange
        var mockService = new Mock();
        var products = new[] { new Product(1, "Test", "Desc", 9.99m, "") };
        mockService.Setup(s => s.GetProductsAsync())
            .ReturnsAsync(products);

        var viewModel = new ProductViewModel(mockService.Object);

        // Act
        await viewModel.LoadProductsCommand.ExecuteAsync(null);

        // Assert
        Assert.Single(viewModel.Products);
        Assert.Equal("Test", viewModel.Products.Name);
    }
}

### Q5: What’s the difference between Shell and traditional navigation?

Shell provides a hierarchical navigation model with tab and flyout support, while traditional navigation uses a stack-based approach. Shell is recommended for most modern applications:




    
        
        
        
    

### Q6: How do I handle background tasks and long-running operations?

Use `BackgroundService` pattern with proper cancellation tokens:

public class SyncBackgroundService : BackgroundService
{
    private readonly IDataSyncService _syncService;
    private readonly ILogger _logger;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                await _syncService.SyncAsync();
                await Task.Delay(TimeSpan.FromMinutes(15), stoppingToken);
            }
            catch (OperationCanceledException)
            {
                break;
            }
            catch (Exception ex)
            {
                _logger.Error("Sync failed", ex);
            }
        }
    }
}

### Q7: How do I optimize app startup time?

Defer non-critical initialization and use lazy loading:

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        
        builder
            .UseMauiApp()
            // Register only critical services immediately
            .ConfigureServices()
            // Defer heavy initialization
            .ConfigureDeferredServices();

        return builder.Build();
    }

    private static MauiAppBuilder ConfigureDeferredServices(this MauiAppBuilder builder)
    {
        // Register services that can be initialized later
        builder.Services.AddSingleton(
            sp => new AnalyticsService()); // Lazy initialization

        return builder;
    }
}

### Q8: How do I handle different screen sizes and orientations?

Use responsive layouts with `Grid` and `FlexLayout`:


    
    
    
    
    




    
    

### Q9: How do I integrate with native APIs for platform-specific features?

Use partial classes and platform-specific implementations:

// Shared interface
public interface INativeFeatureService
{
    Task GetDeviceInfoAsync();
}

// Shared partial class
public partial class NativeFeatureService : INativeFeatureService
{
    public partial Task GetDeviceInfoAsync();
}

// Android implementation
#if ANDROID
public partial class NativeFeatureService
{
    public partial async Task GetDeviceInfoAsync()
    {
        var deviceId = Android.Provider.Settings.Secure.GetString(
            Android.App.Application.Context.ContentResolver,
            Android.Provider.Settings.Secure.AndroidId);
        
        return await Task.FromResult(deviceId);
    }
}
#endif

// iOS implementation
#if IOS
public partial class NativeFeatureService
{
    public partial async Task GetDeviceInfoAsync()
    {
        var deviceId = UIKit.UIDevice.CurrentDevice.IdentifierForVendor?.AsString();
        return await Task.FromResult(deviceId ?? "unknown");
    }
}
#endif

### Q10: What are the best practices for state management in MAUI?

Use a combination of MVVM, dependency injection, and a state container for complex applications:

public class AppState
{
    public User CurrentUser { get; set; }
    public bool IsAuthenticated { get; set; }
    public List CachedProducts { get; set; } = new();
}

public class StateContainer
{
    private AppState _state = new();
    public event Action OnStateChanged;

    public AppState GetState() => _state;

    public void SetUser(User user)
    {
        _state.CurrentUser = user;
        _state.IsAuthenticated = user != null;
        NotifyStateChanged();
    }

    public void UpdateProducts(List products)
    {
        _state.CachedProducts = products;
        NotifyStateChanged();
    }

    private void NotifyStateChanged() => OnStateChanged?.Invoke();
}

// Register as singleton
builder.Services.AddSingleton();

.NET 8 Enhancements for Performance and AI

The Ultimate Guide to .NET 10 LTS and Performance Optimizations – A Critical Performance Wake-Up Call

AI-Native .NET: Building Intelligent Applications with Azure OpenAI, Semantic Kernel, and ML.NET

Modern Authentication in 2026: How to Secure Your .NET 8 and Angular Apps with Keycloak

UnknownX · January 18, 2026 · Leave a Comment

.NET 8 and Angular Apps with Keycloak


In the rapidly evolving landscape of 2026, identity management has shifted from being a peripheral feature to the backbone of secure system architecture. For software engineers navigating the .NET and Angular ecosystems, the challenge is no longer just “making it work,” but doing so in a way that is scalable, observable, and resilient against modern threats. This guide explores the sophisticated integration of Keycloak with .NET 8, moving beyond basic setup into the architectural nuances that define enterprise-grade security.​

The Shift to Externalized Identity

Traditionally, developers managed user tables and password hashing directly within their application databases. However, the rise of compliance requirements and the complexity of features like Multi-Factor Authentication (MFA) have made internal identity management a liability. Keycloak, an open-source Identity and Access Management (IAM) solution, has emerged as the industry standard for externalizing these concerns.​

By offloading authentication to Keycloak, your .NET 8 services become “stateless” regarding user credentials. They no longer store passwords or handle sensitive login logic. Instead, they trust cryptographically signed JSON Web Tokens (JWTs) issued by Keycloak. This separation of concerns allows your team to focus on business logic while Keycloak manages the heavy lifting of security protocols like OpenID Connect (OIDC) and OAuth 2.0.​

Architectural Patterns for 2026

PatternApplication TypePrimary Benefit
BFF (Backend for Frontend)Angular + .NETSecurely manages tokens without exposing secrets to the browser ​.
Stateless API SecurityMicroservicesValidates JWTs locally for high-performance authorization ​.
Identity BrokeringMulti-Tenant AppsDelegates auth to third parties (Google, Microsoft) via Keycloak ​.

Engineering the Backend: .NET 8 Implementation

The integration starts at the infrastructure level. In .NET 8, the Microsoft.AspNetCore.Authentication.JwtBearer library remains the primary tool for securing APIs. Modern implementations require a deep integration with Keycloak’s specific features, such as role-based access control (RBAC) and claim mapping.​

Advanced Service Registration

In your Program.cs, the configuration must be precise. You aren’t just checking if a token exists; you are validating its issuer, audience, and the validity of the signing keys.

csharpbuilder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = builder.Configuration["Keycloak:Authority"];
        options.Audience = builder.Configuration["Keycloak:ClientId"];
        options.RequireHttpsMetadata = false; 
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = builder.Configuration["Keycloak:Authority"],
            ValidateAudience = true,
            ValidateLifetime = true
        };
    });

This configuration ensures that your .NET API automatically fetches the public signing keys from Keycloak’s .well-known/openid-configuration endpoint, allowing for seamless key rotation without manual intervention.​

Bridging the Gap: Angular and Keycloak

For an Angular developer, the goal is a seamless User Experience (UX). Using the Authorization Code Flow with PKCE (Proof Key for Code Exchange) is the only recommended way to secure Single Page Applications (SPAs) in 2026. This flow prevents interception attacks and ensures that tokens are only issued to the legitimate requester.​

Angular Bootstrapping

Integrating the keycloak-angular library allows the frontend to manage the login state efficiently. The initialization should occur at the application startup:​

typescriptfunction initializeKeycloak(keycloak: KeycloakService) {
  return () =>
    keycloak.init({
      config: {
        url: 'http://localhost:8080',
        realm: 'your-realm',
        clientId: 'angular-client'
      },
      initOptions: {
        onLoad: 'check-sso',
        silentCheckSsoRedirectUri: window.location.origin + '/assets/silent-check-sso.html'
      }
    });
}

When a user is redirected back to the Angular app after a successful login, the application receives an access_token. This token is then appended to the Authorization header of every subsequent HTTP request made to the .NET backend using an Angular Interceptor.​

DIY Tutorial: Implementing Secure Guards

To protect specific routes, such as an admin dashboard, you can implement a KeycloakAuthGuard. This guard checks if the user is logged in and verifies if they possess the required roles defined in Keycloak.​

typescript@Injectable({ providedIn: 'root' })
export class AuthGuard extends KeycloakAuthGuard {
  constructor(protected override readonly router: Router, protected readonly keycloak: KeycloakService) {
    super(router, keycloak);
  }

  public async isAccessAllowed(route: ActivatedRouteSnapshot, state: RouterStateSnapshot) {
    if (!this.authenticated) {
      await this.keycloak.login({ redirectUri: window.location.origin + state.url });
    }
    const requiredRoles = route.data['roles'];
    if (!requiredRoles || requiredRoles.length === 0) return true;
    return requiredRoles.every((role) => this.roles.includes(role));
  }
}

Customizing Keycloak: The User Storage SPI

One of the most powerful features for enterprise developers is the User Storage Service Provider Interface (SPI). If you are migrating a legacy system where users are already stored in a custom SQL Server database, you don’t necessarily have to migrate them to Keycloak’s internal database.​

By implementing a custom User Storage Provider in Java, you can make Keycloak “see” your existing .NET database as a user source. This allows you to leverage Keycloak’s security features while maintaining your original data structure for legal or enterprise projects.​

Real-World Implementation: The Reference Repository

To see these concepts in action, the Black-Cockpit/NETCore.Keycloak repository serves as an excellent benchmark. It demonstrates:​

  • Automated Token Management: Handling the lifecycle of access and refresh tokens.​
  • Fine-Grained Authorization: Using Keycloak’s UMA 2.0 to define complex permission structures.​
  • Clean Architecture Integration: How to cleanly separate security configuration from your domain logic.​

Conclusion

Integrating Keycloak with .NET 8 and Angular is not merely a technical task; it is a strategic architectural decision. By adopting OIDC and externalized identity, you ensure that your applications are built on a foundation of “Security by Design”. As we move through 2026, the ability to orchestrate these complex identity flows will remain a hallmark of high-level full-stack engineering.​

You might be interested in

Building Modern .NET Applications with C# 12+: The Game-Changing Features You Can’t Ignore (and Old Pain You’ll Never Go Back To)

The Ultimate Guide to .NET 10 LTS and Performance Optimizations – A Critical Performance Wake-Up Call

Building Modern .NET Applications with C# 12+: The Game-Changing Features You Can’t Ignore (and Old Pain You’ll Never Go Back To)

UnknownX · January 15, 2026 · Leave a Comment

Modern .NET development keeps pushing toward simplicity, clarity, and performance. With C# 12+, developers can eliminate noisy constructors, streamline collection handling, and write APIs that feel effortless to maintain. Developers building modern .NET applications with C# 12 gain immediate benefits from clearer syntax and reduced boilerplate.

By adopting features like primary constructors, collection expressions, params collections, and inline arrays, teams routinely cut 30–40% of ceremony out of codebases while keeping enterprise scalability intact.

Why Build Modern .NET Applications with C# 12?

Modern .NET applications with C# 12 allow teams to write cleaner, more efficient code without the structural noise that older C# versions required.

Prerequisites for Building Modern .NET Applications with C# 12

Tools Required

  • Visual Studio 2022 or VS Code + C# Dev Kit
  • .NET 8 SDK (C# 12)
  • .NET 10 SDK (future-ready)

Recommended NuGet Packages

dotnet add package Microsoft.AspNetCore.OpenApi
dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.SqlServer

Knowledge Required

  • Dependency injection
  • ASP.NET Core
  • LINQ and lambdas
  • EF Core basics

Primary Constructors: Transforming Modern .NET Applications with C# 12

Old DI Pattern (Verbose)

public class UserService
{
    private readonly IUserRepository _userRepository;
    private readonly ILogger&lt;UserService&gt; _logger;
    private readonly IEmailService _emailService;

    public UserService(
        IUserRepository userRepository,
        ILogger&lt;UserService&gt; logger,
        IEmailService emailService)
    {
        _userRepository = userRepository;
        _logger = logger;
        _emailService = emailService;
    }

    public async Task CreateUserAsync(string email)
    {
        _logger.LogInformation($"Creating user: {email}");
        await _userRepository.AddAsync(new User { Email = email });
        await _emailService.SendWelcomeEmailAsync(email);
    }
}

Modern Primary Constructor (Clean C# 12)

public class UserService(
    IUserRepository userRepository,
    ILogger&lt;UserService&gt; logger,
    IEmailService emailService)
{
    public async Task&lt;User&gt; CreateUserAsync(string email)
    {
        logger.LogInformation($"Creating user: {email}");

        var user = new User { Email = email };
        await userRepository.AddAsync(user);
        await emailService.SendWelcomeEmailAsync(email);

        return user;
    }

    public Task&lt;User?&gt; GetUserAsync(int id) =>
        userRepository.GetByIdAsync(id);
}

Real Business Logic Example

public class OrderProcessor(
    IOrderRepository orderRepository,
    IPaymentService paymentService,
    ILogger&lt;OrderProcessor&gt; logger)
{
    private const decimal MinimumOrderAmount = 10m;

    public async Task&lt;OrderResult&gt; ProcessOrderAsync(Order order)
    {
        if (order.TotalAmount &lt; MinimumOrderAmount)
        {
            logger.LogWarning(
                $"Order amount {order.TotalAmount} below minimum");
            return OrderResult.Failure("Order amount too low");
        }

        try
        {
            var payment = await paymentService.ChargeAsync(order.TotalAmount);

            if (!payment.IsSuccessful)
            {
                logger.LogError($"Payment failed: {payment.ErrorMessage}");
                return OrderResult.Failure(payment.ErrorMessage);
            }

            order.Status = OrderStatus.Paid;
            await orderRepository.UpdateAsync(order);

            logger.LogInformation($"Order {order.Id} processed successfully");
            return OrderResult.Success(order);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Unexpected error processing order");
            return OrderResult.Failure("Unexpected error occurred");
        }
    }
}

Collection Expressions in Modern .NET Applications with C# 12

Old Collection Syntax

int[] numbers = new int[] { 1, 2, 3, 4, 5 };
List&lt;string&gt; names = new List&lt;string&gt; { "Alice", "Bob", "Charlie" };
int[][] jagged = new int[][]
{
    new int[] { 1, 2 },
    new int[] { 3, 4 }
};

Modern C# 12 Syntax

int[] numbers = [1, 2, 3, 4, 5];
List&lt;string&gt; names = ["Alice", "Bob", "Charlie"];
int[][] jagged = [[1, 2], [3, 4]];

Spread Syntax

int[] row0 = [1, 2, 3];
int[] row1 = [4, 5, 6];
int[] row2 = [7, 8, 9];

int[] combined = [..row0, ..row1, ..row2];

Real API Example

public class ProductService(IProductRepository repository)
{
    public async Task&lt;ProductListResponse&gt; GetFeaturedProductsAsync()
    {
        var products = await repository.GetFeaturedAsync();

        return new ProductListResponse
        {
            Products =
            [
                ..products.Select(p => new ProductDto(
                    p.Id, p.Name, p.Price, [..p.Tags]))
            ],
            TotalCount = products.Count,
            Categories = ["Electronics", "Clothing", "Books"]
        };
    }
}

public record ProductDto(int Id, string Name, decimal Price, List&lt;string&gt; Tags);

public record ProductListResponse
{
    public required List&lt;ProductDto&gt; Products { get; init; }
    public required int TotalCount { get; init; }
    public required List&lt;string&gt; Categories { get; init; }
}

Minimal APIs in Modern .NET Applications with C# 12

Old Minimal API


app.MapPost("/users",
    async (CreateUserRequest request, UserService service) =>
{
    var user = await service.CreateUserAsync(request.Email);
    return Results.Created($"/users/{user.Id}", user);
});

Modern Minimal API With Metadata


app.MapPost("/users", async (
    [FromBody] CreateUserRequest request,
    [FromServices] UserService service,
    [FromServices] ILogger&lt;UserService&gt; logger) =>
{
    logger.LogInformation($"Creating user: {request.Email}");

    var user = await service.CreateUserAsync(request.Email);
    return Results.Created($"/users/{user.Id}", user);
})
.WithName("CreateUser")
.WithOpenApi()
.Produces(StatusCodes.Status201Created)
.Produces(StatusCodes.Status400BadRequest);

Inline Arrays (Performance Boost in Modern .NET Applications with C# 12)


[System.Runtime.CompilerServices.InlineArray(10)]
public struct IntBuffer
{
    private int _element0;
}

public class DataProcessor
{
    public void ProcessBatch(ReadOnlySpan&lt;int&gt; data)
    {
        var buffer = new IntBuffer();

        for (int i = 0; i &lt; data.Length &amp;&amp; i &lt; 10; i++)
            buffer[i] = data[i];

        foreach (var item in buffer)
            Console.WriteLine(item);
    }
}

Final Thoughts on Modern .NET Applications with C# 12

With C# 12+, enterprise .NET apps benefit from:
✔ Less boilerplate
✔ Cleaner collections
✔ Metadata-rich lambdas
✔ Higher performance

By integrating these language features, teams building modern .NET applications with C# 12 unlock easier code maintenance, faster development, and fewer bugs.

You might be interested in

The Ultimate Guide to .NET 10 LTS and Performance Optimizations – A Critical Performance Wake-Up Call

AI-Native .NET: Building Intelligent Applications with Azure OpenAI, Semantic Kernel, and ML.NET

Master Effortless Cloud-Native .NET Microservices Using DAPR, gRPC & Azure Kubernetes Service

🟣 Microsoft Official Docs

➡ C# 12 Language Features
https://learn.microsoft.com/dotnet/csharp/whats-new/csharp-12

➡ Minimal APIs (.NET 8)
https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis

➡ Primary Constructors Proposal
https://learn.microsoft.com/dotnet/csharp/language-reference/proposals/csharp-12.0/primary-constructors

Powerful AI-First .NET Backend Engineering for High-Throughput APIs (ONNX, Vector Search, Semantic Features)

UnknownX · January 11, 2026 · Leave a Comment

AI-First .NET 8 Backend for High-Throughput Semantic APIs (ONNX, Vector Search, Embeddings)

Executive Summary

AI-First .NET backend – We’ll build a high-throughput, AI-first .NET 8 backend that:

  • Uses an ONNX embedding model to convert text into vectors.
  • Stores those vectors in a vector database (e.g., Qdrant/pgvector or in-memory for demo).
  • Exposes production-ready HTTP APIs for semantic search, recommendations, and similarity matching.
  • Is implemented in modern C# (records, minimal APIs, DI, async, efficient memory usage).

This solves a real production problem: how to serve semantic capabilities (search, RAG, personalization, anomaly detection) from your existing .NET services without routing every request through a cloud LLM provider. You get:

  • Low latency: ONNX Runtime is highly optimized and runs in-process.
  • Cost control: Once the model is deployed, inference cost is predictable.
  • Data control: Vectors and documents stay inside your infrastructure.
  • Composable APIs: You can layer semantic features into any bounded context.

Prerequisites

Tools & Runtime

  • .NET 8 SDK installed.
  • Visual Studio 2022 / Rider / VS Code with C# extension.
  • ONNX Runtime available as a NuGet package.
  • Optionally: a running Qdrant or PostgreSQL + pgvector instance.

NuGet Packages

In your Web API project, add:

  • Microsoft.ML.OnnxRuntime – core ONNX inference.
  • Microsoft.ML.OnnxRuntime.Managed – CPU-only runtime (simpler deployment) or provider-specific packages if you want GPU.
  • System.Text.Json – built-in, but we’ll tweak options.
  • Dapper (if using pgvector + PostgreSQL for storage).
  • Qdrant.Client (if using Qdrant; or you can call its REST API directly with HttpClient).

Model & Data

  • A sentence embedding ONNX model (e.g., a BGE, MiniLM, or similar model exported to ONNX).
  • Text documents (product descriptions, knowledge base articles, etc.) to index.

Step-by-Step Implementation

Step 1: Project Setup

Create a new .NET 8 Web API (minimal APIs) project:

dotnet new webapi -n SemanticBackend
cd SemanticBackend

Edit SemanticBackend.csproj to target .NET 8 and add packages:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.ML.OnnxRuntime" Version="1.20.0" />
    <PackageReference Include="Microsoft.ML.OnnxRuntime.Managed" Version="1.20.0" />
    <PackageReference Include="Dapper" Version="2.1.35" />
    <PackageReference Include="Qdrant.Client" Version="3.5.0" />
  </ItemGroup>
</Project>

Place your ONNX model file under ./Models/embeddings.onnx and mark it as Copy if newer in the .csproj:

<ItemGroup>
  <None Include="Models\embeddings.onnx" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

Step 2: Define Core Domain Types

We’ll focus on a simple domain: documents with semantic search.

namespace SemanticBackend.Documents;

public sealed record Document(
    Guid Id,
    string ExternalId,
    string Title,
    string Content,
    float[] Embedding,
    DateTimeOffset CreatedAt);

For API DTOs:

namespace SemanticBackend.Api;

public sealed record IndexDocumentRequest(
    string ExternalId,
    string Title,
    string Content);

public sealed record SearchRequest(
    string Query,
    int TopK = 5);

public sealed record SearchResult(
    Guid Id,
    string ExternalId,
    string Title,
    string Content,
    double Score);

Step 3: Implement an ONNX Embedding Service

This service will:

  • Load the ONNX model once at startup.
  • Preprocess text (tokenization can be done outside ONNX or inside, depending on the model).
  • Run inference and return a normalized embedding vector.

Basic abstraction:

namespace SemanticBackend.Embeddings;

public interface IEmbeddingGenerator
{
    ValueTask<float[]> GenerateAsync(string text, CancellationToken ct = default);
}

ONNX-based implementation (simplified – assumes the model takes a single input tensor already preprocessed; you can extend this to include tokenization or use a model exported with pre/post processing baked in):

using System.Numerics;
using Microsoft.ML.OnnxRuntime;
using Microsoft.ML.OnnxRuntime.Tensors;

namespace SemanticBackend.Embeddings;

public sealed class OnnxEmbeddingGenerator : IEmbeddingGenerator, IAsyncDisposable
{
    private readonly InferenceSession _session;
    private readonly string _inputName;
    private readonly string _outputName;

    public OnnxEmbeddingGenerator(string modelPath)
    {
        // Configure session options (CPU, threads, graph optimizations)
        var options = new SessionOptions
        {
            GraphOptimizationLevel = GraphOptimizationLevel.ORT_ENABLE_ALL
        };
        options.EnableMemoryPattern = true;

        _session = new InferenceSession(modelPath, options);

        // Inspect model metadata for input/output names if needed.
        _inputName = _session.InputMetadata.Keys.First();
        _outputName = _session.OutputMetadata.Keys.First();
    }

    public ValueTask<float[]> GenerateAsync(string text, CancellationToken ct = default)
    {
        // You would normally do proper tokenization here or call a model
        // that encapsulates tokenization in the ONNX graph.
        // For demo, we assume an external process provides us with a fixed-size input vector.
        // Replace this with real tokenization for a production system.

        // Example: fake tokenization into a fixed-length float vector
        const int inputLength = 128;
        var inputTensor = new DenseTensor<float>(new[] { 1, inputLength });

        var span = inputTensor.Buffer.Span;
        span.Clear();

        // SUPER simplified: map chars to floats
        var length = Math.Min(text.Length, inputLength);
        for (var i = 0; i < length; i++)
        {
            span[i] = text[i] % 128; // safe demo mapping
        }

        var inputs = new List<NamedOnnxValue>
        {
            NamedOnnxValue.CreateFromTensor(_inputName, inputTensor)
        };

        using var results = _session.Run(inputs);
        var outputTensor = results.First(v => v.Name == _outputName).AsTensor<float>();

        var embedding = outputTensor.ToArray();
        NormalizeInPlace(embedding);

        return ValueTask.FromResult(embedding);
    }

    private static void NormalizeInPlace(Span<float> vector)
    {
        var length = vector.Length;
        if (length == 0) return;

        // Use double accumulator to minimize rounding
        double sumSquares = 0;
        for (var i = 0; i < length; i++)
        {
            var v = vector[i];
            sumSquares += (double)v * v;
        }

        var norm = Math.Sqrt(sumSquares);
        if (norm < 1e-12) return;

        var inv = (float)(1.0 / norm);
        for (var i = 0; i < length; i++)
        {
            vector[i] *= inv;
        }
    }

    public ValueTask DisposeAsync()
    {
        _session.Dispose();
        return ValueTask.CompletedTask;
    }
}

Note: In production, you should plug in a real tokenizer and model-specific pre/post-processing. The overall pattern remains the same.

Step 4: Implement a Vector Store Abstraction

We want the rest of the code to be independent of the specific database implementation.

namespace SemanticBackend.VectorStore;

using SemanticBackend.Documents;

public interface IVectorStore
{
    Task IndexAsync(Document document, CancellationToken ct = default);

    Task<IReadOnlyList<(Document Document, double Score)>> SearchAsync(
        float[] queryEmbedding,
        int topK,
        CancellationToken ct = default);
}

Step 5: In-Memory Vector Store (for Fast Iteration)

We’ll start with an in-memory store implementing cosine similarity. This is great for local development and testing.

using System.Collections.Concurrent;
using SemanticBackend.Documents;

namespace SemanticBackend.VectorStore;

public sealed class InMemoryVectorStore : IVectorStore
{
    private readonly ConcurrentDictionary<Guid, Document> _documents = new();

    public Task IndexAsync(Document document, CancellationToken ct = default)
    {
        _documents[document.Id] = document;
        return Task.CompletedTask;
    }

    public Task<IReadOnlyList<(Document Document, double Score)>> SearchAsync(
        float[] queryEmbedding,
        int topK,
        CancellationToken ct = default)
    {
        if (_documents.Count == 0)
        {
            return Task.FromResult<IReadOnlyList<(Document, double)>>
                (Array.Empty<(Document, double)>());
        }

        // Cosine similarity: dot(a, b) / (|a| * |b|), but since vectors
        // are normalized, this is just dot(a, b).
        var results = new List<(Document, double)>(_documents.Count);

        foreach (var doc in _documents.Values)
        {
            var score = Dot(queryEmbedding, doc.Embedding);
            results.Add((doc, score));
        }

        var top = results
            .OrderByDescending(r => r.Item2)
            .Take(topK)
            .ToArray();

        return Task.FromResult<IReadOnlyList<(Document, double)>>(top);
    }

    private static double Dot(ReadOnlySpan<float> a, ReadOnlySpan<float> b)
    {
        if (a.Length != b.Length)
        {
            throw new InvalidOperationException(
                $"Vector dimension mismatch: {a.Length} vs {b.Length}.");
        }

        var sum = 0.0;
        for (var i = 0; i < a.Length; i++)
        {
            sum += a[i] * b[i];
        }

        return sum;
    }
}

Step 6: Qdrant Vector Store (Production-Style Example)

Let’s add a Qdrant-backed store to illustrate real vector DB usage. We assume a collection with vector_size equal to your embedding dimension and appropriate distance metric (cosine).

using Qdrant.Client;
using Qdrant.Client.Grpc;
using SemanticBackend.Documents;

namespace SemanticBackend.VectorStore;

public sealed class QdrantVectorStore : IVectorStore
{
    private readonly QdrantClient _client;
    private readonly string _collectionName;
    private readonly int _dimension;

    public QdrantVectorStore(QdrantClient client, string collectionName, int dimension)
    {
        _client = client;
        _collectionName = collectionName;
        _dimension = dimension;
    }

    public async Task IndexAsync(Document document, CancellationToken ct = default)
    {
        if (document.Embedding.Length != _dimension)
        {
            throw new InvalidOperationException(
                $"Vector dimension mismatch: expected {_dimension}, got {document.Embedding.Length}.");
        }

        var payload = new Dictionary<string, object?>
        {
            ["externalId"] = document.ExternalId,
            ["title"] = document.Title,
            ["content"] = document.Content,
            ["createdAt"] = document.CreatedAt
        };

        var point = new PointStruct
        {
            Id = document.Id.ToString(),
            Vectors = new Vectors
            {
                Vector_ = { document.Embedding.Select(v => (double)v) }
            },
            Payload = { payload.ToStruct() }
        };

        await _client.UpsertAsync(
            _collectionName,
            new[] { point },
            cancellationToken: ct);
    }

    public async Task<IReadOnlyList<(Document Document, double Score)>> SearchAsync(
        float[] queryEmbedding,
        int topK,
        CancellationToken ct = default)
    {
        var searchPoints = await _client.SearchAsync(
            _collectionName,
            queryEmbedding.Select(v => (double)v),
            topK,
            withPayload: true,
            cancellationToken: ct);

        var results = new List<(Document, double)>(searchPoints.Count);

        foreach (var point in searchPoints)
        {
            var payload = point.Payload?.Fields ?? new Dictionary<string, Google.Protobuf.WellKnownTypes.Value>();

            var externalId = payload.TryGetValue("externalId", out var extVal)
                ? extVal.StringValue
                : string.Empty;

            var title = payload.TryGetValue("title", out var titleVal)
                ? titleVal.StringValue
                : string.Empty;

            var content = payload.TryGetValue("content", out var contentVal)
                ? contentVal.StringValue
                : string.Empty;

            var createdAt = payload.TryGetValue("createdAt", out var createdVal)
                ? DateTimeOffset.Parse(createdVal.StringValue)
                : DateTimeOffset.UtcNow;

            // For many APIs, the original vector is not returned; you might not need it
            // for read scenarios. For simplicity, we reuse the query embedding.
            var doc = new Document(
                Guid.Parse(point.Id.StringValue),
                externalId,
                title,
                content,
                queryEmbedding,
                createdAt);

            results.Add((doc, point.Score));
        }

        return results;
    }
}

Note: The ToStruct() extension is straightforward to implement using Google.Protobuf.WellKnownTypes.Struct if your Qdrant client doesn’t already provide helpers.

Step 7: Application Service Layer

Now we compose the embedding generator with the vector store into a use-case–centric service.

using SemanticBackend.Api;
using SemanticBackend.Documents;
using SemanticBackend.Embeddings;
using SemanticBackend.VectorStore;

namespace SemanticBackend.Application;

public interface IDocumentService
{
    Task<Guid> IndexAsync(IndexDocumentRequest request, CancellationToken ct = default);

    Task<IReadOnlyList<SearchResult>> SearchAsync(SearchRequest request, CancellationToken ct = default);
}

public sealed class DocumentService(IEmbeddingGenerator embeddings, IVectorStore store)
    : IDocumentService
{
    public async Task<Guid> IndexAsync(IndexDocumentRequest request, CancellationToken ct = default)
    {
        var embedding = await embeddings.GenerateAsync(request.Content, ct);

        var document = new Document(
            Id: Guid.NewGuid(),
            ExternalId: request.ExternalId,
            Title: request.Title,
            Content: request.Content,
            Embedding: embedding,
            CreatedAt: DateTimeOffset.UtcNow);

        await store.IndexAsync(document, ct);

        return document.Id;
    }

    public async Task<IReadOnlyList<SearchResult>> SearchAsync(SearchRequest request, CancellationToken ct = default)
    {
        var queryEmbedding = await embeddings.GenerateAsync(request.Query, ct);
        var matches = await store.SearchAsync(queryEmbedding, request.TopK, ct);

        return matches
            .Select(m => new SearchResult(
                m.Document.Id,
                m.Document.ExternalId,
                m.Document.Title,
                m.Document.Content,
                m.Score))
            .ToArray();
    }
}

Step 8: Wire Everything in Program.cs (Minimal API)

Now we expose REST endpoints using minimal APIs.

using Microsoft.AspNetCore.Http.HttpResults;
using SemanticBackend.Api;
using SemanticBackend.Application;
using SemanticBackend.Embeddings;
using SemanticBackend.VectorStore;
using Qdrant.Client;

var builder = WebApplication.CreateBuilder(args);

// Configuration
var configuration = builder.Configuration;

var modelPath = Path.Combine(AppContext.BaseDirectory, "Models", "embeddings.onnx");
const int embeddingDimension = 384; // Adjust to your model

// DI registrations
builder.Services.AddSingleton<IEmbeddingGenerator>(_ => new OnnxEmbeddingGenerator(modelPath));

// Choose one vector store implementation.
// For local/dev:
builder.Services.AddSingleton<IVectorStore, InMemoryVectorStore>();

// For Qdrant (comment the above and uncomment these):
// var qdrantUri = configuration.GetValue<string>("Qdrant:Url") ?? "http://localhost:6334";
// var qdrantCollection = configuration.GetValue<string>("Qdrant:Collection") ?? "documents";
// builder.Services.AddSingleton(new QdrantClient(qdrantUri));
// builder.Services.AddSingleton<IVectorStore>(sp =>
// {
//     var client = sp.GetRequiredService<QdrantClient>();
//     return new QdrantVectorStore(client, qdrantCollection, embeddingDimension);
// });

builder.Services.AddScoped<IDocumentService, DocumentService>();

builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.PropertyNamingPolicy = null;
    options.SerializerOptions.WriteIndented = false;
});

var app = builder.Build();

app.MapPost("/documents/index", async Task<Results<Ok<Guid>, BadRequest<string>>> (
    IndexDocumentRequest request,
    IDocumentService service,
    CancellationToken ct) =>
{
    if (string.IsNullOrWhiteSpace(request.Content))
    {
        return TypedResults.BadRequest("Content must not be empty.");
    }

    var id = await service.IndexAsync(request, ct);
    return TypedResults.Ok(id);
});

app.MapPost("/documents/search", async Task<Ok<IReadOnlyList<SearchResult>>> (
    SearchRequest request,
    IDocumentService service,
    CancellationToken ct) =>
{
    if (string.IsNullOrWhiteSpace(request.Query))
    {
        return TypedResults.Ok(Array.Empty<SearchResult>());
    }

    var results = await service.SearchAsync(request, ct);
    return TypedResults.Ok(results);
});

app.Run();

You now have:

  • POST /documents/index – index a document (compute embedding + store in vector DB).
  • POST /documents/search – semantic search over indexed documents.

Step 9: Semantic Features: RAG-style Answering (Optional but Powerful)

Once you have semantic search, layering retrieval-augmented generation (RAG) becomes straightforward. Instead of returning the documents, you can compose them into a prompt for an LLM (local ONNX LLM or remote provider).

Example service method (pseudo-LLM call):

public sealed class RagService(IDocumentService documents, IChatModel chatModel)
{
    public async Task<string> AskAsync(string question, CancellationToken ct = default)
    {
        var searchResults = await documents.SearchAsync(
            new SearchRequest(question, TopK: 5), ct);

        var context = string.Join("\n\n", searchResults.Select(r =>
            $"Title: {r.Title}\nContent: {r.Content}"));

        var prompt = $"""
        You are a helpful assistant. Answer the question based only on the context.

        Context:
        {context}

        Question: {question}
        """;

        var answer = await chatModel.CompleteAsync(prompt, ct);
        return answer;
    }
}

Where IChatModel could be implemented using another ONNX model (e.g., Phi-3) or a cloud provider.

Production-Ready C# Patterns & Examples

Pattern: Batching Embedding Requests

For high throughput, you want to batch embeddings whenever possible.

public interface IBatchEmbeddingGenerator
{
    ValueTask<float[][]> GenerateBatchAsync(
        IReadOnlyList<string> texts,
        CancellationToken ct = default);
}

Inside your ONNX implementation, you can create a tensor of shape [batchSize, sequenceLength] and run a single _session.Run() call, then split the output tensor into separate vectors per item. This significantly improves throughput when handling many small requests (e.g., indexing jobs).

Pattern: Background Indexing

Use a background queue for indexing to reduce latency on the write path:

public sealed class IndexingBackgroundService(
    Channel<IndexDocumentRequest> channel,
    IDocumentService documentService,
    ILogger<IndexingBackgroundService> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var request in channel.Reader.ReadAllAsync(stoppingToken))
        {
            try
            {
                await documentService.IndexAsync(request, stoppingToken);
            }
            catch (Exception ex)
            {
                logger.LogError(ex, "Error indexing document {ExternalId}", request.ExternalId);
            }
        }
    }
}

Common Pitfalls & Troubleshooting

1. Vector Dimension Mismatch

Symptom: Errors like “vector dimension mismatch” or “expected dim X, got Y”.

Cause: Your model outputs a vector of dimension N, but your vector DB or code assumes a different size.

Fix:

  • Determine the embedding dimension once (inspect the ONNX output tensor shape).
  • Store that dimension in configuration and enforce it in the vector store (as shown in QdrantVectorStore).

2. ONNX Runtime Native Dependencies

Symptom: App fails to start with missing DLL or shared library errors.

Cause: Native ONNX Runtime binaries missing for your platform.

Fix:

  • Use Microsoft.ML.OnnxRuntime.Managed for CPU-only deployments to avoid native dependency complexity.
  • If using GPU or specific providers, ensure the correct runtime package is added and native libraries are present in your container or host.

3. Latency Spikes on First Request

Symptom: First inference is slow (model load, JIT, etc.).

Fix:

  • Warm up ONNX at startup by running a single dummy inference in the OnnxEmbeddingGenerator constructor or via IHostedService.

4. High Memory Usage

Symptom: Memory grows with concurrent requests.

Causes: Large allocations per request, no reuse of buffers, unbounded caching.

Fix:

  • Reuse tensors and buffers via pooling where possible.
  • Return only needed data to clients (avoid sending embeddings over the wire).
  • Use structs or readonly records for value types and avoid unnecessary copies.

5. Inaccurate or Poor-Quality Results

Symptom: Semantic search results look random or irrelevant.

Causes: Wrong model type, missing normalization, bad pre-processing.

Fix:

  • Use a model trained for sentence embeddings, not classification.
  • Normalize embeddings to unit length before storing.
  • Ensure the same pre-processing is used for indexing and querying.

Performance & Scalability Considerations

1. Horizontal Scaling

  • Deploy multiple instances of the API behind a load balancer.
  • Keep the vector store external (Qdrant/pgvector) so any instance can serve queries.
  • Ensure ONNX model loading is instance-local, but the model file is part of your container image.

2. Concurrency & Threading

  • ONNX InferenceSession is safe for concurrent use in many scenarios; use a singleton per model.
  • Limit max degree of parallelism via configuration if CPU saturates; you can wrap embeddings calls in a semaphore to protect CPU.

3. Caching

  • Cache embeddings for frequently queried texts (e.g., by hashing the text and storing the vector in a cache layer).
  • Cache search results for popular queries with a short TTL.

4. Indexing Strategy

  • Bulk index documents offline before flipping traffic for new datasets.
  • Use batch APIs for your vector DB to reduce network overhead.

5. Observability

  • Emit metrics: inference latency, search latency, QPS, error rates, queue depth for background indexing.
  • Log only necessary data (avoid raw embeddings in logs).

Practical Best Practices

1. Separate Concerns Clearly

  • Embedding generation is an infrastructure concern (ONNX).
  • Vector storage/search is another infrastructure boundary.
  • Application services orchestrate both to implement business use-cases.

2. Strong Typing Around Semantic Operations

Use domain-specific abstractions like SemanticSearchResult, Embedding value objects, and dedicated services. This makes it easier to evolve the underlying implementation without leaking details.

3. Testing Strategy

  • Unit tests: mock IEmbeddingGenerator and IVectorStore to test application logic.
  • Integration tests: spin up an in-memory vector store and run end-to-end index + search flows.
  • Load tests: use tools like k6 or NBomber to stress-test concurrent search/index semantics.

4. Configuration Management

  • Make model path, embedding dimension, vector DB connection details configurable via appsettings or environment variables.
  • Expose a health endpoint that checks ONNX session initialization and vector DB connectivity.

5. Backward Compatibility

  • If you upgrade models (changing embedding dimension), keep old and new collections in the vector DB and version them.
  • Provide a migration path or dual-read strategy until reindexing is done.

Conclusion

We’ve built a modern, AI-first .NET 8 backend that:

  • Uses ONNX Runtime for fast, local embedding generation.
  • Stores and searches embeddings via a pluggable vector store abstraction.
  • Exposes clean HTTP APIs for indexing and semantic search.

From here, you can:

  • Swap the in-memory vector store for Qdrant/pgvector in production.
  • Integrate a local or remote LLM and implement full RAG flows.
  • Extend the model to support multi-modal embeddings (e.g., images + text) using different ONNX models.

FAQs

1. How do I choose the right ONNX embedding model?

Pick a model that is explicitly designed for sentence embeddings or similarity search and has a good balance between embedding size and speed. Smaller dimensions (e.g., 384–768) are usually enough for many enterprise scenarios while being faster and more memory-efficient than very large embeddings.

2. Can I run this on .NET 6 or 7 instead of .NET 8?

Yes, the concepts are the same. Minimal APIs exist in .NET 6+, and ONNX Runtime works across these versions. You might need minor adjustments to the project file and language features depending on the C# version.

3. How do I implement real tokenization instead of the dummy char mapping?

You have two main options:

  • Export the model to ONNX with tokenizer and pre-processing embedded in the graph, so the input is raw text.
  • Implement the tokenizer in .NET to match the original model (e.g., BPE or WordPiece). This usually means porting the tokenizer logic or using a compatible library and then feeding token IDs into the ONNX model.

4. Should I normalize vectors in the ONNX graph or in C#?

Either works. Normalizing in C# (as shown) is flexible and easy to reason about; normalizing in the ONNX graph simplifies your C# code and guarantees consistent behavior across languages. The key is to normalize consistently for both indexing and querying.

5. How do I secure these APIs?

Treat them like any other internal microservice:

  • Use authentication/authorization (JWT, OAuth2, API keys) at the gateway or directly in the API.
  • Apply rate limiting on search and indexing endpoints.
  • Audit access if sensitive documents are indexed.

6. Can I store embeddings directly in PostgreSQL without pgvector?

You can store embeddings as arrays or JSON and compute similarity in your application or via custom functions, but performance will be limited. pgvector gives you efficient vector types and index structures (IVFFlat, HNSW) suitable for high-throughput APIs.

7. How large can my corpus be before I need a “real” vector DB?

In-memory or naive approaches work for thousands to tens of thousands of vectors. Once you reach hundreds of thousands or millions of vectors, specialized vector DBs (Qdrant, Milvus, pgvector) become important for both latency and resource usage.

8. How do I test semantic accuracy in an automated way?

Create a small labeled dataset of query-document pairs with ground-truth relevance labels. Run your semantic search pipeline against it and compute metrics such as MRR, nDCG, or precision@K. Integrate those tests into your CI/CD pipeline to catch regressions when changing models or preprocessing logic.

9. Can I add semantic capabilities to existing REST endpoints without breaking clients?

Yes. You can:

  • Add new query parameters (e.g., ?query= for semantic search).
  • Introduce new endpoints under a /semantic route.
  • Keep existing keyword-based search endpoints intact while gradually adopting semantic search behind a feature flag.

10. How do I handle multi-tenant data in the vector store?

Include a tenant identifier in your payload (Qdrant) or as a column (pgvector) and add it as a hard filter to all queries. You may also decide to use separate collections/tables per tenant if isolation requirements are strict or if you need different models per tenant.

 

 

 

 

 

You might be interest at

AI-Native .NET: Building Intelligent Applications with Azure OpenAI, Semantic Kernel, and ML.NET

AI-Augmented .NET Backends: Building Intelligent, Agentic APIs with ASP.NET Core and Azure OpenAI

Master Effortless Cloud-Native .NET Microservices Using DAPR, gRPC & Azure Kubernetes Service

🔗 Suggested External Links

  • ONNX Runtime Official Docs
    https://onnxruntime.ai/
  • Qdrant Vector Database
    https://qdrant.tech/
  • pgvector for PostgreSQL
    https://github.com/pgvector/pgvector

AI-Augmented .NET Backends: Building Intelligent, Agentic APIs with ASP.NET Core and Azure OpenAI

UnknownX · January 9, 2026 · Leave a Comment

 

Transform Your Backend into a Smart Autonomous Decision Layer

Executive Summary

Building Intelligent, Agentic APIs with ASP.NET Core and Azure OpenAI

Modern applications need far more than static JSON—they require intelligence, reasoning, and autonomous action. By integrating Azure OpenAI into ASP.NET Core, you can build agentic APIs capable of understanding natural language, analyzing content, and orchestrating workflows with minimal human intervention.

This guide shows how to go beyond basic chatbot calls and create production-ready AI APIs, unlocking:

  • Natural language decision-making

  • Content analysis pipelines

  • Real-time streaming responses

  • Tool calling for agent workflows

  • Resilient patterns suited for enterprise delivery

Whether you’re automating business operations or creating smart assistants, this blueprint gives you everything you need.


Prerequisites

Before writing a single line of code, make sure you have:

  • .NET 6+ (prefer .NET 8 for best performance)

  • Azure subscription

  • Azure OpenAI model deployment (gpt-4o-mini recommended)

  • IDE (Visual Studio or VS Code)

  • API key + endpoint

  • Familiarity with async patterns and dependency injection

Required NuGet packages

Install these packages in your ASP.NET Core project:

“`
dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity
dotnet add package Microsoft.Extensions.AI
dotnet add package Microsoft.Extensions.Configuration.UserSecrets
“`

Step 1 — Securely Configure Azure OpenAI

Options class

Start by setting up secure credential management. Create a configuration class to encapsulate Azure OpenAI settings:


namespace YourApp.AI.Configuration;

public class AzureOpenAIOptions
{
    public string Endpoint { get; set; } = string.Empty;
    public string DeploymentName { get; set; } = string.Empty;
    public string ApiKey { get; set; } = string.Empty;
}

Add your credentials to `appsettings.json`:


{
  "AzureOpenAI": {
    "Endpoint": "https://your-resource.openai.azure.com/",
    "DeploymentName": "gpt-4o-mini",
    "ApiKey": "your-api-key-here"
  }
}

For local development, use .NET user secrets to avoid committing credentials:


dotnet user-secrets init
dotnet user-secrets set "AzureOpenAI:Endpoint" "https://your-resource.openai.azure.com/"
dotnet user-secrets set "AzureOpenAI:DeploymentName" "gpt-4o-mini"
dotnet user-secrets set "AzureOpenAI:ApiKey" "your-api-key-here"

Step 2 — Create an AI Abstraction Service

Build a clean abstraction layer that isolates Azure OpenAI details from your business logic:


namespace YourApp.AI.Services;

using Azure;
using Azure.AI.OpenAI;
using Microsoft.Extensions.Options;

public interface IAIService
{
    Task GenerateResponseAsync(string userMessage, CancellationToken cancellationToken = default);
    Task AnalyzeContentAsync(string content, string analysisPrompt, CancellationToken cancellationToken = default);
    IAsyncEnumerable StreamResponseAsync(string userMessage, CancellationToken cancellationToken = default);
}

public class AzureOpenAIService(IOptions options) : IAIService
{
    private readonly AzureOpenAIOptions _options = options.Value;
    private OpenAIClient? _client;

    private OpenAIClient Client => _client ??= new OpenAIClient(
        new Uri(_options.Endpoint),
        new AzureKeyCredential(_options.ApiKey));

    public async Task GenerateResponseAsync(string userMessage, CancellationToken cancellationToken = default)
    {
        var chatCompletionOptions = new ChatCompletionOptions
        {
            Temperature = 0.7f,
            MaxTokens = 2000,
        };

        var messages = new[]
        {
            new ChatMessage(ChatRole.System, "You are a helpful assistant that provides accurate, concise responses."),
            new ChatMessage(ChatRole.User, userMessage)
        };

        var response = await Client.GetChatCompletionsAsync(
            _options.DeploymentName,
            messages,
            chatCompletionOptions,
            cancellationToken);

        return response.Value.Choices.Message.Content;
    }

    public async Task AnalyzeContentAsync(string content, string analysisPrompt, CancellationToken cancellationToken = default)
    {
        var systemPrompt = $"You are an expert analyst. {analysisPrompt}";
        
        var messages = new[]
        {
            new ChatMessage(ChatRole.System, systemPrompt),
            new ChatMessage(ChatRole.User, content)
        };

        var response = await Client.GetChatCompletionsAsync(
            _options.DeploymentName,
            messages,
            cancellationToken: cancellationToken);

        return response.Value.Choices.Message.Content;
    }

    public async IAsyncEnumerable StreamResponseAsync(
        string userMessage,
        [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        var messages = new[]
        {
            new ChatMessage(ChatRole.System, "You are a helpful assistant."),
            new ChatMessage(ChatRole.User, userMessage)
        };

        using var streamingResponse = await Client.GetChatCompletionsStreamingAsync(
            _options.DeploymentName,
            messages,
            cancellationToken: cancellationToken);

        await foreach (var update in streamingResponse.EnumerateUpdatesAsync(cancellationToken))
        {
            if (update.ContentUpdate != null)
            {
                yield return update.ContentUpdate;
            }
        }
    }
}

Step 3 — Register Services in Dependency Injection

 
 

Configure your services in `Program.cs`:


var builder = WebApplicationBuilder.CreateBuilder(args);

// Add configuration
builder.Services.Configure(
    builder.Configuration.GetSection("AzureOpenAI"));

// Register AI service
builder.Services.AddScoped<IAIService, AzureOpenAIService>();

// Add HTTP client for downstream integrations
builder.Services.AddHttpClient();

builder.Services.AddControllers();
builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();
app.MapControllers();

app.Run();

Step 4 — Build REST Intelligence Endpoints

 
 

Create a controller that exposes AI capabilities as REST endpoints:


namespace YourApp.Controllers;

using Microsoft.AspNetCore.Mvc;
using YourApp.AI.Services;

[ApiController]
[Route("api/[controller]")]
public class IntelligenceController(IAIService aiService) : ControllerBase
{
    [HttpPost("analyze")]
    public async Task AnalyzeContent(
        [FromBody] AnalysisRequest request,
        CancellationToken cancellationToken)
    {
        if (string.IsNullOrWhiteSpace(request.Content))
            return BadRequest("Content is required.");

        var analysis = await aiService.AnalyzeContentAsync(
            request.Content,
            request.AnalysisPrompt ?? "Provide a detailed analysis.",
            cancellationToken);

        return Ok(new { analysis });
    }

    [HttpPost("chat")]
    public async Task Chat(
        [FromBody] ChatRequest request,
        CancellationToken cancellationToken)
    {
        if (string.IsNullOrWhiteSpace(request.Message))
            return BadRequest("Message is required.");

        var response = await aiService.GenerateResponseAsync(
            request.Message,
            cancellationToken);

        return Ok(new { response });
    }

    [HttpPost("stream")]
    public async IAsyncEnumerable StreamChat(
        [FromBody] ChatRequest request,
        [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken)
    {
        if (string.IsNullOrWhiteSpace(request.Message))
            yield break;

        await foreach (var chunk in aiService.StreamResponseAsync(request.Message, cancellationToken))
        {
            yield return chunk;
        }
    }
}

public record AnalysisRequest(string Content, string? AnalysisPrompt = null);
public record ChatRequest(string Message);

Step 5 — Enable Agentic Behavior (Tool Calling)

 
 

Create an advanced service that enables the AI to call functions autonomously:


namespace YourApp.AI.Services;

using Azure.AI.OpenAI;

public interface IAgentService
{
    Task ExecuteAgentAsync(string userRequest, CancellationToken cancellationToken = default);
}

public class AgentService(IAIService aiService, IHttpClientFactory httpClientFactory) : IAgentService
{
    public async Task ExecuteAgentAsync(string userRequest, CancellationToken cancellationToken = default)
    {
        var conversationHistory = new List
        {
            new ChatMessage(ChatRole.System, 
                "You are an intelligent agent. When asked to perform tasks, use available tools. " +
                "Available tools: GetWeather, FetchUserData, SendNotification."),
            new ChatMessage(ChatRole.User, userRequest)
        };

        var response = await aiService.GenerateResponseAsync(userRequest, cancellationToken);

        // In production, implement actual tool calling logic here
        // This would involve parsing the AI response for tool calls and executing them

        return new AgentResponse
        {
            InitialResponse = response,
            ExecutedActions = new List(),
            FinalResult = response
        };
    }
}

public class AgentResponse
{
    public string InitialResponse { get; set; } = string.Empty;
    public List ExecutedActions { get; set; } = new();
    public string FinalResult { get; set; } = string.Empty;
}

## Production-Ready C# Examples

Production-Ready C# Enhancements

Retry + resilience using Polly


namespace YourApp.AI.Services;

using Polly;
using Polly.CircuitBreaker;
using Azure;

public class ResilientAzureOpenAIService(
    IOptions options,
    ILogger logger) : IAIService
{
    private readonly AzureOpenAIOptions _options = options.Value;
    private OpenAIClient? _client;
    private IAsyncPolicy<Response>? _retryPolicy;

    private OpenAIClient Client => _client ??= new OpenAIClient(
        new Uri(_options.Endpoint),
        new AzureKeyCredential(_options.ApiKey));

    private IAsyncPolicy<Response> RetryPolicy =>
        _retryPolicy ??= Policy
            .Handle(ex => ex.Status >= 500)
            .Or()
            .OrResult<Response>(r => !r.GetRawResponse().IsError)
            .WaitAndRetryAsync(
                retryCount: 3,
                sleepDurationProvider: attempt => TimeSpan.FromSeconds(Math.Pow(2, attempt)),
                onRetry: (outcome, timespan, retryCount, context) =>
                {
                    logger.LogWarning(
                        "Retry {RetryCount} after {DelayMs}ms due to {Reason}",
                        retryCount,
                        timespan.TotalMilliseconds,
                        outcome.Exception?.Message ?? "rate limit");
                });

    public async Task GenerateResponseAsync(
        string userMessage,
        CancellationToken cancellationToken = default)
    {
        var messages = new[]
        {
            new ChatMessage(ChatRole.System, "You are a helpful assistant."),
            new ChatMessage(ChatRole.User, userMessage)
        };

        var chatCompletionOptions = new ChatCompletionOptions { MaxTokens = 2000 };

        try
        {
            var response = await RetryPolicy.ExecuteAsync(
                async () => await Client.GetChatCompletionsAsync(
                    _options.DeploymentName,
                    messages,
                    chatCompletionOptions,
                    cancellationToken),
                cancellationToken);

            return response.Value.Choices.Message.Content;
        }
        catch (Azure.RequestFailedException ex) when (ex.Status == 429)
        {
            logger.LogError("Rate limit exceeded. Implement backoff strategy.");
            throw;
        }
    }

    public async Task AnalyzeContentAsync(
        string content,
        string analysisPrompt,
        CancellationToken cancellationToken = default)
    {
        // Implementation similar to GenerateResponseAsync
        throw new NotImplementedException();
    }

    public IAsyncEnumerable StreamResponseAsync(
        string userMessage,
        CancellationToken cancellationToken = default)
    {
        throw new NotImplementedException();
    }
}

Content Analysis Pipelines

 
 

namespace YourApp.Features.ContentAnalysis;

using YourApp.AI.Services;

public interface IContentAnalyzer
{
    Task AnalyzeAsync(string content, CancellationToken cancellationToken = default);
}

public class ContentAnalyzer(IAIService aiService, ILogger logger) : IContentAnalyzer
{
    public async Task AnalyzeAsync(
        string content,
        CancellationToken cancellationToken = default)
    {
        logger.LogInformation("Starting content analysis for {ContentLength} characters", content.Length);

        var sentimentTask = aiService.AnalyzeContentAsync(
            content,
            "Analyze the sentiment. Respond with: positive, negative, or neutral.",
            cancellationToken);

        var summaryTask = aiService.AnalyzeContentAsync(
            content,
            "Provide a concise summary in 2-3 sentences.",
            cancellationToken);

        var keywordsTask = aiService.AnalyzeContentAsync(
            content,
            "Extract 5 key topics or keywords as a comma-separated list.",
            cancellationToken);

        await Task.WhenAll(sentimentTask, summaryTask, keywordsTask);

        return new ContentAnalysisResult
        {
            Sentiment = await sentimentTask,
            Summary = await summaryTask,
            Keywords = (await keywordsTask).Split(',').Select(k => k.Trim()).ToList(),
            AnalyzedAt = DateTime.UtcNow
        };
    }
}

public class ContentAnalysisResult
{
    public string Sentiment { get; set; } = string.Empty;
    public string Summary { get; set; } = string.Empty;
    public List Keywords { get; set; } = new();
    public DateTime AnalyzedAt { get; set; }
}

 Common Pitfalls & Troubleshooting

Pitfall 1: Hardcoded Credentials

Problem: Storing API keys directly in code or configuration files committed to version control.

Solution: Always use Azure Key Vault or .NET user secrets:


// In production, use Azure Key Vault
builder.Services.AddAzureAppConfiguration(options =>
    options.Connect(builder.Configuration["AppConfig:ConnectionString"])
        .Select(KeyFilter.Any, LabelFilter.Null)
        .Select(KeyFilter.Any, builder.Environment.EnvironmentName));

 Pitfall 2: Unhandled Rate Limiting

Problem: Azure OpenAI enforces rate limits; exceeding them causes request failures.

Solution: Implement exponential backoff and circuit breaker patterns (shown in the resilient example above).

 Pitfall 3: Streaming Without Proper Cancellation

Problem: Long-running streaming operations don’t respect cancellation tokens, consuming resources.

Solution: Always pass `CancellationToken` through the entire call chain and use `EnumeratorCancellation` attribute.

Pitfall 4: Memory Leaks from Unclosed Clients

**Problem:** Creating new `OpenAIClient` instances repeatedly without disposal.

**Solution:** Use lazy initialization or dependency injection to maintain a single client instance:


private OpenAIClient Client => _client ??= new OpenAIClient(
    new Uri(_options.Endpoint),
    new AzureKeyCredential(_options.ApiKey));

### Pitfall 5: Ignoring Token Limits

**Problem:** Sending prompts that exceed the model’s token limit, causing failures.

**Solution:** Implement token counting and truncation:


private const int MaxTokens = 2000;
private const int SafetyMargin = 100;

private string TruncateIfNeeded(string content)
{
    // Rough estimate: 1 token ≈ 4 characters
    var estimatedTokens = content.Length / 4;
    if (estimatedTokens > MaxTokens - SafetyMargin)
    {
        var maxChars = (MaxTokens - SafetyMargin) * 4;
        return content[..maxChars];
    }
    return content;
}

## Performance & Scalability Considerations

### 1. Connection Pooling

Reuse HTTP connections by maintaining a single `OpenAIClient` instance per application:


// ✓ Good: Single instance
private OpenAIClient Client => _client ??= new OpenAIClient(...);

// ✗ Bad: New instance per request
var client = new OpenAIClient(...);

### 2. Async All the Way

Never block on async operations:


// ✓ Good
var result = await aiService.GenerateResponseAsync(message);

// ✗ Bad
var result = aiService.GenerateResponseAsync(message).Result;

### 3. Implement Caching for Repeated Queries


public class CachedAIService(IAIService innerService, IMemoryCache cache) : IAIService
{
    private const string CacheKeyPrefix = "ai_response_";
    private const int CacheDurationSeconds = 3600;

    public async Task GenerateResponseAsync(
        string userMessage,
        CancellationToken cancellationToken = default)
    {
        var cacheKey = $"{CacheKeyPrefix}{userMessage.GetHashCode()}";

        if (cache.TryGetValue(cacheKey, out string? cachedResponse))
            return cachedResponse!;

        var response = await innerService.GenerateResponseAsync(userMessage, cancellationToken);

        cache.Set(cacheKey, response, TimeSpan.FromSeconds(CacheDurationSeconds));

        return response;
    }

    // Other methods...
}

### 4. Batch Processing for High Volume


public class BatchAnalysisService(IAIService aiService)
{
    public async Task<List> AnalyzeBatchAsync(
        IEnumerable items,
        string analysisPrompt,
        int maxConcurrency = 5,
        CancellationToken cancellationToken = default)
    {
        var semaphore = new SemaphoreSlim(maxConcurrency);
        var tasks = new List<Task>();

        foreach (var item in items)
        {
            await semaphore.WaitAsync(cancellationToken);

            tasks.Add(Task.Run(async () =>
            {
                try
                {
                    return await aiService.AnalyzeContentAsync(item, analysisPrompt, cancellationToken);
                }
                finally
                {
                    semaphore.Release();
                }
            }, cancellationToken));
        }

        var results = await Task.WhenAll(tasks);
        return results.ToList();
    }
}

### 5. Regional Deployment for Low Latency

Deploy your ASP.NET Core application in the same Azure region as your OpenAI resource to minimize network latency.

## Practical Best Practices

### 1. Structured Logging


logger.LogInformation(
    "AI request completed. Model: {Model}, Tokens: {Tokens}, Duration: {Duration}ms",
    _options.DeploymentName,
    response.Usage.TotalTokens,
    stopwatch.ElapsedMilliseconds);

### 2. Input Validation and Sanitization


private void ValidateInput(string userMessage)
{
    if (string.IsNullOrWhiteSpace(userMessage))
        throw new ArgumentException("Message cannot be empty.");

    if (userMessage.Length > 10000)
        throw new ArgumentException("Message exceeds maximum length.");

    // Prevent prompt injection
    if (userMessage.Contains("ignore previous instructions", StringComparison.OrdinalIgnoreCase))
        throw new ArgumentException("Invalid message content.");
}

### 3. Testing with Mocks


public class MockAIService : IAIService
{
    public Task GenerateResponseAsync(string userMessage, CancellationToken cancellationToken = default)
    {
        return Task.FromResult("Mock response for testing");
    }

    public Task AnalyzeContentAsync(string content, string analysisPrompt, CancellationToken cancellationToken = default)
    {
        return Task.FromResult("Mock analysis");
    }

    public async IAsyncEnumerable StreamResponseAsync(string userMessage, [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        yield return "Mock ";
        yield return "streaming ";
        yield return "response";
    }
}

### 4. Monitoring and Observability


builder.Services.AddApplicationInsightsTelemetry();

// In your service
using var activity = new Activity("AIRequest").Start();
activity?.SetTag("model", _options.DeploymentName);
activity?.SetTag("message_length", userMessage.Length);

try
{
    var response = await Client.GetChatCompletionsAsync(...);
    activity?.SetTag("success", true);
}
catch (Exception ex)
{
    activity?.SetTag("error", ex.Message);
    throw;
}

## Conclusion

You’ve now built a production-grade AI-augmented backend with Azure OpenAI and ASP.NET Core. The architecture you’ve implemented provides:

– **Abstraction layers** that isolate AI logic from business logic
– **Resilience patterns** that handle failures gracefully
– **Scalability mechanisms** for high-volume scenarios
– **Security practices** that protect sensitive credentials
– **Observability** for monitoring and debugging

**Next steps:**

1. Deploy your application to Azure App Service or Azure Container Instances
2. Implement Azure Key Vault for credential management
3. Set up Application Insights for production monitoring
4. Experiment with different models (gpt-4, gpt-4o) to optimize cost vs. capability
5. Build domain-specific agents that leverage your business data
6. Implement fine-tuning for specialized use cases

The foundation is solid. Now extend it with your domain expertise.

—

## Frequently Asked Questions

### Q1: How do I choose between gpt-35-turbo, gpt-4o-mini, and gpt-4?

**A:** This is a cost-vs-capability tradeoff:

– **gpt-35-turbo**: Fastest and cheapest. Use for simple tasks like classification or summarization.
– **gpt-4o-mini**: Balanced option. Recommended for most production applications.
– **gpt-4**: Most capable but expensive. Use for complex reasoning, code generation, or specialized analysis.

Start with gpt-4o-mini and benchmark against your requirements.

### Q2: What’s the difference between streaming and non-streaming responses?

**A:** Streaming returns tokens progressively, enabling real-time UI updates and perceived faster responses. Non-streaming waits for the complete response. Use streaming for user-facing chat applications; use non-streaming for backend analysis where you need the full result before proceeding.

### Q3: How do I prevent prompt injection attacks?

**A:** Implement strict input validation, use system prompts that define boundaries, and never concatenate user input directly into prompts. Instead, use structured formats:


// ✗ Vulnerable
var prompt = $"Analyze this: {userInput}";

// ✓ Safe
var messages = new[]
{
    new ChatMessage(ChatRole.System, "You are an analyzer. Only respond with analysis."),
    new ChatMessage(ChatRole.User, userInput)
};

### Q4: How do I handle Azure OpenAI quota limits?

**A:** Monitor your usage in the Azure Portal, implement request throttling with `SemaphoreSlim`, and use exponential backoff for retries. Consider requesting quota increases for production workloads.

### Q5: Can I use Azure OpenAI with other .NET frameworks like Blazor or MAUI?

**A:** Yes. The Azure.AI.OpenAI SDK works with any .NET application. For Blazor, call your ASP.NET Core backend API instead of directly accessing Azure OpenAI from the browser (for security). For MAUI, use the same patterns shown here.

### Q6: How do I optimize costs for high-volume AI requests?

**A:** Implement caching for repeated queries, batch similar requests together, use gpt-4o-mini instead of gpt-4 when possible, and monitor token usage. Consider implementing a request queue with off-peak processing.

### Q7: What’s the best way to handle long conversations with context?

**A:** Maintain conversation history in memory or a database, but truncate old messages to stay within token limits. Implement a sliding window approach:


private const int MaxHistoryMessages = 10;

private List TrimHistory(List history)
{
    if (history.Count > MaxHistoryMessages)
        return history.Skip(history.Count - MaxHistoryMessages).ToList();
    return history;
}

### Q8: How do I test AI functionality without hitting Azure OpenAI every time?

**A:** Use the `MockAIService` pattern shown earlier. Inject `IAIService` as a dependency, allowing you to swap implementations in tests. Use xUnit or NUnit with Moq for unit testing.

### Q9: What should I do if the AI response is inappropriate or harmful?

**A:** Implement content filtering using Azure Content Safety API or similar services. Add a validation layer after receiving the response:


private async Task IsContentSafeAsync(string content)
{
    // Call Azure Content Safety API
    // Return true if safe, false otherwise
}

### Q10: How do I monitor token usage and costs?

**A:** Log token counts from the response object and aggregate them:


var response = await Client.GetChatCompletionsAsync(...);
var totalTokens = response.Value.Usage.TotalTokens;
var promptTokens = response.Value.Usage.PromptTokens;
var completionTokens = response.Value.Usage.CompletionTokens;

logger.LogInformation(
    "Tokens used - Prompt: {PromptTokens}, Completion: {CompletionTokens}, Total: {TotalTokens}",
    promptTokens,
    completionTokens,
    totalTokens);

Send this data to Application Insights for cost tracking and optimization.

Master Effortless Cloud-Native .NET Microservices Using DAPR, gRPC & Azure Kubernetes Service

Headless Architecture in .NET Microservices with gRPC

AI-Driven .NET Development in 2026: How Senior Architects Master .NET 10 for Elite Performance Tuning

.NET Core Microservices and Azure Kubernetes Service

External Resources

1️⃣ Microsoft Learn – ASP.NET Core Documentation
https://learn.microsoft.com/aspnet/core

2️⃣ Azure OpenAI Service Overview
https://learn.microsoft.com/azure/ai-services/openai/overview

3️⃣ Azure OpenAI Chat Completions API Reference
https://learn.microsoft.com/azure/ai-services/openai/reference

  • Page 1
  • Page 2
  • Go to Next Page »

Primary Sidebar

Recent Posts

  • Build Stunning Cross-Platform Apps with .NET MAUI
  • .NET 10 Performance Optimization and AOT Compilation
  • .NET 8 Enhancements for Performance and AI
  • Modern Authentication in 2026: How to Secure Your .NET 8 and Angular Apps with Keycloak
  • Mastering .NET 10 and C# 13: Ultimate Guide to High-Performance APIs 🚀

Recent Comments

No comments to show.

Archives

  • February 2026
  • January 2026

Categories

  • .NET Core
  • 2026 .NET Stack
  • Enterprise Architecture
  • Kubernetes
  • Machine Learning
  • Web Development

Sas 101

Copyright © 2026 · saas101.tech · Log in