IncludeOpenAPIAnalyzers özelliği ve MVC API çözümleyicileri kullanım dışı bırakıldı

IncludeOpenAPIAnalyzers MSBuild özelliği ve ilişkili MVC API çözümleyicileri kullanım dışıdır ve gelecek bir sürümde kaldırılacaktır. IncludeOpenAPIAnalyzers olarak ayarlandığında true, derleme artık uyarı ASPDEPR007 üretecek.

Sürüm kullanıma sunulmuştur

.NET 10 Preview 7

Önceki davranış

Daha önce, Web SDK projelerinizde MVC API çözümleyicilerini herhangi bir uyarı veya kullanım dışı bırakma bildirimi olmadan etkinleştirmek için <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> ayarlayabiliyordunuz.

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

Böyle bir proje, herhangi bir kullanımdan kaldırma uyarısı olmadan başarıyla oluşturuldu.

Yeni davranış

.NET 10'dan başlayarak, IncludeOpenAPIAnalyzers olarak ayarlandığında true derleme uyarı ASPDEPR007'i görüntüler.

uyarı ASPDEPR007: IncludeOpenAPIAnalyzers özelliği ve ilişkili MVC API çözümleyicileri kullanım dışıdır ve gelecekteki bir sürümde kaldırılacaktır.

Çözümleyiciler çalışmaya devam eder, ancak geliştiriciler derleme sırasında bu kullanımdan kaldırma uyarısını alır.

Kesinti yaratan değişiklik türü

Bu değişiklik kaynak uyumluluğunuetkileyebilir.

Değişiklik nedeni

MVC API çözümleyicileri başlangıçta, dönüş türlerini ve özniteliklerini API denetleyicileri için eşitlenmiş durumda tutmaya yardımcı olmak ve yöntem imzaları ile ilgili OpenAPI belgeleri arasında tutarlılık sağlamaya yardımcı olmak amacıyla sunulmuştur. Bu çözümleyiciler, bildirilen dönüş türleri ile denetleyici eylemleri tarafından döndürülen gerçek türler arasındaki uyuşmazlıkları yakalamak için derleme zamanı doğrulaması sağladı.

Ancak, Minimal API'lerin ve TypedResults şablonunun tanıtımı ile .NET ekosistemi, API geliştirme için daha tip güvenliği olan bir yaklaşıma doğru gelişti. TypedResults ek çözümleyiciler gerektirmeden yanıt türleri hakkında derleme süresi garantileri sağlayarak MVC API çözümleyicilerini modern .NET uygulamaları için yedekli hale getirir. .NET 10'da, TypedResults denetleyici tabanlı API'lerde desteklenir.

MVC API çözümleyicileri ile önceki yaklaşım:

[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 ensures this matches ProducesResponseType(404)

    return Ok(product); // Analyzer ensures this matches ProducesResponseType<Product>(200)
}

Modern yaklaşım TypedResults ile

[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);
}

TypedResults Dönüş türünün kendisi (Results<Ok<Product>, NotFound>) derleme zamanında tüm olası yanıt türlerini açıkça bildirdiğinden, desen ayrı çözümleyiciler gereksinimini ortadan kaldırır. Bu yaklaşım daha sürdürülebilirdir, daha iyi IntelliSense desteği sağlar ve ek araçlar olmadan otomatik olarak doğru OpenAPI belgeleri oluşturur.

.NET ekosistemi API geliştirme için önerilen desen olarak benimsenmeye TypedResults devam ettikçe, MVC API çözümleyicileri kullanımdan kalkmış ve geliştirme deneyimini kolaylaştırmak için kullanım dışı bırakılmıştır.

Önerilen eylem

Geliştiriciler şunları yapmalıdır:

• Kullanım dışı özelliğini kaldırın: Uyarıyı ortadan kaldırmak için proje dosyalarınızdan kaldırın <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> .
• 'a TypedResultsTypedResults geçiş: Uygulama davranışı ile OpenAPI belgeleri arasında daha iyi tutarlılık sağlamak için desene geçiş yapın.

Kullanım dışı bırakılan çözümleyicileri geçici olarak kullanmaya devam etmeniz gerekiyorsa uyarıyı gizleyebilirsiniz:

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

Etkilenen API'ler

• MSBuild özelliği: IncludeOpenAPIAnalyzers.
• IncludeOpenAPIAnalyzers true olduğunda ilişkilendirilmiş MVC API çözümleyicileri dahil edilir.