From 0a6d1a9aedbd6c170dacfb4c42f898b27f770163 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 7 Aug 2025 20:39:58 +0000 Subject: [PATCH 1/5] Initial plan From 35a968faab1317629817f842e08b2083db60d590 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 7 Aug 2025 20:46:28 +0000 Subject: [PATCH 2/5] Document Microsoft.Extensions.ApiDescription.Client deprecation breaking change Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/10.0.md | 6 ++ .../10.0/apidescription-client-deprecated.md | 66 +++++++++++++++++++ docs/core/compatibility/toc.yml | 4 ++ 3 files changed, 76 insertions(+) create mode 100644 docs/core/compatibility/aspnet-core/10.0/apidescription-client-deprecated.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 1b71ea787cc16..cb2e424e9c1d6 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -15,6 +15,12 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af > [!NOTE] > This article is a work in progress. It's not a complete list of breaking changes in .NET 10. +## ASP.NET Core + +| Title | Type of change | Introduced version | +|-------|---------------------|--------------------| +| [Microsoft.Extensions.ApiDescription.Client package deprecated](aspnet-core/10.0/apidescription-client-deprecated.md) | Source incompatible | Preview 7 | + ## Containers | Title | Type of change | Introduced version | diff --git a/docs/core/compatibility/aspnet-core/10.0/apidescription-client-deprecated.md b/docs/core/compatibility/aspnet-core/10.0/apidescription-client-deprecated.md new file mode 100644 index 0000000000000..98940a66600e2 --- /dev/null +++ b/docs/core/compatibility/aspnet-core/10.0/apidescription-client-deprecated.md @@ -0,0 +1,66 @@ +--- +title: "Breaking change - Microsoft.Extensions.ApiDescription.Client package deprecated" +description: "Learn about the breaking change in .NET 10 where the Microsoft.Extensions.ApiDescription.Client package has been deprecated." +ms.date: 08/07/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/aspnet/Announcements/issues/518 +--- + +# Microsoft.Extensions.ApiDescription.Client package deprecated + +The **Microsoft.Extensions.ApiDescription.Client** NuGet package has been deprecated starting in .NET 10. The package supplied MSBuild targets and CLI support that generated OpenAPI-based client code during the build. Projects that reference the package now receive a warning during build. + +## Version introduced + +.NET 10 Preview 7 + +## Previous behavior + +Projects could add `` and `` items (or run `dotnet openapi`) to generate strongly-typed clients at build time. + +```xml + + + net10.0 + + + + + + + + + + +``` + +## New behavior + +The package is deprecated and projects that reference it receive build warnings. The MSBuild targets and CLI commands are no longer supported. + +## Type of breaking change + +This change can affect [source compatibility](../../categories.md#source-compatibility). + +## Reason for change + +- The package has seen minimal updates and maintenance since its introduction. +- Its abstractions were tightly coupled to certain generators and did not scale well to others. +- Each generator now ships its own CLI/configuration experience, making the MSBuild middle-layer redundant. +- Removing the package reduces maintenance burden and clarifies the recommended workflow for client generation. + +## Recommended action + +1. **Remove** any `` from your project. +2. Replace `` items or `dotnet openapi` commands with generator-specific tooling: + - **NSwag** – use `npx nswag` or `dotnet tool run nswag` with an `.nswag` config file. + - **Kiota** – install with `dotnet tool install -g Microsoft.OpenApi.Kiota` and run `kiota generate`. + - **OpenAPI Generator** – invoke `openapi-generator-cli` via JAR or Docker. +3. Commit the generated client code or run generation in a custom pre-build step that does not rely on the removed package. + +## Affected APIs + +- NuGet package **Microsoft.Extensions.ApiDescription.Client** +- MSBuild item **`OpenApiReference`** (all instances) +- MSBuild property **`OpenApiProjectReference`** +- CLI command **`dotnet openapi`** \ No newline at end of file diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index bef069b8a508c..7adc88d978651 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -8,6 +8,10 @@ items: items: - name: Overview href: 10.0.md + - name: ASP.NET Core + items: + - name: Microsoft.Extensions.ApiDescription.Client package deprecated + href: aspnet-core/10.0/apidescription-client-deprecated.md - name: Containers items: - name: Default .NET images use Ubuntu From d11afe82f5e3e161b21e9f6a1aa71ef56415cc84 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 7 Aug 2025 14:44:45 -0700 Subject: [PATCH 3/5] human edits --- .../10.0/apidescription-client-deprecated.md | 34 +++++++++---------- 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/docs/core/compatibility/aspnet-core/10.0/apidescription-client-deprecated.md b/docs/core/compatibility/aspnet-core/10.0/apidescription-client-deprecated.md index 98940a66600e2..bd3f3802a6eeb 100644 --- a/docs/core/compatibility/aspnet-core/10.0/apidescription-client-deprecated.md +++ b/docs/core/compatibility/aspnet-core/10.0/apidescription-client-deprecated.md @@ -1,6 +1,6 @@ --- title: "Breaking change - Microsoft.Extensions.ApiDescription.Client package deprecated" -description: "Learn about the breaking change in .NET 10 where the Microsoft.Extensions.ApiDescription.Client package has been deprecated." +description: "Learn about the breaking change in ASP.NET Core 10 where the Microsoft.Extensions.ApiDescription.Client package has been deprecated." ms.date: 08/07/2025 ai-usage: ai-assisted ms.custom: https://github.com/aspnet/Announcements/issues/518 @@ -8,7 +8,7 @@ ms.custom: https://github.com/aspnet/Announcements/issues/518 # Microsoft.Extensions.ApiDescription.Client package deprecated -The **Microsoft.Extensions.ApiDescription.Client** NuGet package has been deprecated starting in .NET 10. The package supplied MSBuild targets and CLI support that generated OpenAPI-based client code during the build. Projects that reference the package now receive a warning during build. +The Microsoft.Extensions.ApiDescription.Client NuGet package has been deprecated. The package supplied MSBuild targets and CLI support that generated OpenAPI-based client code during the build. Projects that reference the package now receive a warning during build. ## Version introduced @@ -16,18 +16,18 @@ The **Microsoft.Extensions.ApiDescription.Client** NuGet package has been deprec ## Previous behavior -Projects could add `` and `` items (or run `dotnet openapi`) to generate strongly-typed clients at build time. +Projects could add `` and `` items (or run `dotnet openapi`) to generate strongly typed clients at build time. ```xml net10.0 - + - + @@ -36,7 +36,7 @@ Projects could add `` from your project. -2. Replace `` items or `dotnet openapi` commands with generator-specific tooling: - - **NSwag** – use `npx nswag` or `dotnet tool run nswag` with an `.nswag` config file. - - **Kiota** – install with `dotnet tool install -g Microsoft.OpenApi.Kiota` and run `kiota generate`. - - **OpenAPI Generator** – invoke `openapi-generator-cli` via JAR or Docker. -3. Commit the generated client code or run generation in a custom pre-build step that does not rely on the removed package. +- Remove any `` from your project. +- Replace `` items or `dotnet openapi` commands with generator-specific tooling: + - NSwag – Use `npx nswag` or `dotnet tool run nswag` with an `.nswag` config file. + - Kiota – Install with `dotnet tool install -g Microsoft.OpenApi.Kiota` and run `kiota generate`. + - OpenAPI generator – Invoke `openapi-generator-cli` via JAR or Docker. +- Commit the generated client code or run generation in a custom pre-build step that doesn't rely on the removed package. ## Affected APIs -- NuGet package **Microsoft.Extensions.ApiDescription.Client** -- MSBuild item **`OpenApiReference`** (all instances) -- MSBuild property **`OpenApiProjectReference`** -- CLI command **`dotnet openapi`** \ No newline at end of file +- MSBuild item `OpenApiReference` (all instances). +- MSBuild property `OpenApiProjectReference`. +- CLI command `dotnet openapi`. From fce538c0cbccaf70d5eaf2573b884b740b8098b0 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 7 Aug 2025 16:23:03 -0700 Subject: [PATCH 4/5] rename folder --- docs/core/compatibility/10.0.md | 2 +- .../{10.0 => 10}/apidescription-client-deprecated.md | 0 docs/core/compatibility/toc.yml | 2 +- 3 files changed, 2 insertions(+), 2 deletions(-) rename docs/core/compatibility/aspnet-core/{10.0 => 10}/apidescription-client-deprecated.md (100%) diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index cb2e424e9c1d6..0ab57db29f5c1 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -19,7 +19,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | Title | Type of change | Introduced version | |-------|---------------------|--------------------| -| [Microsoft.Extensions.ApiDescription.Client package deprecated](aspnet-core/10.0/apidescription-client-deprecated.md) | Source incompatible | Preview 7 | +| [Microsoft.Extensions.ApiDescription.Client package deprecated](aspnet-core/10/apidescription-client-deprecated.md) | Source incompatible | Preview 7 | ## Containers diff --git a/docs/core/compatibility/aspnet-core/10.0/apidescription-client-deprecated.md b/docs/core/compatibility/aspnet-core/10/apidescription-client-deprecated.md similarity index 100% rename from docs/core/compatibility/aspnet-core/10.0/apidescription-client-deprecated.md rename to docs/core/compatibility/aspnet-core/10/apidescription-client-deprecated.md diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 7adc88d978651..f0d0c3e5bd98e 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -11,7 +11,7 @@ items: - name: ASP.NET Core items: - name: Microsoft.Extensions.ApiDescription.Client package deprecated - href: aspnet-core/10.0/apidescription-client-deprecated.md + href: aspnet-core/10/apidescription-client-deprecated.md - name: Containers items: - name: Default .NET images use Ubuntu From 5abd7be67a95c8380bf6bafc9b231b006eeade0c Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 8 Aug 2025 11:17:05 -0700 Subject: [PATCH 5/5] Add link --- .../aspnet-core/10/apidescription-client-deprecated.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/compatibility/aspnet-core/10/apidescription-client-deprecated.md b/docs/core/compatibility/aspnet-core/10/apidescription-client-deprecated.md index bd3f3802a6eeb..d75856a43db9d 100644 --- a/docs/core/compatibility/aspnet-core/10/apidescription-client-deprecated.md +++ b/docs/core/compatibility/aspnet-core/10/apidescription-client-deprecated.md @@ -61,4 +61,4 @@ This change can affect [source compatibility](../../categories.md#source-compati - MSBuild item `OpenApiReference` (all instances). - MSBuild property `OpenApiProjectReference`. -- CLI command `dotnet openapi`. +- CLI command [`dotnet openapi`](/aspnet/core/fundamentals/openapi/openapi-tools).