Fixes #3059. Removes obsolete API. (#3116)

IEvangelist · web-flow · commit 21dfbdf5b08c · 2025-04-16T10:42:11.000-05:00
diff --git a/docs/azureai/azureai-openai-integration.md b/docs/azureai/azureai-openai-integration.md
@@ -1,7 +1,7 @@
 ---
 title: .NET Aspire Azure OpenAI integration (Preview)
 description: Learn how to use the .NET Aspire Azure OpenAI integration.
-ms.date: 04/03/2025
+ms.date: 04/15/2025
 ---
 
 # .NET Aspire Azure OpenAI integration (Preview)
@@ -53,17 +53,17 @@ The preceding code adds an Azure OpenAI resource named `openai` to the app host
 
 ### Add an Azure OpenAI deployment resource
 
-To add an Azure OpenAI deployment resource, call the <xref:Aspire.Hosting.AzureOpenAIExtensions.AddDeployment(Aspire.Hosting.ApplicationModel.IResourceBuilder{Aspire.Hosting.ApplicationModel.AzureOpenAIResource},Aspire.Hosting.ApplicationModel.AzureOpenAIDeployment)> method:
+To add an Azure OpenAI deployment resource, call the <xref:Aspire.Hosting.AzureOpenAIExtensions.AddDeployment(Aspire.Hosting.ApplicationModel.IResourceBuilder{Aspire.Hosting.ApplicationModel.AzureOpenAIResource},System.String,System.String,System.String)> method:
 
 ```csharp
 var builder = DistributedApplication.CreateBuilder(args);
 
 var openai = builder.AddAzureOpenAI("openai");
+
 openai.AddDeployment(
-    new AzureOpenAIDeployment(
-        name: "preview",
-        modelName: "gpt-4.5-preview",
-        modelVersion: "2025-02-27"));
+    name: "preview",
+    modelName: "gpt-4.5-preview",
+    modelVersion: "2025-02-27");
 
 builder.AddProject<Projects.ExampleProject>()
        .WithReference(openai)
@@ -77,7 +77,7 @@ 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](/azure/ai-services/openai/concepts/models) in the Azure OpenAI service.
 
-### Generated provisioning Bicep
+### Provisioning-generated Bicep
 
 If you're new to [Bicep](/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With .NET 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.
 
diff --git a/docs/azureai/azureai-search-document-integration.md b/docs/azureai/azureai-search-document-integration.md
@@ -51,7 +51,7 @@ The preceding code adds an Azure AI Search resource named `search` to the app ho
 > [!IMPORTANT]
 > When you call <xref:Aspire.Hosting.AzureSearchExtensions.AddAzureSearch*>, it implicitly calls <xref:Aspire.Hosting.AzureProvisionerExtensions.AddAzureProvisioning(Aspire.Hosting.IDistributedApplicationBuilder)>—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
 
-#### Generated provisioning Bicep
+#### Provisioning-generated Bicep
 
 If you're new to [Bicep](/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With .NET 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 is output alongside the manifest file. When you add an Azure AI Search resource, Bicep is generated to provision the search service with appropriate defaults.
 
diff --git a/docs/caching/includes/azure-redis-app-host.md b/docs/caching/includes/azure-redis-app-host.md
@@ -44,7 +44,7 @@ The preceding call to `AddAzureRedis` configures the Redis server resource to be
 > [!TIP]
 > When you call <xref:Aspire.Hosting.AzureRedisExtensions.AddAzureRedis*>, it implicitly calls <xref:Aspire.Hosting.AzureProvisionerExtensions.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](../../azure/local-provisioning.md#configuration).
 
-#### Generated provisioning Bicep
+#### Provisioning-generated Bicep
 
 If you're new to [Bicep](/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With .NET 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 is output alongside the manifest file. When you add an Azure Cache for Redis resource, the following Bicep is generated:
 
diff --git a/docs/compatibility/9.2/azure-openaideployment-obsolete.md b/docs/compatibility/9.2/azure-openaideployment-obsolete.md
@@ -0,0 +1,69 @@
+---
+title: "Breaking change - AzureOpenAIDeployment obsolete"
+description: "Learn about the breaking change in .NET Aspire 9.2 where Azure OpenAI deployments are now modeled as .NET Aspire child resources."
+ms.date: 4/15/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs-aspire/issues/3059
+---
+
+# AzureOpenAIDeployment obsolete
+
+In .NET Aspire 9.2, Azure OpenAI deployments are modeled as .NET Aspire child resources instead of simple objects. This change aligns with the design of other [hosting integrations](../../fundamentals/integrations-overview.md#hosting-integrations) and enables referencing deployments using <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference*>. As a result, the previous APIs for adding deployments are now obsolete.
+
+## Version introduced
+
+.NET Aspire 9.2
+
+## Previous behavior
+
+Previously, deployments were added as simple objects using the <xref:Aspire.Hosting.ApplicationModel.AzureOpenAIDeployment> class. For example:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var openAI = builder.AddAzureOpenAI(openAIName);
+
+openAI.AddDeployment(new AzureOpenAIDeployment("chat", "gpt-4o-mini", "2024-07-18"))
+      .AddDeployment(new AzureOpenAIDeployment("embedding", "text-embedding-3-small", "1"));
+```
+
+## New behavior
+
+Deployments are modeled as .NET Aspire child resources and are added using the new overloads. For example, consider the following code:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var openAI = builder.AddAzureOpenAI(openAIName);
+
+var chatModel = openAI.AddDeployment("chat", "gpt-4o-mini", "2024-07-18");
+var embeddingModel = openAI.AddDeployment("embedding", "text-embedding-3-small", "1");
+```
+
+## Type of breaking change
+
+This is a [source incompatible](../categories.md#source-compatibility) change.
+
+## Reason for change
+
+Modeling deployments as Aspire resources allows them to be referenced by other resources via `.WithReference`. This design eliminates the need to hard-code model names in .NET applications and enables configuration-based deployment name resolution. It also ensures consistency with other hosting integrations.
+
+## Recommended action
+
+Update your code to use the new overloads for adding deployments. Replace calls to the obsolete APIs with the new pattern. For example:
+
+**Before:**
+
+```csharp
+openAI.AddDeployment(new AzureOpenAIDeployment("chat", "gpt-4o-mini", "2024-07-18"));
+```
+
+**After:**
+
+```csharp
+var chatModel = openAI.AddDeployment("chat", "gpt-4o-mini", "2024-07-18");
+```
+
+## Affected APIs
+
+- <xref:Aspire.Hosting.AzureOpenAIExtensions.AddDeployment*>
diff --git a/docs/compatibility/9.2/index.md b/docs/compatibility/9.2/index.md
@@ -2,7 +2,7 @@
 title: Breaking changes in .NET Aspire 9.2
 titleSuffix: ""
 description: Navigate to the breaking changes in .NET Aspire 9.2.
-ms.date: 04/02/2025
+ms.date: 04/15/2025
 ---
 
 # Breaking changes in .NET Aspire 9.2
@@ -19,6 +19,7 @@ If you're migrating an app to .NET Aspire 9.2, the breaking changes listed here
 | Title | Type of change | Introduced version |
 |--|--|--|
 | [AzureContainerApps infrastructure creates managed identity per container app](managed-identity-per-app.md) | Behavioral change | 9.2 |
+| [AzureOpenAIDeployment obsolete](azure-openaideployment-obsolete.md) | Source incompatible | 9.2 |
 | [KeyVault default role assignment changing from KeyVaultAdministrator to KeyVaultSecretsUser](keyvault-role-assignment-changes.md) | Behavioral change | 9.2 |
 | [Role Assignments separated from Azure resource bicep](generated-bicep-updates.md) | Behavioral change | 9.2 |
 | [With authentication API creates keyvault resource in the app model](withauthentication-changes.md) | Behavioral change | 9.2 |
diff --git a/docs/compatibility/toc.yml b/docs/compatibility/toc.yml
@@ -15,6 +15,8 @@ items:
     items:
     - name: Azure Container Apps managed identity changes
       href: 9.2/managed-identity-per-app.md
+    - name: Azure OpenAI deployment obsolete APIs
+      href: 9.2/azure-openaideployment-obsolete.md
     - name: KeyVault default role assignment changes
       href: 9.2/keyvault-role-assignment-changes.md
     - name: Role Assignments is separate bicep
diff --git a/docs/database/includes/cosmos-app-host.md b/docs/database/includes/cosmos-app-host.md
@@ -45,7 +45,7 @@ When you add an <xref:Aspire.Hosting.AzureCosmosDBResource> to the app host, it
 > [!IMPORTANT]
 > When you call <xref:Aspire.Hosting.AzureCosmosExtensions.AddAzureCosmosDB*>, it implicitly calls <xref:Aspire.Hosting.AzureProvisionerExtensions.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](../../azure/local-provisioning.md#configuration).
 
-#### Generated provisioning Bicep
+#### Provisioning-generated Bicep
 
 If you're new to [Bicep](/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With .NET 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 is output alongside the manifest file. When you add an Azure Cosmos DB resource, the following Bicep is generated:
 
diff --git a/docs/database/includes/postgresql-flexible-server.md b/docs/database/includes/postgresql-flexible-server.md
@@ -56,7 +56,7 @@ The preceding call to `AddAzurePostgresFlexibleServer` configures the PostgresSQ
 > [!TIP]
 > When you call <xref:Aspire.Hosting.AzurePostgresExtensions.AddAzurePostgresFlexibleServer*>, it implicitly calls <xref:Aspire.Hosting.AzureProvisionerExtensions.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](../../azure/local-provisioning.md#configuration).
 
-#### Generated provisioning Bicep
+#### Provisioning-generated Bicep
 
 If you're new to [Bicep](/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With .NET Aspire, you don't need to write Bicep by hand, because the provisioning APIs generate Bicep for you. When you publish your app, the generated Bicep is output alongside the manifest file. When you add an Azure PostgreSQL resource, the following Bicep is generated:
 
diff --git a/docs/messaging/azure-event-hubs-integration.md b/docs/messaging/azure-event-hubs-integration.md
@@ -59,7 +59,7 @@ When you add an Azure Event Hubs resource to the app host, it exposes other usef
 > [!IMPORTANT]
 > When you call <xref:Aspire.Hosting.AzureEventHubsExtensions.AddAzureEventHubs*>, it implicitly calls <xref:Aspire.Hosting.AzureProvisionerExtensions.AddAzureProvisioning(Aspire.Hosting.IDistributedApplicationBuilder)>—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](../azure/local-provisioning.md#configuration)
 
-#### Generated provisioning Bicep
+#### Provisioning-generated Bicep
 
 If you're new to [Bicep](/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With .NET 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 is output alongside the manifest file. When you add an Azure Event Hubs resource, the following Bicep is generated:
 
diff --git a/docs/messaging/azure-service-bus-integration.md b/docs/messaging/azure-service-bus-integration.md
@@ -56,7 +56,7 @@ When you add an <xref:Aspire.Hosting.Azure.AzureServiceBusResource> to the app h
 > [!IMPORTANT]
 > When you call <xref:Aspire.Hosting.AzureServiceBusExtensions.AddAzureServiceBus*>, it implicitly calls <xref:Aspire.Hosting.AzureProvisionerExtensions.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 [Configuration](../azure/local-provisioning.md#configuration).
 
-#### Generated provisioning Bicep
+#### Provisioning-generated Bicep
 
 If you're new to Bicep, it's a domain-specific language for defining Azure resources. With .NET 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 is output alongside the manifest file. When you add an Azure Service Bus resource, the following Bicep is generated:
 
diff --git a/docs/messaging/azure-web-pubsub-integration.md b/docs/messaging/azure-web-pubsub-integration.md
@@ -93,7 +93,7 @@ messagesHub.AddEventHandler(
 
 The preceding code adds a worker service project named `worker` with an external HTTP endpoint. The hub named `messages` resource is added to the `web-pubsub` resource, and an event handler is added to the `messagesHub` resource. The event handler URL is set to the worker service's external HTTP endpoint. For more information, see [Azure Web PubSub event handlers](/azure/azure-web-pubsub/howto-develop-eventhandler).
 
-#### Generated provisioning Bicep
+#### Provisioning-generated Bicep
 
 When you publish your app, .NET Aspire provisioning APIs generate Bicep alongside the manifest file. Bicep is a domain-specific language for defining Azure resources. For more information, see [Bicep Overview](/azure/azure-resource-manager/bicep/overview).
 
diff --git a/docs/real-time/azure-signalr-scenario.md b/docs/real-time/azure-signalr-scenario.md
@@ -69,7 +69,7 @@ This architecture allows the `webapp` project to communicate with the `api` proj
 > [!IMPORTANT]
 > Calling `AddAzureSignalR` implicitly enables Azure provisioning support. Ensure your app host is configured with the appropriate Azure subscription and location. For more information, see [Local provisioning: Configuration](../azure/local-provisioning.md#configuration).
 
-### Generated provisioning Bicep
+### Provisioning-generated Bicep
 
 When you add an Azure SignalR Service resource, .NET Aspire generates provisioning infrastructure using [Bicep](/azure/azure-resource-manager/bicep/overview). The generated Bicep includes defaults for location, SKU, and role assignments:
 
diff --git a/docs/security/azure-security-key-vault-integration.md b/docs/security/azure-security-key-vault-integration.md
@@ -55,7 +55,7 @@ The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A> method conf
 > [!TIP]
 > When you call <xref:Aspire.Hosting.AzureKeyVaultResourceExtensions.AddAzureKeyVault*>, it implicitly calls <xref:Aspire.Hosting.AzureProvisionerExtensions.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](../azure/local-provisioning.md#configuration).
 
-#### Generated provisioning Bicep
+#### Provisioning-generated Bicep
 
 If you're new to [Bicep](/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With .NET 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 is output alongside the manifest file. When you add an Azure Key Vault resource, the following Bicep is generated:
 
