devexpress/agent-skills/devexpress-blazor-ai-chat

DevExpress Blazor AI Chat

DxAIChat is an AI-powered conversational UI component compatible with major cloud AI providers (OpenAI, Azure OpenAI) and self-hosted models (Ollama). It runs in Blazor, .NET MAUI, WPF, and WinForms applications. The component operates on a BYOK (bring your own key) model — you supply the AI provider credentials; DevExpress does not bundle any LLM.

Security: Never hardcode AI provider keys, endpoints, or credentials in source code. Use environment variables, user secrets, or a secrets vault.

When to Use This Skill

• Add a conversational AI chat widget to a Blazor page
• Connect DxAIChat to Azure OpenAI, OpenAI, or Ollama
• Configure prompt suggestions (hint bubbles shown before the first message)
• Add a system prompt to give the AI model a persona or instructions
• Enable file attachments (PDF, images) for multimodal AI analysis
• Render AI responses with Markdown formatting
• Switch between multiple AI providers at runtime
• Implement tool/function calling from the AI model
• Save and load conversation history
• Integrate with AI agents and custom backends via IChatResponseProvider

Prerequisites & Installation

NuGet Packages

# Install from NuGet.org:
dotnet add package DevExpress.AIIntegration.Blazor.Chat
dotnet add package DevExpress.Blazor

Important: Always use version 26.1 or later. IChatResponseProvider and .AsIChatResponseProvider() are not available in 25.2 or earlier. All DevExpress packages must use the same version. A valid DevExpress license is required.

Namespace Quick Reference

Use this table to resolve using directives without searching — copy the exact namespace for each type:

Required Registration (all three steps must be present)

Program.cs — register the AI provider, then DevExpress services (see BYOK Setup Guide below for provider details):

// Register the IChatClient — AddDevExpressAI() automatically creates the default IChatResponseProvider from it
builder.Services.AddChatClient(chatClient);
builder.Services.AddDevExpressBlazor();
builder.Services.AddDevExpressAI();

v26.1 note: DevExpress.Blazor no longer includes options.BootstrapVersion or DevExpress.Blazor.BootstrapVersion. Do not generate either API.

Keyed providers only: For multi-provider (runtime-switching) setups, skip AddChatClient and register each provider explicitly: builder.Services.AddKeyedScoped<IChatResponseProvider>("key", (_, _) => client.AsIChatResponseProvider()).

Components/App.razor — register theme and client scripts inside <head>:

@using DevExpress.Blazor
@DxResourceManager.RegisterTheme(Themes.Fluent)
@DxResourceManager.RegisterScripts()

Without these two calls components render without styles and client interactivity is broken.

Components/_Imports.razor — add global namespace:

@using DevExpress.AIIntegration.Blazor.Chat

Before You Start — Ask the Developer

If the host agent has a structured question-asking tool available, use it to ask these questions one at a time with clear options — for example, Claude Code's AskUserQuestion tool or GitHub Copilot's askQuestions tool. If no such tool is available, ask the questions directly in the chat response before generating code.

1. Render mode: What is your render mode? (InteractiveServer, InteractiveWebAssembly, or InteractiveAuto)
2. New or existing project?
3. AI provider: Azure OpenAI, OpenAI, Ollama, Google Gemini, or custom?
4. If Ollama: What model name do you want to use? (e.g., llama3, phi4, mistral, gemma) — run ollama list to see installed models.
5. Key features needed: Prompt suggestions? File attachments? System prompt? Markdown rendering? Tool calling?
6. Secrets management: How are API keys stored? (environment variables, user secrets, Azure Key Vault)

Rule: Do not hardcode AI credentials. Confirm secret management before generating Program.cs code.

BYOK Setup Guide

DxAIChat is a Bring Your Own Key (BYOK) component — DevExpress does not supply AI models, API keys, or endpoints. The developer must provision an AI provider and configure credentials before any code will work.

Agent instruction: When the user picks an AI provider (question 3) or a secret storage approach (question 5) from the section above, immediately present the matching rows from the tables below. Do not skip to code generation until the user confirms their credentials are in place.

Required Credentials by Provider

Azure OpenAI — three values are required:

AZURE_OPENAI_ENDPOINT   = https://<resource-name>.openai.azure.com/
AZURE_OPENAI_KEY        = <key copied from Azure Portal → Keys and Endpoint>
AZURE_OPENAI_DEPLOYMENT = <deployment name from Azure OpenAI Studio>

OpenAI — one value required:

OPENAI_KEY = sk-<key from platform.openai.com>

The model name (e.g., "gpt-4o") is set in Program.cs code directly, not stored as a secret.

Ollama — local system setup, no cloud account:

# Install Ollama on Windows
winget install Ollama.Ollama
 
# List already-installed models
ollama list
 
# Pull a model if not already installed (examples below)
ollama pull llama3      # Meta LLaMA 3
ollama pull phi4        # Microsoft Phi-4
ollama pull mistral     # Mistral 7B
ollama pull gemma       # Google Gemma
 
# Ollama starts automatically; default server URL: http://localhost:11434
# No API key required for local use

Agent instruction: Before generating Ollama registration code, ask the developer which model they want to use. Declare the client as IChatClient (not var) so .AsIChatResponseProvider() resolves: IChatClient ollamaClient = new OllamaApiClient(url, "<model-name>"); — do not hardcode "llama3" as a default.

Secret Storage — What to Configure

User secrets — run once per project in the project folder:

dotnet user-secrets init
 
# Azure OpenAI
dotnet user-secrets set "AZURE_OPENAI_ENDPOINT" "https://..."
dotnet user-secrets set "AZURE_OPENAI_KEY" "..."
dotnet user-secrets set "AZURE_OPENAI_DEPLOYMENT" "gpt-4o"
 
# OpenAI
dotnet user-secrets set "OPENAI_KEY" "sk-..."

Secrets are stored in %APPDATA%\Microsoft\UserSecrets\<project-guid>\secrets.json and are never committed to source control.

Environment variables — read in Program.cs:

// Direct read
Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY")
 
// Via IConfiguration (reads env vars and user secrets automatically in development)
builder.Configuration["AZURE_OPENAI_KEY"]

Azure Key Vault — add to Program.cs before building services:

using Azure.Identity;
 
builder.Configuration.AddAzureKeyVault(
    new Uri("https://<vault-name>.vault.azure.net/"),
    new DefaultAzureCredential());
 
// Then read secrets by their vault secret name:
builder.Configuration["AzureOpenAiKey"]

Component Overview

DxAIChat provides:

• Conversational UI: Full message history, user/AI message rendering, typing indicator (DxAIChat)
• Prompt suggestions: Pre-defined hint bubbles for first-message guidance (DxAIChatPromptSuggestion)
• File attachments: Upload PDFs and images for multimodal AI analysis (DxAIChatFileUploadSettings)
• Initialization hook: Run setup code (system prompt, assistant binding) via the Initialized event (IAIChat)
• Multi-provider support: Switch providers at runtime using ChatResponseProviderServiceKey

Core Entry Point

Minimal Razor markup:

@using DevExpress.AIIntegration.Blazor.Chat
 
<DxAIChat />

Minimal Program.cs (Azure OpenAI):

using Azure.AI.OpenAI;
using System.ClientModel;
using Microsoft.Extensions.AI;
 
var azureClient = new AzureOpenAIClient(
    new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!),
    new ApiKeyCredential(Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY")!));
 
IChatClient chatClient = azureClient
    .GetChatClient(Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT")!)
    .AsIChatClient();
 
// AddChatClient registers the IChatClient; AddDevExpressAI() automatically wraps it
// as the default (non-keyed) IChatResponseProvider — no explicit registration needed
builder.Services.AddChatClient(chatClient);
builder.Services.AddDevExpressBlazor();
builder.Services.AddDevExpressAI();

Version requirement: IChatResponseProvider and the .AsIChatResponseProvider() extension method are available starting from DevExpress v26.1. Earlier versions use a different integration API.

Documentation & Navigation Guide

Getting Started

📄 references/getting-started.md

When you need to:

• Install packages and register an AI provider in Program.cs
• Add DxAIChat to a Blazor page with the correct render mode
• See a complete working project setup

AI Service Integration

📄 references/ai-service-integration.md