[Breaking change]: Deprecation of Microsoft.Extensions.ApiDescription.Client package

[captainsafia]

Description

The Microsoft.Extensions.ApiDescription.Client NuGet package has been deprecated starting in .NET 10 Preview 7. The package supplied MSBuild targets and CLI support (e.g., dotnet openapi, the OpenApiReference item group, and OpenApiProjectReference property) that generated OpenAPI-based client code during the build. Projects that reference the package will now receive a warning during build.

Version

.NET 10 Preview 7

Previous behavior

Projects could add <PackageReference Include="Microsoft.Extensions.ApiDescription.Client" … /> and <OpenApiReference> (or run dotnet openapi) to generate strongly-typed clients at build time.

New behavior

1. Remove any <PackageReference Include="Microsoft.Extensions.ApiDescription.Client" … /> from your project.
   2. Replace <OpenApiReference> 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.
   validations:
   required: true

• type: textarea

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code may require source changes to compile successfully.
• Behavioral change: Existing binaries may behave differently at run time.

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 <PackageReference Include="Microsoft.Extensions.ApiDescription.Client" … /> from your project.
2. Replace <OpenApiReference> 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.

Affected APIs

• NuGet package Microsoft.Extensions.ApiDescription.Client
• MSBuild item OpenApiReference (all instances)
• MSBuild property OpenApiProjectReference
• CLI command dotnet openapi