Nguon: Microsoft Learn · .NET 8.0

Breaking change: Ngừng sử dụng phương thức mở rộng WithOpenApi

Nguồn: Deprecation of WithOpenApi extension method

Các phương thức WithOpenApi đã bị ngừng sử dụng trong .NET 10. Việc gọi các phương thức này giờ đây tạo ra diagnostic (chẩn đoán) compile-time (thời gian biên dịch) ASPDEPR002 và cảnh báo Obsolete tiêu chuẩn với nội dung:

WithOpenApi is deprecated and will be removed in a future release. For more information, visit https://aka.ms/aspnet/deprecate/002. (WithOpenApi đã lỗi thời và sẽ bị xóa trong phiên bản tương lai.)

Phiên bản ra mắt

.NET 10 Preview 7

Hành vi trước đây

Trước đây, bạn có thể dùng phương thức mở rộng WithOpenApi mà không có cảnh báo nào:

csharp
app.MapGet("/weather", () => ...)
   .WithOpenApi();   // Không có cảnh báo.

Hành vi mới

Kể từ .NET 10, việc dùng phương thức mở rộng WithOpenApi tạo ra cảnh báo compiler (trình biên dịch):

csharp
app.MapGet("/weather", () => ...)
   .WithOpenApi();   // Cảnh báo ASPDEPR002: WithOpenApi is deprecated...

Tuy nhiên, lệnh gọi vẫn biên dịch và thực thi được.

Loại breaking change

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

Lý do thay đổi

WithOpenApi đã sao chép chức năng giờ đây được cung cấp bởi built-in OpenAPI document generation pipeline (đường ống tạo tài liệu OpenAPI tích hợp sẵn). Việc ngừng sử dụng nó đơn giản hóa API surface (bề mặt API) và chuẩn bị cho việc xóa bỏ cuối cùng.

Hành động khuyến nghị

Xóa các lệnh gọi .WithOpenApi() khỏi code của bạn.

Trước:

```csharp using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(); var app = builder.Build();

app.MapGet("/weather", () => ...) .WithOpenApi(operation => { // Điều chỉnh từng endpoint operation.Summary = "Gets the current weather report."; operation.Description = "Returns a short description and emoji."; return operation; });

app.Run(); ```

Sau:

```csharp using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(); var app = builder.Build();

app.MapGet("/weather", () => ...) .AddOpenApiOperationTransformer((operation, context, ct) => { // Điều chỉnh từng endpoint operation.Summary = "Gets the current weather report."; operation.Description = "Returns a short description and emoji."; return Task.CompletedTask; });

app.Run(); ```

API bị ảnh hưởng