Azure OpenAI for .NET: Setup, Usage & Best Practices

Azure OpenAI brings GPT-4, embeddings, DALL-E, and Whisper to enterprise .NET applications with built-in security, compliance, and Azure integration. For .NET developers building AI-powered features, this SDK provides production-ready access to cutting-edge language models without managing infrastructure or API keys manually.

What This Skill Does

The Azure.AI.OpenAI SDK provides strongly-typed .NET clients for all Azure OpenAI capabilities. The hierarchical client design starts with AzureOpenAIClient as your entry point, then specialized clients for specific operations: ChatClient for conversations, EmbeddingClient for vector generation, ImageClient for DALL-E image creation, and AudioClient for Whisper transcription and text-to-speech.

This architecture mirrors Azure's service structure while providing .NET-native patterns. Type safety catches configuration errors at compile time, async/await patterns integrate seamlessly with ASP.NET Core and other async .NET frameworks, and DefaultAzureCredential eliminates manual credential management.

The SDK supports both Azure OpenAI Service and standard OpenAI endpoints, providing flexibility for hybrid scenarios. Chat completions handle everything from basic Q&A to complex multi-turn conversations with function calling, streaming responses, and structured JSON outputs.

Getting Started

Install the Azure.AI.OpenAI package via NuGet. For production applications, also add Azure.Identity for credential management. Set environment variables for your Azure OpenAI endpoint, API key (or use managed identity), and deployment name.

Client creation follows Azure SDK patterns. Use AzureOpenAIClient with your endpoint and credentials, then call specialized client getters—GetChatClient(deploymentName) for chat, GetEmbeddingClient(deploymentName) for embeddings, etc. The deployment name parameter targets your specific model deployment in Azure, not the base model name.

Key Features

Chat Completions: The ChatClient handles conversations with full support for system prompts, multi-turn dialogue, streaming responses, and token usage tracking. Create chat messages with strongly-typed classes—SystemChatMessage for system prompts, UserChatMessage for user input, AssistantChatMessage for model responses.

Structured Outputs: Define JSON schemas for model responses, ensuring consistent, parseable output. This is critical for applications feeding LLM outputs into downstream systems or databases. The SDK validates responses against your schema automatically.

Function Calling: Expose .NET methods as tools the model can invoke. Define function schemas with ChatTool.CreateFunctionTool, check for tool calls in responses, execute functions in your application, then submit results back. This enables models to access real-time data, perform calculations, or trigger actions.

Embeddings: Generate vector representations of text for semantic search, similarity matching, or clustering. The EmbeddingClient supports both single and batch embedding generation, returning float arrays suitable for vector databases.

Image Generation: Create images from text prompts using DALL-E 3. Control size, quality, and artistic style. Images return as URLs or base64-encoded data depending on your needs.

Audio Processing: Transcribe audio with Whisper for speech-to-text applications. Generate speech from text for text-to-speech scenarios with multiple voice options.

Azure AI Search Integration: Connect chat completions to Azure AI Search for retrieval-augmented generation (RAG). The SDK handles grounding model responses in your indexed documents, returning citations and sources automatically.

Usage Examples

Basic chat starts with creating message arrays and calling CompleteChatAsync. Check token usage in the response for cost tracking and rate limit management.

Streaming provides better user experience for long responses. Use CompleteChatStreamingAsync and iterate over updates, printing content chunks as they arrive. This dramatically improves perceived latency.

Function calling requires defining tool schemas, detecting tool calls in responses, executing functions, and submitting outputs. The SDK provides all necessary types—ChatToolCall, ToolOutput, etc.—with strong typing throughout.

RAG with Azure AI Search involves adding data sources to completion options. Responses include citations with content snippets and source references.

Best Practices

Use DefaultAzureCredential for all production deployments. It discovers managed identities, service principals, or environment variables automatically, eliminating hardcoded keys.

Reuse client instances across requests. Clients are thread-safe and expensive to instantiate. Create once during application startup, inject via dependency injection in ASP.NET Core.

Implement exponential backoff for rate limit errors (429 responses). The SDK throws RequestFailedException with status codes for error handling.

Monitor token usage closely. Check completion.Usage.TotalTokenCount and log for cost analysis and quota management.

Use structured outputs for downstream system integration. JSON schemas prevent parsing errors and type mismatches.

When to Use This Skill

This skill is essential for any .NET application integrating language models—chatbots, content generation, code assistants, document analysis, or customer support automation.

RAG applications benefit from Azure AI Search integration. Combine your proprietary data with model intelligence for grounded, citation-backed responses.

Enterprise .NET teams leverage existing infrastructure and expertise. Integrate OpenAI capabilities into existing ASP.NET, Azure Functions, or microservices architectures.

When NOT to Use This Skill

For non-.NET applications, Python or JavaScript SDKs provide equivalent functionality. Don't adopt .NET solely for this SDK.

Extremely cost-sensitive applications might prefer smaller, self-hosted models despite lower capabilities.

Related Skills

• azure-ai-projects-dotnet - Higher-level Azure AI project management
• agent-framework-azure-ai-py - Python agent framework
• azure-ai-agents-persistent-dotnet - Persistent agents for .NET

Source

This skill is maintained by Microsoft. View on GitHub