Get started with the 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.

In this introduction, you'll see how to install and use the Aspire Azure OpenAI integrations in a simple configuration. If you already have this knowledge, see Azure OpenAI Hosting integration for full reference details.

Note

To follow this guide, you must have created an Aspire solution to work with. To learn how to do that, see Build your first Aspire app.

Set up hosting integration

To begin, install the Aspire Azure OpenAI Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure OpenAI resources from your Aspire hosting projects:

Install the NuGet package

dotnet add package Aspire.Hosting.Azure.CognitiveServices

Next, in the AppHost project, create an Azure OpenAI resource and pass it to the consuming client projects:

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...
  
builder.Build().Run();

The preceding code adds an Azure OpenAI resource named openai to the AppHost project, configures a deployment with a specific model, and passes the connection information to the ExampleProject project.

Caution

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.

Tip

This is the simplest implementation of Azure OpenAI resources in the AppHost. There are many more options you can choose from to address your requirements. For full details, see Azure OpenAI Hosting integration.

Set up client integration

To use Azure OpenAI from your client applications, install the Aspire Azure OpenAI client integration in your client project:

Install the NuGet package

dotnet add package Aspire.Azure.AI.OpenAI

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:

builder.AddAzureOpenAIClient(connectionName: "openai");

Tip

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

Use injected Azure OpenAI properties

In the AppHost, when you used the WithReference method to pass an Azure OpenAI resource to a consuming client project, Aspire injects several configuration properties that you can 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.

Use the GetValue() method to obtain these environment variables in consuming projects:

string openaiUri = builder.Configuration.GetValue<string>("OPENAI_URI");

Tip

The full set of properties that Aspire injects depends on whether you passed an Azure OpenAI service or deployment resource. For more information, see Properties of the Azure OpenAI resources.

Use Azure OpenAI client in client code

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

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

For full details on using the client integration, see Azure OpenAI Client integration.

Get started with the Azure OpenAI integration

Set up hosting integration

Set up client integration

Use injected Azure OpenAI properties

Use Azure OpenAI client in client code

Next steps