AI integrations compatibility matrix

Este conteúdo não está disponível em sua língua ainda.

Aspire provides several AI hosting and client integrations that enable you to work with different AI services and platforms. This article is a compatibility reference showing which client integrations work with which hosting integrations, along with the recommended pairings and AppHost API examples.

Compatibility matrix

The following table shows the compatibility between Aspire AI hosting and client integrations:

Hosting Integration	Aspire.OpenAI	Aspire.Azure.AI.OpenAI	Aspire.Azure.AI.Inference
`Aspire.Hosting.Foundry`	⚠️ Partial — Foundry Local only (preferred)	⚠️ Partial	❗ Legacy
`Aspire.Hosting.Azure.CognitiveServices`	❌ No	✅ Yes (preferred)	❌ No
`Aspire.Hosting.OpenAI`	✅ Yes (preferred)	✅ Yes	❌ No

Recommended pairings

In general, use an Aspire client integration when one supports the resource and its authentication method. Use Aspire.OpenAI for OpenAI-compatible resources that provide an API key, including Foundry Local. For cloud-provisioned Microsoft Foundry resources, use the OpenAI SDK directly because they authenticate with managed identity.

Microsoft Foundry

For Foundry Local resources, use the Aspire.OpenAI client integration. It provides dependency injection and telemetry for the OpenAI-compatible endpoint and the API key that Foundry Local exposes. Cloud-provisioned Microsoft Foundry resources use managed identity, which Aspire.OpenAI does not support; use the OpenAI SDK directly for those resources.

For more information, see Microsoft Foundry integration.

Hosting integration

The Aspire.Hosting.Foundry package provides the hosting integration. In your app host project:

TypeScript
C#

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();

const 
const foundry: FoundryResource
foundry = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addFoundry(name: string): FoundryResource
Adds a Microsoft Foundry resource to the application model.
addFoundry("foundry").
FoundryResource.runAsFoundryLocal(endpoint?: string): FoundryResource
Configures a Microsoft Foundry resource to use an Aspire-managed or existing Foundry Local service.
runAsFoundryLocal();

const 
const chat: FoundryDeploymentResource
chat = await 
const foundry: FoundryResource
foundry.
FoundryResource.addDeployment(name: string, model: FoundryModel | string, options?: {
    modelVersion?: string;
    format?: string;
} | undefined): FoundryDeploymentResource (+1 overload)
Adds a Microsoft Foundry deployment resource to a Microsoft Foundry resource.
addDeployment('chat', {
  
FoundryModel.name?: string | undefined
name: 'Phi-4',
  
FoundryModel.version?: string | undefined
version: '1',
  
FoundryModel.format?: string | undefined
format: 'Microsoft',
});

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addNodeApp(name: string, appDirectory: string, scriptPath: string): NodeAppResource
Adds a node application to the application model. Node should be available on the PATH.
addNodeApp("api", "./api", "index.js")
    .
ExecutableResource.withReference(source: IResource | EndpointReference | string | uri, options?: {
    connectionName?: string;
    optional?: boolean;
    name?: string;
} | undefined): NodeAppResource (+1 overload)
Adds a reference to another resource
withReference(
const chat: FoundryDeploymentResource
chat);

var builder = DistributedApplication.CreateBuilder(args);

var foundry = builder.AddFoundry("foundry")
    .RunAsFoundryLocal();

var chat = foundry.AddDeployment("chat", FoundryModel.Local.Phi4);

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

Client integration

For Foundry Local, the Aspire.OpenAI package provides the recommended client integration. For its configuration sample, see Connect with Aspire.OpenAI. For cloud-provisioned Foundry resources that authenticate with managed identity, use the OpenAI SDK directly as shown on that page.

Azure Cognitive Services (Azure OpenAI)

For Azure OpenAI resources, use the Aspire.Azure.AI.OpenAI client integration for full Azure-specific features and authentication support. For more information, see Azure OpenAI integration.

Hosting integration

The Aspire.Hosting.Azure.CognitiveServices package provides the hosting integration. In your app host project:

TypeScript
C#

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();

const 
const openai: AzureOpenAIResource
openai = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addAzureOpenAI(name: string): AzureOpenAIResource
Adds an Azure OpenAI resource to the application model.
addAzureOpenAI("openai");

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addNodeApp(name: string, appDirectory: string, scriptPath: string): NodeAppResource
Adds a node application to the application model. Node should be available on the PATH.
addNodeApp("api", "./api", "index.js")
    .
ExecutableResource.withReference(source: IResource | EndpointReference | string | uri, options?: {
    connectionName?: string;
    optional?: boolean;
    name?: string;
} | undefined): NodeAppResource (+1 overload)
Adds a reference to another resource
withReference(
const openai: AzureOpenAIResource
openai);

var builder = DistributedApplication.CreateBuilder(args);

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

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

Client integration

The Aspire.Azure.AI.OpenAI package provides the client integration. In your service project:

builder.AddAzureOpenAIClient("openai");

Direct OpenAI

For direct OpenAI API access, use the Aspire.OpenAI client integration. For more information, see Aspire OpenAI integration (Preview).

Hosting integration

The Aspire.Hosting.OpenAI package provides the hosting integration. In your app host project:

TypeScript
C#

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();

const 
const openai: OpenAIResource
openai = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addOpenAI(name: string): OpenAIResource
Adds an OpenAI parent resource that can host multiple models.
addOpenAI("openai");

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addNodeApp(name: string, appDirectory: string, scriptPath: string): NodeAppResource
Adds a node application to the application model. Node should be available on the PATH.
addNodeApp("api", "./api", "index.js")
    .
ExecutableResource.withReference(source: IResource | EndpointReference | string | uri, options?: {
    connectionName?: string;
    optional?: boolean;
    name?: string;
} | undefined): NodeAppResource (+1 overload)
Adds a reference to another resource
withReference(
const openai: OpenAIResource
openai);

var builder = DistributedApplication.CreateBuilder(args);

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

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

Client integration

The Aspire.OpenAI package provides the client integration. In your service project:

builder.AddOpenAIClient("openai");

Connection string formats

Understanding how hosting and client integrations communicate through connection strings can help you troubleshoot connectivity issues and understand the underlying mechanics.

Each hosting integration generates connection strings in different formats that are consumed by the client integrations.

Hosting integration connection strings

Aspire.Hosting.Foundry

Azure:

Endpoint={Endpoint};EndpointAIInference={EndpointAIInference}models

Foundry Local:

Endpoint={EmulatorServiceUri};Key={ApiKey}

Deployment:

{Parent};Deployment={DeploymentName}

Aspire.Hosting.Azure.CognitiveServices

Deployment:

{ConnectionString};Deployment={DeploymentName}

Aspire.Hosting.OpenAI

Endpoint={Endpoint};Key={Key};Model={Model}

Client integration connection string requirements

Aspire.OpenAI

Expects connection strings in the format:

Endpoint={Endpoint};Key={Key};Deployment={Deployment};Model={Model}

Uses either Deployment or Model (in that order). Deployment is set by Aspire.Hosting.Azure.CognitiveServices while Model is set by Aspire.Hosting.OpenAI.

Aspire.Azure.AI.OpenAI

Expects connection strings in the format:

Endpoint={Endpoint};Key={Key};Deployment={Deployment};Model={Model}

Uses either Deployment or Model (in that order). Deployment is set by Aspire.Hosting.Azure.CognitiveServices while Model is set by Aspire.Hosting.OpenAI.

This integration is a superset of Aspire.OpenAI and supports TokenCredential and Azure-specific features.

Aspire.Azure.AI.Inference

Expects connection strings in the format:

Endpoint={Endpoint};EndpointAIInference={EndpointAIInference};Key={Key};Deployment={DeploymentName};Model={ModelName}

Uses either Deployment or Model (in that order).

Uses EndpointAIInference if available, otherwise Endpoint.

AI integrations compatibility matrix

Compatibility matrix

Recommended pairings

Microsoft Foundry

Hosting integration

Client integration

Azure Cognitive Services (Azure OpenAI)

Hosting integration

Client integration

Direct OpenAI

Hosting integration

Client integration

Connection string formats

Hosting integration connection strings

Aspire.Hosting.Foundry

Aspire.Hosting.Azure.CognitiveServices

Aspire.Hosting.OpenAI

Client integration connection string requirements

Aspire.OpenAI

Aspire.Azure.AI.OpenAI

Aspire.Azure.AI.Inference

See also