IncludeOpenAPIAnalyzers-Eigenschaft und MVC-API-Analysegeräte sind veraltet

Die IncludeOpenAPIAnalyzers MSBuild-Eigenschaft und die zugehörigen MVC-API-Analysegeräte sind veraltet und werden in einer zukünftigen Version entfernt. Wenn dieser auf ist, gibt der Build jetzt Warnung aus.

Eingeführte Version

.NET 10 Preview 7

Vorheriges Verhalten

Bisher konnten Sie in Ihren Web SDK-Projekten <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> konfigurieren, um MVC-API-Analysetools ohne Warnungen oder Veralterungshinweise zu aktivieren.

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

Ein solches Projekt wurde ohne veraltete Warnungen erfolgreich erstellt.

Neues Verhalten

Ab .NET 10 gibt der Build warnung IncludeOpenAPIAnalyzersaus, wenn true er auf ASPDEPR007.NET 10 festgelegt ist:

Warnung ASPDEPR007: Die IncludeOpenAPIAnalyzers-Eigenschaft und die zugehörigen MVC-API-Analysegeräte sind veraltet und werden in einer zukünftigen Version entfernt.

Die Analysegeräte funktionieren weiterhin, aber Entwickler erhalten diese Warnung zur Veraltetkeit während der Kompilierung.

Art der einschneidenden Änderung

Diese Änderung kann sich auf die Quellkompatibilität auswirken.

Grund für Änderung

Die MVC-API-Analysegeräte wurden ursprünglich eingeführt, um Rückgabetypen und Attribute für API-Controller synchron zu halten, um die Konsistenz zwischen Methodensignaturen und der entsprechenden OpenAPI-Dokumentation sicherzustellen. Diese Analysatoren haben eine Kompilierungszeitüberprüfung bereitgestellt, um Nichtübereinstimmungen zwischen deklarierten Rückgabetypen und den tatsächlichen Typen abzufangen, die von Controlleraktionen zurückgegeben werden.

Mit der Einführung minimaler APIs und des TypedResults Musters hat sich das .NET-Ökosystem jedoch zu einem typsichereren Ansatz für die API-Entwicklung entwickelt. TypedResults stellt Kompilierungszeitgarantien für Antworttypen bereit, ohne dass zusätzliche Analysegeräte erforderlich sind, wodurch die MVC-API-Analysegeräte für moderne .NET-Anwendungen redundant sind. In .NET 10 TypedResults werden in controllerbasierten APIs unterstützt.

Vorheriger Ansatz mit MVC-API-Analysegeräten:

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

Moderner Ansatz mit TypedResults:

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

Das TypedResults Muster beseitigt die Notwendigkeit separater Analysegeräte, da der Rückgabetyp selbst (Results<Ok<Product>, NotFound>) alle möglichen Antworttypen zur Kompilierungszeit explizit deklariert. Dieser Ansatz ist wartungsfähiger, bietet eine bessere IntelliSense-Unterstützung und generiert automatisch präzise OpenAPI-Dokumentation ohne zusätzliche Tools.

Da das .NET-Ökosystem weiterhin als empfohlenes Muster für die API-Entwicklung verwendet TypedResults wird, sind die MVC-API-Analysegeräte veraltet und veraltet, um die Entwicklungserfahrung zu optimieren.

Empfohlene Aktion

Entwickler sollten:

• Entfernen Sie die veraltete Eigenschaft: Entfernen Sie <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> aus Ihren Projektdateien, um die Warnung zu beseitigen.
• Migrieren Sie zu TypedResults: Migrieren Sie zu dem TypedResults Muster, um eine bessere Konsistenz zwischen Anwendungsverhalten und OpenAPI-Dokumentation sicherzustellen.

Wenn Sie die veralteten Analysegeräte vorübergehend weiterhin verwenden müssen, können Sie die Warnung unterdrücken:

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

Betroffene APIs

• MSBuild-Eigenschaft: IncludeOpenAPIAnalyzers.
• Zugeordnete MVC-API-Analysegeräte, die enthalten sind, wenn IncludeOpenAPIAnalyzers dies der Zeitpunkt ist true.