devexpress-blazor-ai-chat

name	devexpress-blazor-ai-chat
description	Generate and configure DevExpress Blazor AI Chat (DxAIChat) — an AI-powered chat UI for Blazor apps. Use for building conversational assistants, integrating providers (OpenAI, Azure OpenAI, Ollama, or custom), configuring system prompts and suggestions, streaming responses, attachments, Markdown rendering, and tool/function calling via custom IChatResponseProvider implementations. Also use for DxAIChat, AI chat component, LLM chat UI, OpenAI setup, and chat architecture comparisons or migration scenarios.
compatibility	Requires .NET 8.0, 9.0, or 10.0. Interactive render mode required (InteractiveServer, InteractiveWebAssembly, or InteractiveAuto). DevExpress NuGet packages are available on NuGet.org. An AI provider (OpenAI, Azure OpenAI, Ollama, or custom) must be configured separately — BYOK model.
metadata	{"author":"DevExpress","version":"26.1","source-commit":"8493730c9e9a47a009fc307a37c307e157663819"}

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

Package	Minimum Version	Purpose
DevExpress.AIIntegration.Blazor.Chat	26.1	Core AI Chat component
DevExpress.Blazor	26.1	Required DevExpress Blazor base
DevExpress.AIIntegration.Agents	26.1	Agent-based IChatResponseProvider creation (.AsAIAgent())
Microsoft.Extensions.AI	9.7.1	Required MEI abstraction layer
Microsoft.Extensions.AI.OpenAI	9.7.1-preview.1.25365.4	Azure OpenAI / OpenAI provider bridge
Azure.AI.OpenAI	2.3.0	Azure OpenAI SDK
OpenAI	2.3.0	OpenAI (non-Azure) SDK
OllamaSharp	—	Ollama self-hosted provider

# 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:

Type / Extension	Namespace
DxAIChat, DxAIChatPromptSuggestion, DxAIChatFileUploadSettings, BlazorChatMessage, IAIChat, AIChatResource, IAIChatMessageContextItem	DevExpress.AIIntegration.Blazor.Chat
IChatResponseProvider, .AsIChatResponseProvider(), .AsIChatResponseProvider(ChatOptions)	DevExpress.AIIntegration.Chat
.AsAIAgent(instructions:)	DevExpress.AIIntegration.Agents
DxResourceManager, Themes, SizeMode	DevExpress.Blazor
IChatClient, ChatRole	Microsoft.Extensions.AI
AzureOpenAIClient	Azure.AI.OpenAI
ApiKeyCredential	System.ClientModel
OpenAIClient	OpenAI
AddDevExpressBlazor, AddDevExpressAI	Extension methods — no explicit using needed; resolved from installed NuGet packages

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

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

Provider	Required Values	Where to Obtain
Azure OpenAI	Endpoint URL · API key · Deployment name	Azure Portal → your Azure OpenAI resource → Keys and Endpoint; deployment name from Azure OpenAI Studio
OpenAI	API key	platform.openai.com → API keys
Ollama (self-hosted)	Server URL (default http://localhost:11434) · Model name	No cloud account needed — install Ollama locally and pull a model (see below)
Google Gemini	API key	Google AI Studio → Get API key
Custom provider	Provider-specific	Implement IChatResponseProvider manually

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

Approach	Recommended for	What to do
User secrets	Local development	Run dotnet user-secrets commands once per project (see below)
Environment variables	CI/CD pipelines, containers, PaaS hosting	Set variables in the OS, Docker environment, or hosting platform config
Azure Key Vault	Production Azure deployments	Add Azure.Extensions.AspNetCore.Configuration.Secrets package; configure vault URI in Program.cs
appsettings.json overrides	Deploy-time injection only	Leave placeholder values in the file; supply real values via environment variable overrides at deploy time — never commit real keys

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

When you need to:

• Connect to Azure OpenAI, OpenAI, or Ollama
• Register multiple providers and switch between them at runtime
• Build agent-based providers using DevExpress.AIIntegration.Agents

Features Reference

📄 references/features.md

When you need to:

• Add prompt suggestions or a system prompt
• Enable file attachments and configure validation rules
• Configure Markdown rendering
• Handle MessageSending / ResponseReceived events
• Manually append context or send messages via AppendMessageAsync / SendMessageAsync
• Implement tool/function calling
• Save and restore conversation history
• Use Resources for structured document grounding
• Customize the chat header, empty placeholder, or input resize

Quick Start Example

📄 examples/quickstart.razor — complete page with prompt suggestions and system prompt.

More Examples

File	What it demonstrates
📄 examples/file-attachments.razor	PDF and image upload with type/size validation
📄 examples/multi-provider.razor	Switching between Azure OpenAI and Ollama at runtime
📄 examples/tool-calling.razor	AI function/tool calling with UseFunctionInvocation()
📄 examples/save-restore-history.razor	Saving and restoring conversation history across page navigations

Key Properties & API Surface

DxAIChat

Property / Event	Type	Description
Initialized	EventCallback<IAIChat>	Fires after AI service connects — use to load system prompts or history
UseStreaming	bool	Stream tokens as they arrive (default: false) — set true to stream partial tokens as they arrive instead of waiting for the full response
ResponseContentFormat	ResponseContentFormat	Default (plain text) or Markdown
MessageSending	EventCallback<MessageSendingEventArgs>	Fires before the message is sent — intercept, cancel, or append system context. User text: args.Text
ResponseReceived	EventCallback<ResponseReceivedEventArgs>	Fires after AI responds — use for audit logging or filtering tool calls
FileUploadEnabled	bool	Shows the file attachment button (default: false)
ChatResponseProviderServiceKey	string?	Key for a keyed IChatResponseProvider DI registration
PromptSuggestions	RenderFragment	Slot for DxAIChatPromptSuggestion components
MessageContentTemplate	RenderFragment<BlazorChatMessage>	Custom template for message content rendering
AIChatSettings	RenderFragment	Slot for DxAIChatFileUploadSettings
ShowHeader	bool	Shows or hides the chat header bar (default: false)
HeaderText	string	Text displayed in the header (requires ShowHeader="true")
EmptyMessageAreaText	string	Placeholder text when the chat has no messages
AllowResizeInput	bool	Allows users to drag the input box height (default: false)
SizeMode	SizeMode	Component size: Small, Medium (default), Large
CssClass	string	CSS class(es) applied to the root element — use for sizing and positioning (e.g., width, height, margin)
InputBoxNullText	string	Placeholder text shown in the input box when empty (default: localized string)
IncludeFunctionCallInfo	bool	Appends tool call details (name, args, result) to AI responses — useful during development/debugging (default: false)
FunctionCallInfoContentTemplate	RenderFragment<BlazorChatMessage>	Custom template for the function call details section appended by IncludeFunctionCallInfo; context.FunctionCalls lists each invoked function with Request.Name and Result.Result
Resources	IEnumerable<AIChatResource>	Named documents/data users attach via a picker for contextual grounding
ResourceItemTemplate	RenderFragment<AIChatResource>	Custom template for each entry in the resource picker popup; context.Name and context.Uri are available
BindValueMode	BindValueMode	Controls when the input buffer syncs: OnInput (default), OnLostFocus, OnDelayedInput. Use OnDelayedInput with InputDelay to reduce re-renders in WebAssembly/Auto modes
InputDelay	int?	Milliseconds of idle time before buffer syncs in OnDelayedInput mode (default: 500 ms)
MessageTemplate	RenderFragment<BlazorChatMessage>	Replaces the entire message bubble including padding and layout; use MessageContentTemplate instead to only replace the inner content while keeping bubble styling
EmptyMessageAreaTemplate	RenderFragment	Custom template for the empty state when the chat has no messages — replaces EmptyMessageAreaText when more than text is needed
PromptSuggestionContentTemplate	RenderFragment<IPromptSuggestion>	Custom template for the content inside each prompt suggestion bubble; context.Title is the suggestion text

DxAIChatPromptSuggestion

Property	Type	Description
Title	string	Bold header on the suggestion tile
Text	string	Secondary description text
PromptMessage	string	Message sent to AI when user clicks the tile
SendOnClick	bool	true — send immediately on click; false (default) — place in prompt box for user to edit before sending

DxAIChatFileUploadSettings

Property	Type	Description
MaxFileCount	int	Maximum files per message
MaxFileSize	int	Maximum file size in bytes
AllowedFileExtensions	List<string>	e.g., new List<string> { ".jpg", ".pdf" }
FileTypeFilter	List<string>	MIME filter for browser picker, e.g., "image/*"

IAIChat (from Initialized event arg)

Method	Description
LoadMessages(IEnumerable<BlazorChatMessage>)	Preloads messages (system prompt, history)
SaveMessages()	Snapshots current conversation history (returns IEnumerable<BlazorChatMessage>)
AppendMessageAsync(string, ChatRole, List<IAIChatMessageContextItem>?)	Adds a message to history without triggering an AI response
ShowLoadingIndicatorAsync(string?)	Shows a loading indicator with optional text — useful in MessageSending for long async pre-processing
HideLoadingIndicatorAsync()	Removes the loading indicator — must call before SendMessageAsync will work again

DxAIChat Methods (via @ref)

Obtain a component reference to call these methods imperatively:

<DxAIChat @ref="chat" />
@code { DxAIChat? chat; }

Method	Signature	Description
AppendMessageAsync	(string content, ChatRole role, List<IAIChatMessageContextItem>? contexts = null)	Adds a message to history without triggering an AI response
SendMessageAsync	(string content, List<IAIChatMessageContextItem>? contexts = null)	Programmatically sends a message to the AI service
SaveMessages	() → IEnumerable<BlazorChatMessage>	Snapshots current conversation history for persistence
LoadMessages	(IEnumerable<BlazorChatMessage>)	Restores conversation history (same as IAIChat.LoadMessages)

Common Patterns

• System prompt: Load via Initialized event — chat.LoadMessages(new[] { new BlazorChatMessage(ChatRole.System, "...") }). See 📄 examples/quickstart.razor.
• File attachments: Set FileUploadEnabled="true" + nest <DxAIChatFileUploadSettings> inside <AIChatSettings>. See 📄 examples/file-attachments.razor.
• Multiple providers: Register each as AddKeyedScoped<IChatResponseProvider>("key", ...) and bind with ChatResponseProviderServiceKey="@key". See 📄 examples/multi-provider.razor.
• Tool calling: Register UseFunctionInvocation() on the IChatClient pipeline. See 📄 examples/tool-calling.razor.
• Save/restore history: Call chat.SaveMessages() on navigate-away, chat.LoadMessages(saved) on return. See 📄 examples/save-restore-history.razor.

Troubleshooting

Symptom	Likely Cause	Fix
Component renders without styles	App.razor missing theme/scripts registration	Add @DxResourceManager.RegisterTheme(Themes.Fluent) and @DxResourceManager.RegisterScripts() inside <head> in App.razor
Chat renders, AI does not respond	IChatResponseProvider not registered	Verify DI registration in Program.cs
Runtime exception on first message with multiple providers	Keyed IChatClient (via AddKeyedChatClient) used instead of IChatResponseProvider	Replace AddKeyedChatClient("key", ...) with AddKeyedScoped<IChatResponseProvider>("key", (_, _) => client.AsIChatResponseProvider()) and replace ChatClientServiceKey with ChatResponseProviderServiceKey
401 Unauthorized	Wrong API key or endpoint	Check environment variables / secrets
Chat loads but stays blank	Static SSR render mode	Add @rendermode InteractiveServer to the page
File upload button not visible	FileUploadEnabled not set	Set FileUploadEnabled="true"
Markdown not rendered	Default format is plain text	Set ResponseContentFormat="ResponseContentFormat.Markdown"
AI responses show raw HTML tags	Markdown converted to HTML without sanitization	Use HtmlSanitizer (Ganss.Xss) + Markdig in MessageContentTemplate — never pass raw AI output to MarkupString
AI responds slowly	No streaming	Streaming is on by default; check provider config
"Unhandled exception on the current circuit" with no detail	CircuitOptions.DetailedErrors not set	Add builder.Services.Configure<CircuitOptions>(o => o.DetailedErrors = true); in Program.cs (development only)
"Component parameter 'ValueChanged' is used two or more times" compile error	@bind-Value and ValueChanged used together	Use @bind-Value="@val" for two-way binding, or Value="@val" ValueChanged="@handler" — never both simultaneously
dx-blazor.js not found (404) behind a reverse proxy	Reverse proxy strips the app base path	Add app.UsePathBase("/subpath") before app.MapBlazorHub(), or set <base href="/subpath/" /> in App.razor
Static assets return 404 (dx-blazor.css, dx-blazor.js)	UseStaticWebAssets() not called	Add app.UseStaticWebAssets(); in Program.cs before app.UseStaticFiles()
"Could not find 'X' in 'window.DxBlazor'" JavaScript error	Stale browser-cached JS from an older DevExpress version	Hard-refresh the browser (Ctrl+Shift+R), clear site data, or verify all DevExpress NuGet packages are the same version
"Cannot pass the parameter 'X' to component 'Y' with rendermode"	Non-serializable parameter passed across a render mode boundary	Move the component to a child .razor file with its own @rendermode directive; pass only serializable parameters

Constraints & Rules

0. Never invent API: If a property, method, event, or feature is not documented in this skill or its references, do not assume it exists. When asked about an unfamiliar API, first try to verify it using the DevExpress documentation MCP (devexpress_docs_search) or the local apidoc/ folder. Only after checking: if confirmed, use the API; if not found, explicitly state that it does not appear to be part of the DxAIChat API. Do not warn that a feature "may have been introduced in a recent version" as a way to justify inventing it.
1. Build verification: After changes, run dotnet build and fix errors before reporting success.
2. Never hardcode keys: API keys and endpoints must come from environment variables, user secrets, or a vault.
3. Render mode required: DxAIChat requires an interactive render mode. Static SSR is not supported.
4. BYOK model: DevExpress does not provide AI models. The developer must supply provider credentials.
5. Version consistency: All DevExpress packages must use the same version number. IChatResponseProvider (and .AsIChatResponseProvider()) requires v26.1 or later — do not generate code using this API for earlier versions.
6. MessageSendingEventArgs property name: The user message text is args.Text (v26.1+). The old args.Content property is obsolete and generates compiler warnings — do not generate it.
7. Obsolete — do not generate: Temperature, MaxTokens, and FrequencyPenalty are removed from DxAIChat (build errors). ChatClientServiceKey → use ChatResponseProviderServiceKey. MessageSent event and MessageSentEventArgs → use MessageSending / MessageSendingEventArgs. SendMessage(string, ChatRole, ...) on IAIChat/DxAIChat → use SendMessageAsync (for ChatRole.User) or AppendMessageAsync (for other roles). SetupAssistantAsync(AIAssistantOptions) overloads and BlazorChatMessage.Content → use BlazorChatMessage.Text. For inference parameters (Temperature, FrequencyPenalty, MaxOutputTokens), pass a ChatOptions object to .AsIChatResponseProvider(chatOptions) during DI registration.
8. License: A valid DevExpress license is required. Resolve license errors before proceeding.
9. No destructive changes: Preserve existing using statements, class structure, and unrelated code.
10. App.razor styles: When generating a new project or extending an existing one, always verify that App.razor contains both @DxResourceManager.RegisterTheme(Themes.Fluent) and @DxResourceManager.RegisterScripts() inside <head>. Without them the component renders without styles.
11. No style attribute on DxAIChat: DxAIChat does not accept an HTML style attribute or arbitrary HTML attributes. Do not generate <DxAIChat style="..."> — use CssClass for sizing/positioning or documented properties (SizeMode, ShowHeader, etc.) for appearance control.
12. XSS sanitization: When ResponseContentFormat="Markdown" is used with a custom MessageContentTemplate that renders output as MarkupString, always sanitize the HTML before rendering. Use Markdig to convert Markdown to HTML and HtmlSanitizer (Ganss.Xss) to strip unsafe tags. Never pass raw AI output directly to new MarkupString(...) without sanitization. See references/features.md for the required pattern.
13. Boolean property defaults: All bool parameters default to false unless the API doc explicitly declares [DefaultValue(true)]. Never assume or state that a boolean property defaults to true unless it is confirmed by a [DefaultValue(true)] attribute in the API reference.

Using DevExpress Documentation MCP

If the DevExpress Docs MCP server is available, use it to supplement this skill:

1. Search: devexpress_docs_search(technology="Blazor", query="DxAIChat file attachments")
2. Fetch: devexpress_docs_get_content(url="https://docs.devexpress.com/Blazor/...")

Use built-in references for common patterns. Use MCP for advanced scenarios, exact method signatures, version-specific API changes, or features not covered in this skill.