Nguon: Microsoft Learn · .NET 8.0

Thuộc tính IncludeOpenAPIAnalyzers và MVC API analyzers đã bị deprecated (không còn được hỗ trợ)

Nguồn: IncludeOpenAPIAnalyzers property and MVC API analyzers are deprecated

Thuộc tính MSBuild IncludeOpenAPIAnalyzers và các MVC API analyzers (bộ phân tích) liên quan đã bị deprecated (không còn được hỗ trợ) và sẽ bị xóa trong phiên bản tương lai. Khi IncludeOpenAPIAnalyzers được đặt thành true, quá trình build (xây dựng) sẽ phát ra cảnh báo ASPDEPR007.

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

.NET 10 Preview 7

Hành vi trước đây

Trước đây, bạn có thể đặt <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> trong các dự án Web SDK để bật MVC API analyzers mà không có bất kỳ cảnh báo hay thông báo deprecated nào.

xml
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
  </PropertyGroup>
</Project>

Dự án như vậy build thành công mà không có cảnh báo deprecated.

Hành vi mới

Bắt đầu từ .NET 10, khi IncludeOpenAPIAnalyzers được đặt thành true, quá trình build sẽ phát ra cảnh báo ASPDEPR007:

warning ASPDEPR007: The IncludeOpenAPIAnalyzers property and its associated MVC API analyzers are deprecated and will be removed in a future release.

Các analyzer vẫn tiếp tục hoạt động, nhưng các nhà phát triển sẽ nhận được cảnh báo deprecated này trong quá trình biên dịch.

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

Các MVC API analyzers ban đầu được giới thiệu để giúp đồng bộ các kiểu trả về và thuộc tính cho API controllers, đảm bảo tính nhất quán giữa method signatures (chữ ký phương thức) và tài liệu OpenAPI tương ứng. Các analyzer này cung cấp validation (kiểm tra) tại compile time để phát hiện sự không khớp giữa các kiểu trả về đã khai báo và các kiểu thực tế được trả về bởi các controller action.

Tuy nhiên, với sự ra đời của Minimal APIs và mẫu TypedResults, hệ sinh thái .NET đã phát triển theo hướng tiếp cận an toàn kiểu hơn cho phát triển API. TypedResults cung cấp các đảm bảo tại compile time về kiểu response mà không cần thêm analyzer, khiến các MVC API analyzers trở nên dư thừa đối với các ứng dụng .NET hiện đại. Trong .NET 10, TypedResults được hỗ trợ trong các API dựa trên controller.

Cách tiếp cận trước đây với MVC API analyzers:

csharp
[HttpGet]
[ProducesResponseType<Product>(200)]
[ProducesResponseType(404)]
public async Task<ActionResult> GetProduct(int id)
{
    var product = await _productService.GetByIdAsync(id);
    if (product == null)
        return NotFound(); // Analyzer đảm bảo khớp với ProducesResponseType(404)

    return Ok(product); // Analyzer đảm bảo khớp với ProducesResponseType<Product>(200)
}

Cách tiếp cận hiện đại với TypedResults:

csharp
[HttpGet("{id}")]
public async Task<Results<Ok<Product>, NotFound>> GetProduct(int id)
{
    var product = await _productService.GetByIdAsync(id);
    return product == null
        ? TypedResults.NotFound()
        : TypedResults.Ok(product);
}

Mẫu TypedResults loại bỏ nhu cầu về các analyzer riêng biệt vì kiểu trả về (Results<Ok<Product>, NotFound>) tự nó khai báo tường minh tất cả các kiểu response có thể tại compile time. Cách tiếp cận này dễ bảo trì hơn, cung cấp hỗ trợ IntelliSense tốt hơn, và tự động tạo tài liệu OpenAPI chính xác mà không cần công cụ bổ sung.

Khi hệ sinh thái .NET tiếp tục áp dụng TypedResults như là mẫu được khuyến nghị cho phát triển API, các MVC API analyzers đã trở nên lỗi thời và đang bị deprecated để tinh giản trải nghiệm phát triển.

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

Các nhà phát triển nên:

Nếu bạn cần tiếp tục sử dụng tạm thời các analyzer đã deprecated, bạn có thể chặn cảnh báo:

xml
<PropertyGroup>
  <NoWarn>$(NoWarn);ASPDEPR007</NoWarn>
</PropertyGroup>

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