Azure OpenAI client integration

🧪 Preview

The Aspire Azure OpenAI client integration is used to connect to an Azure OpenAI service. To get started with the Aspire Azure OpenAI client integration, install the 📦 Aspire.Azure.AI.OpenAI NuGet package.

.NET CLI

.NET CLI — Add Aspire.Azure.AI.OpenAI package

dotnet add package Aspire.Azure.AI.OpenAI

Program.cs (C# file-based app)

Program.cs

#:package Aspire.Azure.AI.OpenAI@*

PackageReference (*.csproj)

XML — Add Aspire.Azure.AI.OpenAI package reference

<PackageReference Include="Aspire.Azure.AI.OpenAI" Version="*" />

For an introduction to working with the Azure OpenAI client integration, see Get started with the Azure OpenAI integration.

Add Azure OpenAI client

In the Program.cs file of your client-consuming project, call the AddAzureOpenAIClient extension method to register an AzureOpenAIClient for use via the dependency injection container. The method takes a connection name parameter:

builder.AddAzureOpenAIClient(connectionName: "openai");

Tips

The connectionName parameter must match the name used when adding the OpenAI resource in the AppHost project.

After adding the AzureOpenAIClient, you can retrieve the client instance using dependency injection:

public class ExampleService(AzureOpenAIClient client)
{
    // Use client...
}

Add Azure OpenAI client with registered IChatClient

If you’re interested in using the IChatClient interface, with the OpenAI client, simply chain either of the following APIs to the AddAzureOpenAIClient method:

• AddChatClient: Registers a singleton IChatClient in the services provided by the AspireOpenAIClientBuilder.
• AddKeyedChatClient: Registers a keyed singleton IChatClient in the services provided by the AspireOpenAIClientBuilder.

For example, consider the following C# code that adds an IChatClient to the DI container:

builder.AddAzureOpenAIClient(connectionName: "openai")
       .AddChatClient("deploymentName");

Similarly, you can add a keyed IChatClient with the following C# code:

builder.AddAzureOpenAIClient(connectionName: "openai")
       .AddKeyedChatClient("serviceKey", "deploymentName");

After adding the IChatClient, you can retrieve the client instance using dependency injection:

public class ExampleService(IChatClient chatClient)
{
    public async Task<string> GetResponseAsync(string userMessage)
    {
        var response = await chatClient.CompleteAsync(userMessage);
        return response.Message.Text ?? string.Empty;
    }
}

For more information on IChatClient and Microsoft.Extensions.AI, see Unified AI Building Blocks for .NET.

Configure Azure OpenAI client settings

The Aspire Azure OpenAI library provides a set of settings to configure the Azure OpenAI client. The AddAzureOpenAIClient method exposes an optional configureSettings parameter of type Action<AzureOpenAISettings>?. To configure settings inline, consider the following example:

builder.AddAzureOpenAIClient(
    connectionName: "openai",
    configureSettings: settings =>
    {
        settings.DisableTracing = true;

        var uriString = builder.Configuration["AZURE_OPENAI_ENDPOINT"]
            ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");

        settings.Endpoint = new Uri(uriString);
    });

The preceding code sets the AzureOpenAISettings.DisableTracing property to true, and sets the AzureOpenAISettings.Endpoint property to the Azure OpenAI endpoint.

Configure Azure OpenAI client builder options

To configure the AzureOpenAIClientOptions for the client, you can use the AddAzureOpenAIClient method. This method takes an optional configureClientBuilder parameter of type Action<IAzureClientBuilder<OpenAIClient, AzureOpenAIClientOptions>>?. Consider the following example:

builder.AddAzureOpenAIClient(
    connectionName: "openai",
    configureClientBuilder: clientBuilder =>
    {
        clientBuilder.ConfigureOptions(options =>
        {
            options.UserAgentApplicationId = "CLIENT_ID";
        });
    });

The client builder is an instance of the IAzureClientBuilder type, which provides a fluent API to configure the client options. The preceding code sets the AzureOpenAIClientOptions.UserAgentApplicationId property to CLIENT_ID.

Add Azure OpenAI client from configuration

Additionally, the package provides the AddOpenAIClientFromConfiguration extension method to register an OpenAIClient or AzureOpenAIClient instance based on the provided connection string. This method follows these rules:

• If the Endpoint attribute is empty or missing, an OpenAIClient instance is registered using the provided key, for example, Key={key};.
• If the IsAzure attribute is true, an AzureOpenAIClient is registered; otherwise, an OpenAIClient is registered, for example, Endpoint={azure_endpoint};Key={key};IsAzure=true registers an AzureOpenAIClient, while Endpoint=https://localhost:18889;Key={key} registers an OpenAIClient.
• If the Endpoint attribute contains ".azure.", an AzureOpenAIClient is registered; otherwise, an OpenAIClient is registered, for example, Endpoint=https://{account}.azure.com;Key={key};.

Consider the following example:

builder.AddOpenAIClientFromConfiguration("openai");

Tip

A valid connection string must contain at least an Endpoint or a Key.

Consider the following example connection strings and whether they register an OpenAIClient or AzureOpenAIClient:

Example connection string	Registered client type
Endpoint=https://{account_name}.openai.azure.com/;Key={account_key}	AzureOpenAIClient
Endpoint=https://{account_name}.openai.azure.com/;Key={account_key};IsAzure=false	OpenAIClient
Endpoint=https://{account_name}.openai.azure.com/;Key={account_key};IsAzure=true	AzureOpenAIClient
Endpoint=https://localhost:18889;Key={account_key}	OpenAIClient

Properties of the Azure OpenAI resources

When you use the WithReference method to pass an Azure OpenAI resource from the AppHost project to a consuming client project, several properties are available to use in the consuming project.

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Uri property of a resource called openai becomes OPENAI_URI.

Azure OpenAI service

The Azure OpenAI resource exposes the following connection property:

Property Name	Description
Uri	The service endpoint URI

Azure OpenAI deployment

The Azure OpenAI deployment resource inherits the property from its parent service and adds:

Property Name	Description
ModelName	The deployment/model name

For example, if you reference an Azure OpenAI resource named openai in your AppHost project, the following environment variables will be available in the consuming project:

• OPENAI_URI

If you reference a deployment resource:

• {DEPLOYMENT}_URI
• {DEPLOYMENT}_MODELNAME

Add keyed Azure OpenAI clients

There might be situations where you want to register multiple OpenAIClient instances with different connection names. To register keyed Azure OpenAI clients, call the AddKeyedAzureOpenAIClient method:

builder.AddKeyedAzureOpenAIClient(name: "chat");
builder.AddKeyedAzureOpenAIClient(name: "code");

Caution

When using keyed services, ensure that your Azure OpenAI resource configures two named connections, one for chat and one for code.

Then you can retrieve the client instances using dependency injection. For example, to retrieve the clients from a service:

public class ExampleService(
    [KeyedService("chat")] OpenAIClient chatClient,
    [KeyedService("code")] OpenAIClient codeClient)
{
    // Use clients...
}

For more information, see Keyed services in .NET.

Add keyed Azure OpenAI clients from configuration

The same functionality and rules exist for keyed Azure OpenAI clients as for the nonkeyed clients. You can use the AddKeyedOpenAIClientFromConfiguration extension method to register an OpenAIClient or AzureOpenAIClient instance based on the provided connection string.

Consider the following example:

builder.AddKeyedOpenAIClientFromConfiguration("openai");

This method follows the same rules as detailed in the Add Azure OpenAI client from configuration.

Configuration

The Aspire Azure OpenAI library provides multiple options to configure the Azure OpenAI connection based on the requirements and conventions of your project. Either an Endpoint or a ConnectionString must be supplied.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling AddAzureOpenAIClient:

builder.AddAzureOpenAIClient(connectionName: "openai");

The connection information is retrieved from the ConnectionStrings configuration section. Two connection formats are supported:

• Service endpoint (recommended): Uses the service endpoint with DefaultAzureCredential.

  {
    "ConnectionStrings": {
      "openai": "https://{account_name}.openai.azure.com/"
    }
  }

• Connection string: Includes an API key.

  {
    "ConnectionStrings": {
      "openai": "Endpoint=https://{account_name}.openai.azure.com/;Key={api_key}"
    }
  }

Use configuration providers

The library supports Microsoft.Extensions.Configuration. It loads settings from configuration using the Aspire:Azure:AI:OpenAI key:

{
  "Aspire": {
    "Azure": {
      "AI": {
        "OpenAI": {
          "DisableTracing": false
        }
      }
    }
  }
}

Use inline delegates

You can configure settings inline:

builder.AddAzureOpenAIClient(
    "openai",
    settings => settings.DisableTracing = true);

Observability and telemetry

Aspire integrations automatically set up Logging, Tracing, and Metrics configurations.

Logging

The Aspire Azure OpenAI integration uses the following log categories:

• Azure
• Azure.Core
• Azure.Identity
• Azure.AI.OpenAI

Tracing

The Aspire Azure OpenAI integration will emit the following tracing activities using OpenTelemetry:

• Azure.AI.OpenAI.*
• gen_ai.system - Generic AI system tracing
• gen_ai.operation.name - Operation names for AI calls

Metrics

The Aspire Azure OpenAI integration currently doesn’t support metrics by default due to limitations with the Azure SDK for .NET.