Aspire.Azure.AI.Extensions.OpenAI
17.0.0-preview.1.26567.5
Prefix Reserved
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
<PackageReference Include="Aspire.Azure.AI.Extensions.OpenAI" Version="17.0.0-preview.1.26567.5" />
<PackageVersion Include="Aspire.Azure.AI.Extensions.OpenAI" Version="17.0.0-preview.1.26567.5" />
<PackageReference Include="Aspire.Azure.AI.Extensions.OpenAI" />
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"
#:package Aspire.Azure.AI.Extensions.OpenAI@17.0.0-preview.1.26567.5
#addin nuget:?package=Aspire.Azure.AI.Extensions.OpenAI&version=17.0.0-preview.1.26567.5&prerelease
#tool nuget:?package=Aspire.Azure.AI.Extensions.OpenAI&version=17.0.0-preview.1.26567.5&prerelease
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
- Azure AI Extensions OpenAI SDK
- https://github.com/microsoft/aspire/tree/main/src/Components/README.md
Feedback & contributing
| Product | Versions 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. |
-
net10.0
- Aspire.OpenAI (>= 17.0.0-preview.1.26567.5)
- Azure.AI.Extensions.OpenAI (>= 3.0.0-beta.3)
- Azure.Core (>= 1.63.0)
- Microsoft.Extensions.AI (>= 10.10.0)
- Microsoft.Extensions.AI.OpenAI (>= 10.10.1)
- Microsoft.Extensions.Azure (>= 1.14.1)
- Microsoft.Extensions.Configuration.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Configuration.Binder (>= 10.0.15)
- Microsoft.Extensions.Configuration.EnvironmentVariables (>= 10.0.15)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Diagnostics.HealthChecks (>= 10.0.15)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Logging (>= 10.0.15)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Options (>= 10.0.15)
- Microsoft.Extensions.Primitives (>= 10.0.15)
- OpenAI (>= 2.14.0)
- OpenTelemetry.Extensions.Hosting (>= 1.18.0)
-
net11.0
- Aspire.OpenAI (>= 17.0.0-preview.1.26567.5)
- Azure.AI.Extensions.OpenAI (>= 3.0.0-beta.3)
- Azure.Core (>= 1.63.0)
- Microsoft.Extensions.AI (>= 10.10.0)
- Microsoft.Extensions.AI.OpenAI (>= 10.10.1)
- Microsoft.Extensions.Azure (>= 1.14.1)
- Microsoft.Extensions.Configuration.Binder (>= 11.0.0)
- Microsoft.Extensions.Configuration.EnvironmentVariables (>= 11.0.0)
- Microsoft.Extensions.Diagnostics.HealthChecks (>= 11.0.0)
- Microsoft.Extensions.Logging (>= 11.0.0)
- OpenAI (>= 2.14.0)
- OpenTelemetry.Extensions.Hosting (>= 1.18.0)
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 |