Thay đổi có thể gây lỗi: Package Microsoft.Extensions.ApiDescription.Client bị deprecated (không còn được hỗ trợ)

Nguồn: Microsoft.Extensions.ApiDescription.Client package deprecated

NuGet package (gói) Microsoft.Extensions.ApiDescription.Client đã bị deprecated. Package này cung cấp các MSBuild target và hỗ trợ CLI để tạo ra code client dựa trên OpenAPI trong quá trình build. Các dự án tham chiếu package này hiện nhận được cảnh báo trong quá trình build.

Phiên bản được giới thiệu

.NET 10 Preview 7

Hành vi trước đây

Các dự án có thể thêm <PackageReference Include="Microsoft.Extensions.ApiDescription.Client" ... /> và các mục <OpenApiReference> (hoặc chạy dotnet openapi) để tạo ra các client có kiểu mạnh (strongly typed) tại thời điểm build.

xml

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Client" Version="8.0.0" />
  </ItemGroup>

  <ItemGroup>
    <OpenApiReference Include="swagger.json" />
  </ItemGroup>
</Project>

Hành vi mới

Package hiện bị deprecated và các dự án tham chiếu nó sẽ nhận được cảnh báo build. Các MSBuild target và lệnh CLI không còn được hỗ trợ nữa.

Loại thay đổi có thể gây lỗi

Thay đổi này có thể ảnh hưởng đến source compatibility (tương thích mã nguồn).

Lý do thay đổi

Package này hầu như không được cập nhật hay bảo trì kể từ khi ra đời.
Các abstraction (trừu tượng hóa) của nó bị ràng buộc chặt chẽ với một số generator nhất định và không mở rộng tốt với các generator khác. Mỗi generator hiện gửi kèm CLI/cấu hình riêng của mình, khiến lớp MSBuild trung gian trở nên dư thừa.
Xóa package này giảm gánh nặng bảo trì và làm rõ quy trình được khuyến nghị cho việc tạo client.

Hành động được khuyến nghị

Xóa bất kỳ <PackageReference Include="Microsoft.Extensions.ApiDescription.Client" … /> nào khỏi dự án của bạn.
Thay thế các mục <OpenApiReference> hoặc lệnh dotnet openapi bằng công cụ riêng của từng generator:
NSwag – Sử dụng npx nswag hoặc dotnet tool run nswag với file cấu hình .nswag.
Kiota – Cài đặt bằng dotnet tool install -g Microsoft.OpenApi.Kiota và chạy kiota generate.
OpenAPI generator – Gọi openapi-generator-cli qua JAR hoặc Docker.
Commit code client đã tạo ra hoặc chạy việc tạo trong bước pre-build tùy chỉnh không phụ thuộc vào package đã xóa.

Các API bị ảnh hưởng

MSBuild item OpenApiReference (tất cả các trường hợp).
MSBuild property OpenApiProjectReference.
Lệnh CLI dotnet openapi.