Aspire.Azure.AI.Extensions.OpenAI 17.0.0-preview.1.26567.5

Prefix Reserved
This is a prerelease version of Aspire.Azure.AI.Extensions.OpenAI.
dotnet add package Aspire.Azure.AI.Extensions.OpenAI --version 17.0.0-preview.1.26567.5
                    
NuGet\Install-Package Aspire.Azure.AI.Extensions.OpenAI -Version 17.0.0-preview.1.26567.5
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Aspire.Azure.AI.Extensions.OpenAI" Version="17.0.0-preview.1.26567.5" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Aspire.Azure.AI.Extensions.OpenAI" Version="17.0.0-preview.1.26567.5" />
                    
Directory.Packages.props
<PackageReference Include="Aspire.Azure.AI.Extensions.OpenAI" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Aspire.Azure.AI.Extensions.OpenAI --version 17.0.0-preview.1.26567.5
                    
#r "nuget: Aspire.Azure.AI.Extensions.OpenAI, 17.0.0-preview.1.26567.5"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Aspire.Azure.AI.Extensions.OpenAI@17.0.0-preview.1.26567.5
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Aspire.Azure.AI.Extensions.OpenAI&version=17.0.0-preview.1.26567.5&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=Aspire.Azure.AI.Extensions.OpenAI&version=17.0.0-preview.1.26567.5&prerelease
                    
Install as a Cake Tool

Aspire.Azure.AI.Extensions.OpenAI library

Registers the Azure SDK's ProjectOpenAIClient and its OpenAIClient alias in the DI container as singletons, with Foundry project configuration, Microsoft Entra authentication, and Microsoft.Extensions.AI telemetry.

Also registers the standard OpenAI SDK's OpenAIClient for Azure OpenAI account endpoints, with Microsoft Entra or API-key authentication and the same chat/embedding helpers.

Getting started

Prerequisites

An Azure subscription and a Microsoft Entra identity authorized to invoke a deployed model or agent, or an API key for account-based access. Use AddAzureProjectOpenAIClient for a Foundry project endpoint, or AddAzureOpenAIClient for an Azure OpenAI account. Project clients do not accept API keys or account/Foundry Local endpoints.

Install the package

Install the Aspire Azure AI Extensions OpenAI library with NuGet:

dotnet add package Aspire.Azure.AI.Extensions.OpenAI

Usage example

In the consuming application's Program.cs, register the client with a connection name:

builder.AddAzureProjectOpenAIClient("ai");
{
  "ConnectionStrings": {
    "ai": "Endpoint=https://account.services.ai.azure.com/api/projects/project"
  }
}

A bare project URI is also accepted. Resolve Azure.AI.Extensions.OpenAI.ProjectOpenAIClient or OpenAI.OpenAIClient from dependency injection; both refer to the same instance.

using Azure.AI.Extensions.OpenAI;

public class AgentService(ProjectOpenAIClient client)
{
    public ProjectOpenAIClient Client => client;
}

For Microsoft.Extensions.AI chat or embeddings:

var clientBuilder = builder.AddAzureProjectOpenAIClient("ai");
clientBuilder.AddChatClient("chat");
clientBuilder.AddEmbeddingGenerator("embeddings");

Resolve IChatClient or IEmbeddingGenerator<string, Embedding<float>> from dependency injection. Model names refer to deployments available to the project. An optional Deployment=chat or Model=chat connection-string field supplies the default model; do not specify both.

For prompt agents, use the registered ProjectOpenAIClient:

using Azure.AI.Extensions.OpenAI;

var responses = client.GetProjectResponsesClientForAgent(new AgentReference("my-agent"));
var response = await responses.CreateResponseAsync("Hello!");

Hosted Responses agents use GetProjectResponsesClientForAgentEndpoint("my-agent") instead. Responses APIs may require an OPENAI001 experimental-API warning suppression.

When manually adapting a model Responses client with GetProjectResponsesClientForModel("chat").AsIChatClient(), also supply ChatOptions.ModelId = "chat" on requests. The Microsoft.Extensions.AI adapter does not infer the model from the project SDK's defaults. This is not required by the AddChatClient("chat") helper, which uses the Chat Completions API.

Keyed clients

builder.AddKeyedAzureProjectOpenAIClient("ai")
    .AddKeyedChatClient("chat-client", "chat");

Resolve the SDK client with service key ai, or the IChatClient with key chat-client.

Configuration

Settings are applied in this order: Aspire:Azure:AI:Extensions:OpenAI, its connection-specific subsection, the connection string, and finally configureSettings. Root and connection-specific ClientOptions are bound before configureClientBuilder.

Use a connection string

Provide ConnectionStrings:ai as shown in the usage example. Include Deployment=chat when model helpers should use a default deployment instead of an explicit method argument.

Use configuration providers

{
  "Aspire": {
    "Azure": {
      "AI": {
        "Extensions": {
          "OpenAI": {
            "DisableTracing": false,
            "DisableMetrics": false,
            "EnableSensitiveTelemetryData": false,
            "ai": {
              "Endpoint": "https://account.services.ai.azure.com/api/projects/project",
              "ClientOptions": {
                "NetworkTimeout": "00:01:00"
              }
            }
          }
        }
      }
    }
  }
}

Use inline delegates

Without a connection string, settings can be supplied entirely in code:

using Azure.Identity;
using Microsoft.Extensions.Azure;

builder.AddAzureProjectOpenAIClient("ai",
    configureSettings: settings =>
    {
        settings.Endpoint = new Uri("https://account.services.ai.azure.com/api/projects/project");
        settings.Credential = new AzureCliCredential();
    },
    configureClientBuilder: client => client.ConfigureOptions(options =>
    {
        options.NetworkTimeout = TimeSpan.FromSeconds(60);
    }));

Without an explicit credential, Aspire uses a development credential locally and managed identity in Azure. API-key connection strings are rejected.

Azure OpenAI account clients

For an Azure OpenAI account, keep the existing chat-registration pattern:

builder.AddAzureOpenAIClient("chat").AddChatClient();
{
  "ConnectionStrings": {
    "chat": "Endpoint=https://account.openai.azure.com/;Deployment=chat"
  }
}

The account endpoint is normalized to /openai/v1/. An existing HTTPS v1 endpoint is also accepted; project endpoints and legacy deployment-specific routes are rejected. Resolve OpenAI.OpenAIClient or IChatClient, not Azure.AI.OpenAI.AzureOpenAIClient.

Without a key, the registration uses Microsoft Entra authentication and Aspire's default Azure credential selection. Supply a custom credential through configureSettings or configureClientBuilder.WithCredential. The default token scope is https://ai.azure.com/.default; set TokenScope for other Azure cloud audiences. A Key connection-string field or settings property selects API-key authentication instead.

builder.AddAzureOpenAIClient("chat",
    configureSettings: settings =>
    {
        settings.Credential = new AzureCliCredential();
    },
    configureClientBuilder: client => client.ConfigureOptions(options =>
    {
        options.NetworkTimeout = TimeSpan.FromSeconds(60);
    }))
    .AddChatClient();

builder.AddKeyedAzureOpenAIClient("other-account")
    .AddKeyedChatClient("other-chat", "deployment");

Account settings use Aspire:Azure:AI:OpenAI and its connection-specific subsection, followed by the connection string and configureSettings. Root/named ClientOptions and the client callback customize OpenAIClientOptions. DisableTracing, DisableMetrics, and EnableSensitiveTelemetryData have the same meaning as for project clients. Use distinct service keys when registering multiple account/project clients.

In the AppHost, use Aspire.Hosting.Azure.CognitiveServices and Aspire.Hosting.Dotnet, and keep the deployment reference.

var chat = builder.AddAzureOpenAI("openai")
    .AddDeployment("chat", "gpt-4o", "2024-05-13");

builder.AddDotnetProject("app", "../MyApp/MyApp.csproj").WithReference(chat);

AppHost extensions

Install Aspire.Hosting.Foundry in the AppHost:

dotnet add package Aspire.Hosting.Foundry
dotnet add package Aspire.Hosting.Dotnet
using Aspire.Hosting.Foundry;

var foundry = builder.AddFoundry("foundry");
var project = foundry.AddProject("ai");
var chat = project.AddModelDeployment("chat", FoundryModel.OpenAI.Gpt5Mini);

builder.AddDotnetProject("app", "../MyApp/MyApp.csproj")
    .WithReference(foundry)
    .WithReference(project)
    .WaitFor(chat);

Register builder.AddAzureProjectOpenAIClient("ai").AddChatClient("chat") in MyApp. The project reference supplies the endpoint; the account reference configures runtime identity and Foundry access. A model-deployment reference alone supplies an account endpoint, not a project endpoint.

Telemetry and health checks

Chat and embedding helpers register Microsoft.Extensions.AI telemetry. The activity sources and meters are Experimental.Microsoft.Extensions.AI and Microsoft.Extensions.AI; exporters come from the application's OpenTelemetry configuration.

DisableTracing and DisableMetrics independently disable the respective subscriptions. The helpers retain the telemetry wrapper when either signal is enabled, so disabling tracing does not disable metrics. EnableSensitiveTelemetryData controls capture of message content in the helpers; it defaults to false unless OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true. Direct SDK calls use the SDK's own diagnostic options, not the Microsoft.Extensions.AI wrappers.

No health check is registered: the integration does not make billable inference calls or require model-list permissions for a health probe.

Migration from retired client integrations

Aspire.Azure.AI.OpenAI and Aspire.Azure.AI.Inference are no longer produced, following microsoft/aspire#20401. Previously published versions remain available. Aspire.OpenAI, Aspire.Hosting.Foundry, and the Azure OpenAI hosting integration remain supported.

For a Foundry project, replace the old package with this package, replace AddAzureOpenAIClient or AddAzureChatCompletionsClient with AddAzureProjectOpenAIClient, and provide the project endpoint, not the old account/inference endpoint. Replace API-key authentication with Microsoft Entra credentials and grant the runtime identity the permissions it needs.

For Azure OpenAI accounts, replace the old package with this package and keep AddAzureOpenAIClient / AddKeyedAzureOpenAIClient and the existing chat/embedding helpers. The registration now uses the standard OpenAI SDK and v1 routes, while preserving Entra authentication and account connection strings. Settings/builder types now live in Aspire.Azure.AI.Extensions.OpenAI; client-options callbacks use OpenAIClientOptions instead of AzureOpenAIClientOptions. This is registration-pattern compatibility, not binary compatibility with the retired package.

SDK consumers must replace AzureOpenAIClient, ChatCompletionsClient, or EmbeddingsClient with OpenAIClient for account access, or ProjectOpenAIClient for project access. Inference SDK request/response types are not interchangeable with the OpenAI SDK types.

AddOpenAIClientFromConfiguration and AddKeyedOpenAIClientFromConfiguration are available in this replacement package. They select generic OpenAI-compatible, Azure account, or Foundry project registration from the connection string. Existing OpenAI-versus-Azure applications can retain their registration code:

builder.AddOpenAIClientFromConfiguration("chat").AddChatClient();

The same registration consumes the model connection supplied by Aspire.Hosting.Foundry for both Foundry Local and Azure Foundry. Local connections use their API key and Model; Azure account connections use Entra authentication (or a supplied key) and Deployment. No application-side emulator flag or switch is needed. Azure account endpoints use v1 routes; project endpoints use the project SDK. An explicit IsAzure=true or IsAzure=false field overrides endpoint-host detection, including custom Azure domains. An invalid IsAzure value is rejected.

Without a connection string, the helper preserves the original default of reading Aspire:OpenAI settings. Use the explicit Azure registration methods when configuring Azure clients entirely through settings or delegates.

See Azure's OpenAI SDK migration guide for v1 API differences and scenario-specific limitations.

For project and agent-management operations rather than inference, use Aspire.Azure.AI.Projects and AddAzureAIProjectClient.

Additional documentation

Feedback & contributing

https://github.com/microsoft/aspire

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed.  net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
17.0.0-preview.1.26567.5 0 11/18/2026