Azure AI Openai Dotnet

1---
2name: azure-ai-openai-dotnet
3description: |
4  Azure OpenAI SDK for .NET. Client library for Azure OpenAI and OpenAI services. Use for chat completions, embeddings, image generation, audio transcription, and assistants. Triggers: "Azure OpenAI", "AzureOpenAIClient", "ChatClient", "chat completions .NET", "GPT-4", "embeddings", "DALL-E", "Whisper", "OpenAI .NET".
5package: Azure.AI.OpenAI
6---
7 
8# Azure.AI.OpenAI (.NET)
9 
10Client library for Azure OpenAI Service providing access to OpenAI models including GPT-4, GPT-4o, embeddings, DALL-E, and Whisper.
11 
12## Installation
13 
14```bash
15dotnet add package Azure.AI.OpenAI
16 
17# For OpenAI (non-Azure) compatibility
18dotnet add package OpenAI
19```
20 
21**Current Version**: 2.1.0 (stable)
22 
23## Environment Variables
24 
25```bash
26AZURE_OPENAI_ENDPOINT=https://<resource-name>.openai.azure.com
27AZURE_OPENAI_API_KEY=<api-key>                    # For key-based auth
28AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o-mini          # Your deployment name
29```
30 
31## Client Hierarchy
32 
33```
34AzureOpenAIClient (top-level)
35├── GetChatClient(deploymentName)      → ChatClient
36├── GetEmbeddingClient(deploymentName) → EmbeddingClient
37├── GetImageClient(deploymentName)     → ImageClient
38├── GetAudioClient(deploymentName)     → AudioClient
39└── GetAssistantClient()               → AssistantClient
40```
41 
42## Authentication
43 
44### API Key Authentication
45 
46```csharp
47using Azure;
48using Azure.AI.OpenAI;
49 
50AzureOpenAIClient client = new(
51    new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!),
52    new AzureKeyCredential(Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")!));
53```
54 
55### Microsoft Entra ID (Recommended for Production)
56 
57```csharp
58using Azure.Identity;
59using Azure.AI.OpenAI;
60 
61AzureOpenAIClient client = new(
62    new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!),
63    new DefaultAzureCredential());
64```
65 
66### Using OpenAI SDK Directly with Azure
67 
68```csharp
69using Azure.Identity;
70using OpenAI;
71using OpenAI.Chat;
72using System.ClientModel.Primitives;
73 
74#pragma warning disable OPENAI001
75 
76BearerTokenPolicy tokenPolicy = new(
77    new DefaultAzureCredential(),
78    "https://cognitiveservices.azure.com/.default");
79 
80ChatClient client = new(
81    model: "gpt-4o-mini",
82    authenticationPolicy: tokenPolicy,
83    options: new OpenAIClientOptions()
84    {
85        Endpoint = new Uri("https://YOUR-RESOURCE.openai.azure.com/openai/v1")
86    });
87```
88 
89## Chat Completions
90 
91### Basic Chat
92 
93```csharp
94using Azure.AI.OpenAI;
95using OpenAI.Chat;
96 
97AzureOpenAIClient azureClient = new(
98    new Uri(endpoint),
99    new DefaultAzureCredential());
100 
101ChatClient chatClient = azureClient.GetChatClient("gpt-4o-mini");
102 
103ChatCompletion completion = chatClient.CompleteChat(
104[
105    new SystemChatMessage("You are a helpful assistant."),
106    new UserChatMessage("What is Azure OpenAI?")
107]);
108 
109Console.WriteLine(completion.Content[0].Text);
110```
111 
112### Async Chat
113 
114```csharp
115ChatCompletion completion = await chatClient.CompleteChatAsync(
116[
117    new SystemChatMessage("You are a helpful assistant."),
118    new UserChatMessage("Explain cloud computing in simple terms.")
119]);
120 
121Console.WriteLine($"Response: {completion.Content[0].Text}");
122Console.WriteLine($"Tokens used: {completion.Usage.TotalTokenCount}");
123```
124 
125### Streaming Chat
126 
127```csharp
128await foreach (StreamingChatCompletionUpdate update 
129    in chatClient.CompleteChatStreamingAsync(messages))
130{
131    if (update.ContentUpdate.Count > 0)
132    {
133        Console.Write(update.ContentUpdate[0].Text);
134    }
135}
136```
137 
138### Chat with Options
139 
140```csharp
141ChatCompletionOptions options = new()
142{
143    MaxOutputTokenCount = 1000,
144    Temperature = 0.7f,
145    TopP = 0.95f,
146    FrequencyPenalty = 0,
147    PresencePenalty = 0
148};
149 
150ChatCompletion completion = await chatClient.CompleteChatAsync(messages, options);
151```
152 
153### Multi-turn Conversation
154 
155```csharp
156List<ChatMessage> messages = new()
157{
158    new SystemChatMessage("You are a helpful assistant."),
159    new UserChatMessage("Hi, can you help me?"),
160    new AssistantChatMessage("Of course! What do you need help with?"),
161    new UserChatMessage("What's the capital of France?")
162};
163 
164ChatCompletion completion = await chatClient.CompleteChatAsync(messages);
165messages.Add(new AssistantChatMessage(completion.Content[0].Text));
166```
167 
168## Structured Outputs (JSON Schema)
169 
170```csharp
171using System.Text.Json;
172 
173ChatCompletionOptions options = new()
174{
175    ResponseFormat = ChatResponseFormat.CreateJsonSchemaFormat(
176        jsonSchemaFormatName: "math_reasoning",
177        jsonSchema: BinaryData.FromBytes("""
178            {
179                "type": "object",
180                "properties": {
181                    "steps": {
182                        "type": "array",
183                        "items": {
184                            "type": "object",
185                            "properties": {
186                                "explanation": { "type": "string" },
187                                "output": { "type": "string" }
188                            },
189                            "required": ["explanation", "output"],
190                            "additionalProperties": false
191                        }
192                    },
193                    "final_answer": { "type": "string" }
194                },
195                "required": ["steps", "final_answer"],
196                "additionalProperties": false
197            }
198            """u8.ToArray()),
199        jsonSchemaIsStrict: true)
200};
201 
202ChatCompletion completion = await chatClient.CompleteChatAsync(
203    [new UserChatMessage("How can I solve 8x + 7 = -23?")],
204    options);
205 
206using JsonDocument json = JsonDocument.Parse(completion.Content[0].Text);
207Console.WriteLine($"Answer: {json.RootElement.GetProperty("final_answer")}");
208```
209 
210## Reasoning Models (o1, o4-mini)
211 
212```csharp
213ChatCompletionOptions options = new()
214{
215    ReasoningEffortLevel = ChatReasoningEffortLevel.Low,
216    MaxOutputTokenCount = 100000
217};
218 
219ChatCompletion completion = await chatClient.CompleteChatAsync(
220[
221    new DeveloperChatMessage("You are a helpful assistant"),
222    new UserChatMessage("Explain the theory of relativity")
223], options);
224```
225 
226## Azure AI Search Integration (RAG)
227 
228```csharp
229using Azure.AI.OpenAI.Chat;
230 
231#pragma warning disable AOAI001
232 
233ChatCompletionOptions options = new();
234options.AddDataSource(new AzureSearchChatDataSource()
235{
236    Endpoint = new Uri(searchEndpoint),
237    IndexName = searchIndex,
238    Authentication = DataSourceAuthentication.FromApiKey(searchKey)
239});
240 
241ChatCompletion completion = await chatClient.CompleteChatAsync(
242    [new UserChatMessage("What health plans are available?")],
243    options);
244 
245ChatMessageContext context = completion.GetMessageContext();
246if (context?.Intent is not null)
247{
248    Console.WriteLine($"Intent: {context.Intent}");
249}
250foreach (ChatCitation citation in context?.Citations ?? [])
251{
252    Console.WriteLine($"Citation: {citation.Content}");
253}
254```
255 
256## Embeddings
257 
258```csharp
259using OpenAI.Embeddings;
260 
261EmbeddingClient embeddingClient = azureClient.GetEmbeddingClient("text-embedding-ada-002");
262 
263OpenAIEmbedding embedding = await embeddingClient.GenerateEmbeddingAsync("Hello, world!");
264ReadOnlyMemory<float> vector = embedding.ToFloats();
265 
266Console.WriteLine($"Embedding dimensions: {vector.Length}");
267```
268 
269### Batch Embeddings
270 
271```csharp
272List<string> inputs = new()
273{
274    "First document text",
275    "Second document text",
276    "Third document text"
277};
278 
279OpenAIEmbeddingCollection embeddings = await embeddingClient.GenerateEmbeddingsAsync(inputs);
280 
281foreach (OpenAIEmbedding emb in embeddings)
282{
283    Console.WriteLine($"Index {emb.Index}: {emb.ToFloats().Length} dimensions");
284}
285```
286 
287## Image Generation (DALL-E)
288 
289```csharp
290using OpenAI.Images;
291 
292ImageClient imageClient = azureClient.GetImageClient("dall-e-3");
293 
294GeneratedImage image = await imageClient.GenerateImageAsync(
295    "A futuristic city skyline at sunset",
296    new ImageGenerationOptions
297    {
298        Size = GeneratedImageSize.W1024xH1024,
299        Quality = GeneratedImageQuality.High,
300        Style = GeneratedImageStyle.Vivid
301    });
302 
303Console.WriteLine($"Image URL: {image.ImageUri}");
304```
305 
306## Audio (Whisper)
307 
308### Transcription
309 
310```csharp
311using OpenAI.Audio;
312 
313AudioClient audioClient = azureClient.GetAudioClient("whisper");
314 
315AudioTranscription transcription = await audioClient.TranscribeAudioAsync(
316    "audio.mp3",
317    new AudioTranscriptionOptions
318    {
319        ResponseFormat = AudioTranscriptionFormat.Verbose,
320        Language = "en"
321    });
322 
323Console.WriteLine(transcription.Text);
324```
325 
326### Text-to-Speech
327 
328```csharp
329BinaryData speech = await audioClient.GenerateSpeechAsync(
330    "Hello, welcome to Azure OpenAI!",
331    GeneratedSpeechVoice.Alloy,
332    new SpeechGenerationOptions
333    {
334        SpeedRatio = 1.0f,
335        ResponseFormat = GeneratedSpeechFormat.Mp3
336    });
337 
338await File.WriteAllBytesAsync("output.mp3", speech.ToArray());
339```
340 
341## Function Calling (Tools)
342 
343```csharp
344ChatTool getCurrentWeatherTool = ChatTool.CreateFunctionTool(
345    functionName: "get_current_weather",
346    functionDescription: "Get the current weather in a given location",
347    functionParameters: BinaryData.FromString("""
348        {
349            "type": "object",
350            "properties": {
351                "location": {
352                    "type": "string",
353                    "description": "The city and state, e.g. San Francisco, CA"
354                },
355                "unit": {
356                    "type": "string",
357                    "enum": ["celsius", "fahrenheit"]
358                }
359            },
360            "required": ["location"]
361        }
362        """));
363 
364ChatCompletionOptions options = new()
365{
366    Tools = { getCurrentWeatherTool }
367};
368 
369ChatCompletion completion = await chatClient.CompleteChatAsync(
370    [new UserChatMessage("What's the weather in Seattle?")],
371    options);
372 
373if (completion.FinishReason == ChatFinishReason.ToolCalls)
374{
375    foreach (ChatToolCall toolCall in completion.ToolCalls)
376    {
377        Console.WriteLine($"Function: {toolCall.FunctionName}");
378        Console.WriteLine($"Arguments: {toolCall.FunctionArguments}");
379    }
380}
381```
382 
383## Key Types Reference
384 
385| Type | Purpose |
386|------|---------|
387| `AzureOpenAIClient` | Top-level client for Azure OpenAI |
388| `ChatClient` | Chat completions |
389| `EmbeddingClient` | Text embeddings |
390| `ImageClient` | Image generation (DALL-E) |
391| `AudioClient` | Audio transcription/TTS |
392| `ChatCompletion` | Chat response |
393| `ChatCompletionOptions` | Request configuration |
394| `StreamingChatCompletionUpdate` | Streaming response chunk |
395| `ChatMessage` | Base message type |
396| `SystemChatMessage` | System prompt |
397| `UserChatMessage` | User input |
398| `AssistantChatMessage` | Assistant response |
399| `DeveloperChatMessage` | Developer message (reasoning models) |
400| `ChatTool` | Function/tool definition |
401| `ChatToolCall` | Tool invocation request |
402 
403## Best Practices
404 
4051. **Use Entra ID in production** — Avoid API keys; use `DefaultAzureCredential`
4062. **Reuse client instances** — Create once, share across requests
4073. **Handle rate limits** — Implement exponential backoff for 429 errors
4084. **Stream for long responses** — Use `CompleteChatStreamingAsync` for better UX
4095. **Set appropriate timeouts** — Long completions may need extended timeouts
4106. **Use structured outputs** — JSON schema ensures consistent response format
4117. **Monitor token usage** — Track `completion.Usage` for cost management
4128. **Validate tool calls** — Always validate function arguments before execution
413 
414## Error Handling
415 
416```csharp
417using Azure;
418 
419try
420{
421    ChatCompletion completion = await chatClient.CompleteChatAsync(messages);
422}
423catch (RequestFailedException ex) when (ex.Status == 429)
424{
425    Console.WriteLine("Rate limited. Retry after delay.");
426    await Task.Delay(TimeSpan.FromSeconds(10));
427}
428catch (RequestFailedException ex) when (ex.Status == 400)
429{
430    Console.WriteLine($"Bad request: {ex.Message}");
431}
432catch (RequestFailedException ex)
433{
434    Console.WriteLine($"Azure OpenAI error: {ex.Status} - {ex.Message}");
435}
436```
437 
438## Related SDKs
439 
440| SDK | Purpose | Install |
441|-----|---------|---------|
442| `Azure.AI.OpenAI` | Azure OpenAI client (this SDK) | `dotnet add package Azure.AI.OpenAI` |
443| `OpenAI` | OpenAI compatibility | `dotnet add package OpenAI` |
444| `Azure.Identity` | Authentication | `dotnet add package Azure.Identity` |
445| `Azure.Search.Documents` | AI Search for RAG | `dotnet add package Azure.Search.Documents` |
446 
447## Reference Links
448 
449| Resource | URL |
450|----------|-----|
451| NuGet Package | https://www.nuget.org/packages/Azure.AI.OpenAI |
452| API Reference | https://learn.microsoft.com/dotnet/api/azure.ai.openai |
453| Migration Guide (1.0→2.0) | https://learn.microsoft.com/azure/ai-services/openai/how-to/dotnet-migration |
454| Quickstart | https://learn.microsoft.com/azure/ai-services/openai/quickstart |
455| GitHub Source | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/openai/Azure.AI.OpenAI |
456