Свойство IncludeOpenAPIAnalyzers и анализаторы API MVC устарели

Свойство IncludeOpenAPIAnalyzers MSBuild и связанные анализаторы API MVC устарели и будут удалены в будущем выпуске. Если IncludeOpenAPIAnalyzers задано значение true, сборка теперь выдает предупреждение ASPDEPR007.

Представленная версия

.NET 10 (предварительная версия 7)

Предыдущее поведение

Ранее в проектах Web SDK можно было настроить <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>, чтобы включить анализаторы API MVC без каких-либо предупреждений или уведомлений о прекращении использования.

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

Такой проект успешно создан без предупреждений об отмене.

Новое поведение

Начиная с .NET 10, если IncludeOpenAPIAnalyzers задано значение true, сборка выдает предупреждение ASPDEPR007:

предупреждение ASPDEPR007. Свойство IncludeOpenAPIAnalyzers и связанные с ним анализаторы API MVC устарели и будут удалены в будущем выпуске.

Анализаторы продолжают функционировать, но разработчики получают это предупреждение об нерекомендуемом во время компиляции.

Тип разрушающего изменения

Это изменение может повлиять на совместимость исходного кода .

Причина изменения

Анализаторы API MVC изначально были представлены для обеспечения синхронизации возвращаемых типов и атрибутов для контроллеров API, обеспечивая согласованность между сигнатурами методов и соответствующей документацией OpenAPI. Эти анализаторы предоставили проверку во время компиляции для перехвата несоответствий между объявленными типами возврата и фактическими типами, возвращаемыми действиями контроллера.

Однако при внедрении минимальных API и TypedResults шаблона экосистема .NET развивалась в направлении более типобезопасного подхода для разработки API. TypedResults предоставляет гарантии во время компиляции о типах ответов, не требуя дополнительных анализаторов, что делает анализаторы API MVC избыточными для современных приложений .NET. В .NET 10 TypedResults поддерживаются в API на основе контроллера.

Предыдущий подход с анализаторами API MVC:

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

Современный подход с 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);
}

Шаблон TypedResults устраняет необходимость отдельных анализаторов, так как сам возвращаемый тип (Results<Ok<Product>, NotFound>) явно объявляет все возможные типы ответов во время компиляции. Этот подход является более поддерживающим, обеспечивает улучшенную поддержку IntelliSense и автоматически создает точную документацию OpenAPI без дополнительных инструментов.

Поскольку экосистема .NET продолжает принимать TypedResults в качестве рекомендуемого шаблона для разработки API, анализаторы API MVC стали устаревшими и устарели для упрощения процесса разработки.

Рекомендуемое действие

Разработчики должны:

• Удалите нерекомендуемое свойство: удалите <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> из файлов проекта, чтобы исключить предупреждение.
• TypedResultsМиграция в: миграция в TypedResults шаблон, чтобы обеспечить лучшую согласованность между поведением приложения и документацией OpenAPI.

Если вам нужно временно использовать устаревшие анализаторы, вы можете отключить предупреждение:

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

Затронутые API

• Свойство MSBuild: IncludeOpenAPIAnalyzers.
• Связанные анализаторы API MVC, включенные при IncludeOpenAPIAnalyzers использовании true.