Azure OpenAI integration

🧪 Preview

Azure OpenAI Service provides access to OpenAI’s powerful language and embedding models with the security and enterprise promise of Azure. The Aspire Azure OpenAI integration enables you to connect to Azure OpenAI services from your applications.

Hosting integration

The Aspire Azure OpenAI hosting integration models the Azure OpenAI service as the AzureOpenAIResource type. To access this type and APIs for expressing them within your AppHost project, install the 📦 Aspire.Hosting.Azure.CognitiveServices NuGet package:

Aspire CLI

Aspire CLI — 添加 Aspire.Hosting.Azure.CognitiveServices 包

aspire add azure-cognitiveservices

Aspire CLI 是交互式的；按提示选择合适的搜索结果：

Aspire CLI — 输出示例

Select an integration to add:

> azure-cognitiveservices (Aspire.Hosting.Azure.CognitiveServices)
> Other results listed as selectable options...

注意

如果只有一个结果，会自动选择。仍需确认版本。

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.Azure.CognitiveServices@*

PackageReference (*.csproj)

XML — 添加 Aspire.Hosting.Azure.CognitiveServices 包引用

<PackageReference Include="Aspire.Hosting.Azure.CognitiveServices" Version="*" />

Add an Azure OpenAI resource

To add an Azure OpenAI resource to your AppHost project, call the AddAzureOpenAI method providing a name:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddAzureOpenAI("openai");

builder.AddProject<Projects.ExampleProject>()
    .WithReference(openai);

// After adding all resources, run the app...

The preceding code adds an Azure OpenAI resource named openai to the AppHost project. The WithReference method passes the connection information to the ExampleProject project.

警告

When you call AddAzureOpenAI, it implicitly calls AddAzureProvisioning—which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see Local provisioning: Configuration.

Add an Azure OpenAI deployment resource

To add an Azure OpenAI deployment resource, call the AddDeployment method:

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddAzureOpenAI("openai");

openai.AddDeployment(
    name: "preview",
    modelName: "gpt-4.5-preview",
    modelVersion: "2025-02-27");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(openai)
       .WaitFor(openai);

// After adding all resources, run the app...

The preceding code:

• Adds an Azure OpenAI resource named openai.
• Adds an Azure OpenAI deployment resource named preview with a model name of gpt-4.5-preview. The model name must correspond to an available model in the Azure OpenAI service.

Connect to an existing Azure OpenAI service

You might have an existing Azure OpenAI service that you want to connect to. You can chain a call to annotate that your AzureOpenAIResource is an existing resource:

var builder = DistributedApplication.CreateBuilder(args);

var existingOpenAIName = builder.AddParameter("existingOpenAIName");
var existingOpenAIResourceGroup = builder.AddParameter("existingOpenAIResourceGroup");

var openai = builder.AddAzureOpenAI("openai")
    .AsExisting(existingOpenAIName, existingOpenAIResourceGroup);

builder.AddProject<Projects.ExampleProject>()
    .WithReference(openai);

// After adding all resources, run the app...

For more information on treating Azure OpenAI resources as existing resources, see Use existing Azure resources.

Note

Alternatively, instead of representing an Azure OpenAI resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn’t work with role assignments or infrastructure customizations. For more information, see Add existing Azure resources with connection strings.

Provisioning-generated Bicep

If you’re new to Bicep, it’s a domain-specific language for defining Azure resources. With Aspire, you don’t need to write Bicep by-hand, instead the provisioning APIs generate Bicep for you. When you publish your app, the generated Bicep provisions an Azure OpenAI resource with standard defaults.

Bicep — openai.bicep

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

resource openai 'Microsoft.CognitiveServices/accounts@2024-10-01' = {
  name: take('openai-${uniqueString(resourceGroup().id)}', 64)
  location: location
  kind: 'OpenAI'
  properties: {
    customSubDomainName: toLower(take(concat('openai', uniqueString(resourceGroup().id)), 24))
    publicNetworkAccess: 'Enabled'
    disableLocalAuth: true
  }
  sku: {
    name: 'S0'
  }
  tags: {
    'aspire-resource-name': 'openai'
  }
}

resource preview 'Microsoft.CognitiveServices/accounts/deployments@2024-10-01' = {
  name: 'preview'
  properties: {
    model: {
      format: 'OpenAI'
      name: 'gpt-4.5-preview'
      version: '2025-02-27'
    }
  }
  sku: {
    name: 'Standard'
    capacity: 8
  }
  parent: openai
}

output connectionString string = 'Endpoint=${openai.properties.endpoint}'

output name string = openai.name

The preceding Bicep is a module that provisions an Azure Cognitive Services resource. Additionally, role assignments are created for the Azure resource in a separate module:

Bicep — openai-roles.bicep

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param openai_outputs_name string

param principalType string

param principalId string

resource openai 'Microsoft.CognitiveServices/accounts@2024-10-01' existing = {
  name: openai_outputs_name
}

resource openai_CognitiveServicesOpenAIUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(openai.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '5e0bd9bd-7b93-4f28-af87-19fc36ad61bd'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '5e0bd9bd-7b93-4f28-af87-19fc36ad61bd')
    principalType: principalType
  }
  scope: openai
}

The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly will be overwritten, so make changes through the C# provisioning APIs to ensure they are reflected in the generated files.

Customize provisioning infrastructure

All Aspire Azure resources are subclasses of the AzureProvisioningResource type. This enables customization of the generated Bicep by providing a fluent API to configure the Azure resources—using the ConfigureInfrastructure API:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureOpenAI("openai")
    .ConfigureInfrastructure(infra =>
    {
        var resources = infra.GetProvisionableResources();
        var account = resources.OfType<CognitiveServicesAccount>().Single();

        account.Sku = new CognitiveServicesSku
        {
            Tier = CognitiveServicesSkuTier.Enterprise,
            Name = "E0"
        };
        account.Tags.Add("ExampleKey", "Example value");
    });

The preceding code:

• Chains a call to the ConfigureInfrastructure API:
  • The infra parameter is an instance of the `AzureResourceInfrastructure type.
  • The provisionable resources are retrieved by calling the GetProvisionableResources method.
  • The single CognitiveServicesAccount resource is retrieved.
  • The CognitiveServicesAccount property is assigned to a new instance of CognitiveServices.CognitiveServicesSku with an E0 name and CognitiveServicesSkuTier.Enterprise` tier.
  • A tag is added to the Cognitive Services resource with a key of ExampleKey and a value of Example value.

Client integration

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="*" />

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");

提示

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

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.