다음을 통해 공유

IncludeOpenAPIAnalyzers 속성 및 MVC API 분석기는 더 이상 사용되지 않습니다.

IncludeOpenAPIAnalyzers MSBuild 속성 및 관련 MVC API 분석기는 더 이상 사용되지 않으며 향후 릴리스에서 제거될 예정입니다. IncludeOpenAPIAnalyzers이 true로 설정되면, 이제 빌드는 경고 ASPDEPR007를 출력합니다.

도입된 버전

.NET 10 미리 보기 7

이전 동작

이전에는 경고 또는 사용 중단 알림 없이 MVC API 분석기를 사용하도록 웹 SDK 프로젝트에서 설정할 <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> 수 있습니다.

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

이러한 프로젝트는 사용 중단 경고 없이 성공적으로 빌드되었습니다.

새 동작

.NET 10, IncludeOpenAPIAnalyzers가 true으로 설정되면 빌드가 경고 ASPDEPR007를 내보낸다.

경고 ASPDEPR007: IncludeOpenAPIAnalyzers 속성 및 관련 MVC API 분석기는 더 이상 사용되지 않으며 향후 릴리스에서 제거될 예정입니다.

분석기는 계속 작동하지만 개발자는 컴파일 중에 이 사용 중단 경고를 받습니다.

파괴적 변경 유형

이 변경 사항은 소스 호환성에 영향을 줄 수 있습니다.

변경 이유

MVC API 분석기는 원래 API 컨트롤러에 대한 반환 형식 및 특성을 동기화 상태로 유지하여 메서드 서명과 해당 OpenAPI 설명서 간의 일관성을 보장하기 위해 도입되었습니다. 이러한 분석기는 선언된 반환 형식과 컨트롤러 작업에서 반환된 실제 형식 간의 불일치를 catch하기 위한 컴파일 시간 유효성 검사를 제공했습니다.

그러나 Minimal API 및 TypedResults 패턴의 도입으로 .NET 에코시스템은 API 개발을 위한 보다 형식 안전한 접근 방식으로 발전했습니다. TypedResults는 추가 분석기를 요구하지 않고 응답 형식에 대한 컴파일 시간 보장을 제공하여 최신 .NET 애플리케이션에서 MVC API 분석기를 불필요하게 합니다. .NET 10에서는 TypedResults 컨트롤러 기반 API에서 지원됩니다.

MVC API 분석기를 사용하는 이전 방법:

[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 에코시스템이 API 개발의 권장 패턴으로 TypedResults을(를) 계속 수용함에 따라, MVC API 분석기는 더 이상 필요하지 않으며, 개발 경험을 간소화하기 위해 사용 중단되었습니다.

개발자는 다음을 수행해야 합니다.

  • 사용되지 않는 속성을 제거하세요: 경고를 제거하려면 프로젝트 파일에서 <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> 를 제거하세요.
  • 마이그레이션 TypedResults: 패턴으로 마이그레이션하여 TypedResults 애플리케이션 동작과 OpenAPI 설명서 간의 일관성을 향상합니다.

사용되지 않는 분석기를 일시적으로 계속 사용해야 하는 경우 경고를 표시하지 않을 수 있습니다.

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

영향을 받는 API

  • MSBuild 속성: IncludeOpenAPIAnalyzers.
  • IncludeOpenAPIAnalyzers이 true인 경우 관련 MVC API 분석기가 포함됩니다.
  • Last updated on