From b5e465652f8cba4667b6ceaa60c678f3e6974b29 Mon Sep 17 00:00:00 2001 From: David Pine Date: Mon, 12 May 2025 09:26:01 -0500 Subject: [PATCH 1/6] Fixes #3373, removal of publisher APIs. --- docs/compatibility/9.3/index.md | 3 +- .../9.3/remove-publisher-apis.md | 90 +++++++++++++++++++ docs/compatibility/toc.yml | 2 + 3 files changed, 94 insertions(+), 1 deletion(-) create mode 100644 docs/compatibility/9.3/remove-publisher-apis.md diff --git a/docs/compatibility/9.3/index.md b/docs/compatibility/9.3/index.md index cf0a532db3..00b5d4ce25 100644 --- a/docs/compatibility/9.3/index.md +++ b/docs/compatibility/9.3/index.md @@ -2,7 +2,7 @@ title: Breaking changes in .NET Aspire 9.3 titleSuffix: "" description: Navigate to the breaking changes in .NET Aspire 9.3. -ms.date: 05/07/2025 +ms.date: 05/12/2025 --- # Breaking changes in .NET Aspire 9.3 @@ -20,3 +20,4 @@ If you're migrating an app to .NET Aspire 9.3, the breaking changes listed here |--|--|--| | [With health checks changes in .NET Aspire 9.3](with-health-checks-changes.md) | Binary and source incompatible | 9.3 | | [Change the default SKU used for creating a new Azure SQL database](azure-sql-server-default-sku-changes.md) | Behavioral change | 9.3 | +| [Remove publisher APIs](remove-publisher-apis.md) | Binary incompatible, source incompatible, and behavioral change | 9.3 | diff --git a/docs/compatibility/9.3/remove-publisher-apis.md b/docs/compatibility/9.3/remove-publisher-apis.md new file mode 100644 index 0000000000..6b8cc41c7d --- /dev/null +++ b/docs/compatibility/9.3/remove-publisher-apis.md @@ -0,0 +1,90 @@ +--- +title: "Breaking change - Removal of DockerComposePublisher, KubernetesPublisher and AzurePublisher" +description: "Learn about the breaking change in .NET Aspire 9.3 where publisher APIs were removed in favor of new resource types." +ms.date: 5/12/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs-aspire/issues/3373 +--- + +# Removal of DockerComposePublisher, KubernetesPublisher and AzurePublisher + +In .NET Aspire 9.3, the `AddDockerComposePublisher`, `AddKubernetesPublisher`, and `AddAzurePublisher` APIs were removed. These APIs have been replaced with new resource types that provide a more streamlined and flexible publishing experience. + +## Version introduced + +.NET Aspire 9.3 + +## Previous behavior + +In .NET Aspire 9.2, the publisher API was introduced in preview, allowing the use of the following publishers: + +- DockerCompose +- Kubernetes +- Azure + +These publishers were added using the following methods: + +- +- +- + +Multiple publishers could be added, and the `aspire publish` CLI command allowed users to select one for publishing. + +## New behavior + +In .NET Aspire 9.3, the publishers have been replaced with new resource types: + + + +- `DockerEnvironmentResource` +- `KubernetesEnvironmentResource` +- `AzureEnvironmentResource` + +These resources include a `PublisherCallbackAnnotation` that defines their publishing behavior. The default publisher now automatically processes all resources with this annotation to generate assets. The `aspire publish` command no longer requires selecting a publisher; it uses the default publisher to handle all annotated resources. + +Example: + +```csharp +builder.AddDockerComposeEnvironment(publisher => +{ + // Configure the Docker environment publisher +}); +builder.AddKubernetesEnvironment(publisher => +{ + // Configure the Kubernetes environment publisher +}); +builder.AddAzureEnvironment(publisher => +{ + // Configure the Azure environment publisher +}); +``` + +## Type of breaking change + +This is a [binary incompatible](../categories.md#binary-compatibility), [source incompatible](../categories.md#source-compatibility), and [behavioral change](../categories.md#behavioral-change). + +## Reason for change + +The change simplifies the publishing process by consolidating functionality into resource types with a unified publishing mechanism. For more details, see the [GitHub issue](https://github.com/dotnet/aspire/issues/9089). + +## Recommended action + +Update your code to use the new resource APIs: + +- Replace `AddDockerComposePublisher` with `AddDockerComposeEnvironment(...)`. +- Replace `AddKubernetesPublisher` with `AddKubernetesEnvironment(...)`. +- Replace `AddAzurePublisher` with `AddAzureEnvironment(...)` (this is implicit with any Azure resource). + +Example: + +```csharp +builder.AddDockerComposeEnvironment(...); +builder.AddKubernetesEnvironment(...); +builder.AddAzureEnvironment(...); +``` + +## Affected APIs + +- `IDistributedApplicationBuilder.AddDockerComposePublisher` +- `IDistributedApplicationBuilder.AddKubernetesPublisher` +- `IDistributedApplicationBuilder.AddAzurePublisher` diff --git a/docs/compatibility/toc.yml b/docs/compatibility/toc.yml index 27a565ff0f..7ad897d357 100644 --- a/docs/compatibility/toc.yml +++ b/docs/compatibility/toc.yml @@ -17,6 +17,8 @@ items: href: 9.3/with-health-checks-changes.md - name: Azure SQL Server default SKU changes href: 9.3/azure-sql-server-default-sku-changes.md + - name: Removal of publisher APIs + href: 9.3/remove-publisher-apis.md - name: .NET Aspire 9.2 expanded: false items: From 8ca9ac8b989a4e1359f2b14ed16de2acec2a895d Mon Sep 17 00:00:00 2001 From: David Pine Date: Mon, 12 May 2025 09:26:23 -0500 Subject: [PATCH 2/6] Minor tweaks --- docs/compatibility/9.3/remove-publisher-apis.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/compatibility/9.3/remove-publisher-apis.md b/docs/compatibility/9.3/remove-publisher-apis.md index 6b8cc41c7d..2b6fa36fb7 100644 --- a/docs/compatibility/9.3/remove-publisher-apis.md +++ b/docs/compatibility/9.3/remove-publisher-apis.md @@ -49,10 +49,12 @@ builder.AddDockerComposeEnvironment(publisher => { // Configure the Docker environment publisher }); + builder.AddKubernetesEnvironment(publisher => { // Configure the Kubernetes environment publisher }); + builder.AddAzureEnvironment(publisher => { // Configure the Azure environment publisher From 518d0cb484513c4a2004186b322b4428e34ec0a0 Mon Sep 17 00:00:00 2001 From: David Pine Date: Mon, 12 May 2025 09:28:55 -0500 Subject: [PATCH 3/6] Edit pass --- docs/compatibility/9.3/remove-publisher-apis.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/compatibility/9.3/remove-publisher-apis.md b/docs/compatibility/9.3/remove-publisher-apis.md index 2b6fa36fb7..39b44e03f4 100644 --- a/docs/compatibility/9.3/remove-publisher-apis.md +++ b/docs/compatibility/9.3/remove-publisher-apis.md @@ -1,14 +1,14 @@ --- -title: "Breaking change - Removal of DockerComposePublisher, KubernetesPublisher and AzurePublisher" +title: "Breaking change - Removal of DockerComposePublisher, KubernetesPublisher, and AzurePublisher" description: "Learn about the breaking change in .NET Aspire 9.3 where publisher APIs were removed in favor of new resource types." ms.date: 5/12/2025 ai-usage: ai-assisted ms.custom: https://github.com/dotnet/docs-aspire/issues/3373 --- -# Removal of DockerComposePublisher, KubernetesPublisher and AzurePublisher +# Removal of DockerComposePublisher, KubernetesPublisher, and AzurePublisher -In .NET Aspire 9.3, the `AddDockerComposePublisher`, `AddKubernetesPublisher`, and `AddAzurePublisher` APIs were removed. These APIs have been replaced with new resource types that provide a more streamlined and flexible publishing experience. +In .NET Aspire 9.3, the `AddDockerComposePublisher`, `AddKubernetesPublisher`, and `AddAzurePublisher` APIs were removed. These APIs are now replaced with new resource types that provide a more streamlined and flexible publishing experience. ## Version introduced @@ -32,7 +32,7 @@ Multiple publishers could be added, and the `aspire publish` CLI command allowed ## New behavior -In .NET Aspire 9.3, the publishers have been replaced with new resource types: +In .NET Aspire 9.3, the publishers are now replaced with new resource types: @@ -67,7 +67,7 @@ This is a [binary incompatible](../categories.md#binary-compatibility), [source ## Reason for change -The change simplifies the publishing process by consolidating functionality into resource types with a unified publishing mechanism. For more details, see the [GitHub issue](https://github.com/dotnet/aspire/issues/9089). +The change simplifies the publishing process by consolidating functionality into resource types with a unified publishing mechanism. For more information, see the [GitHub issue](https://github.com/dotnet/aspire/issues/9089). ## Recommended action @@ -75,7 +75,7 @@ Update your code to use the new resource APIs: - Replace `AddDockerComposePublisher` with `AddDockerComposeEnvironment(...)`. - Replace `AddKubernetesPublisher` with `AddKubernetesEnvironment(...)`. -- Replace `AddAzurePublisher` with `AddAzureEnvironment(...)` (this is implicit with any Azure resource). +- Replace `AddAzurePublisher` with `AddAzureEnvironment(...)` (implicit with any Azure resource). Example: From b1e356102d292630af94ef312cc5eba8bbca78f0 Mon Sep 17 00:00:00 2001 From: David Pine Date: Mon, 12 May 2025 09:35:03 -0500 Subject: [PATCH 4/6] Sort table --- docs/compatibility/9.3/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/compatibility/9.3/index.md b/docs/compatibility/9.3/index.md index 00b5d4ce25..524dc49408 100644 --- a/docs/compatibility/9.3/index.md +++ b/docs/compatibility/9.3/index.md @@ -18,6 +18,6 @@ If you're migrating an app to .NET Aspire 9.3, the breaking changes listed here | Title | Type of change | Introduced version | |--|--|--| -| [With health checks changes in .NET Aspire 9.3](with-health-checks-changes.md) | Binary and source incompatible | 9.3 | | [Change the default SKU used for creating a new Azure SQL database](azure-sql-server-default-sku-changes.md) | Behavioral change | 9.3 | | [Remove publisher APIs](remove-publisher-apis.md) | Binary incompatible, source incompatible, and behavioral change | 9.3 | +| [With health checks changes in .NET Aspire 9.3](with-health-checks-changes.md) | Binary and source incompatible | 9.3 | From 974d62f351de601b40ac528812fb036a0e67d5f9 Mon Sep 17 00:00:00 2001 From: David Pine Date: Mon, 12 May 2025 09:45:43 -0500 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: David Fowler --- docs/compatibility/9.3/remove-publisher-apis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/compatibility/9.3/remove-publisher-apis.md b/docs/compatibility/9.3/remove-publisher-apis.md index 39b44e03f4..387a99695b 100644 --- a/docs/compatibility/9.3/remove-publisher-apis.md +++ b/docs/compatibility/9.3/remove-publisher-apis.md @@ -8,7 +8,7 @@ ms.custom: https://github.com/dotnet/docs-aspire/issues/3373 # Removal of DockerComposePublisher, KubernetesPublisher, and AzurePublisher -In .NET Aspire 9.3, the `AddDockerComposePublisher`, `AddKubernetesPublisher`, and `AddAzurePublisher` APIs were removed. These APIs are now replaced with new resource types that provide a more streamlined and flexible publishing experience. +In .NET Aspire 9.3, the `AddDockerComposePublisher`, `AddKubernetesPublisher`, and `AddAzurePublisher` APIs were removed. These APIs are now replaced with new resource types that provide a more composable experience. ## Version introduced From 442b97093da6297e704d05a65439703cb4bb8fab Mon Sep 17 00:00:00 2001 From: David Pine Date: Mon, 12 May 2025 09:57:47 -0500 Subject: [PATCH 6/6] Address feedback --- .../9.3/remove-publisher-apis.md | 41 ++++++++----------- 1 file changed, 16 insertions(+), 25 deletions(-) diff --git a/docs/compatibility/9.3/remove-publisher-apis.md b/docs/compatibility/9.3/remove-publisher-apis.md index 387a99695b..8fc346ba53 100644 --- a/docs/compatibility/9.3/remove-publisher-apis.md +++ b/docs/compatibility/9.3/remove-publisher-apis.md @@ -36,29 +36,20 @@ In .NET Aspire 9.3, the publishers are now replaced with new resource types: -- `DockerEnvironmentResource` +- `DockerComposeEnvironmentResource` - `KubernetesEnvironmentResource` -- `AzureEnvironmentResource` +- `AzureEnvironmentResource` (Automatically added when you use any Azure resource) These resources include a `PublisherCallbackAnnotation` that defines their publishing behavior. The default publisher now automatically processes all resources with this annotation to generate assets. The `aspire publish` command no longer requires selecting a publisher; it uses the default publisher to handle all annotated resources. Example: ```csharp -builder.AddDockerComposeEnvironment(publisher => -{ - // Configure the Docker environment publisher -}); - -builder.AddKubernetesEnvironment(publisher => -{ - // Configure the Kubernetes environment publisher -}); - -builder.AddAzureEnvironment(publisher => -{ - // Configure the Azure environment publisher -}); +builder.AddDockerComposeEnvironment("docker-compose"); + +builder.AddKubernetesEnvironment("kubernetes"); + +builder.AddAzureEnvironment("azure"); ``` ## Type of breaking change @@ -73,20 +64,20 @@ The change simplifies the publishing process by consolidating functionality into Update your code to use the new resource APIs: -- Replace `AddDockerComposePublisher` with `AddDockerComposeEnvironment(...)`. -- Replace `AddKubernetesPublisher` with `AddKubernetesEnvironment(...)`. -- Replace `AddAzurePublisher` with `AddAzureEnvironment(...)` (implicit with any Azure resource). +- Replace `AddDockerComposePublisher` with `AddDockerComposeEnvironment("...")`. +- Replace `AddKubernetesPublisher` with `AddKubernetesEnvironment("...")`. +- Replace `AddAzurePublisher` with `AddAzureEnvironment("...")`. Example: ```csharp -builder.AddDockerComposeEnvironment(...); -builder.AddKubernetesEnvironment(...); -builder.AddAzureEnvironment(...); +var dockerCompose = builder.AddDockerComposeEnvironment("docker-compose"); +var kubernetes = builder.AddKubernetesEnvironment("kubernetes"); +var azure = builder.AddAzureEnvironment("azure"); ``` ## Affected APIs -- `IDistributedApplicationBuilder.AddDockerComposePublisher` -- `IDistributedApplicationBuilder.AddKubernetesPublisher` -- `IDistributedApplicationBuilder.AddAzurePublisher` +- +- +-