CA2252: 미리 보기 기능을 사용하기 전에 옵트인

원인

클라이언트가 로컬로 또는 모듈 또는 어셈블리 수준에서 명시적으로 옵트인하지 않고 어셈블리에서 미리 보기 API 또는 형식을 사용합니다.

규칙 설명

RequiresPreviewFeaturesAttribute 특성으로 데코레이트된 API 또는 어셈블리를 사용하는 경우 이 규칙은 호출 사이트에서 미리 보기 기능을 옵트인했는지 여부를 확인합니다. 다음 중 하나가 적용되는 경우 호출 사이트에서 미리 보기 기능을 옵트인한 것입니다.

• RequiresPreviewFeaturesAttribute 주석 범위 내에 있습니다.
• 미리 보기 기능을 이미 옵트인한 어셈블리 또는 모듈의 일부입니다.

다음 이미지에서는 CA2252 진단의 예를 보여 줍니다.

여기서 Lib는 Main 메서드에서 생성되는 미리 보기 유형입니다. Main 자체는 미리 보기 메서드로 주석이 추가되지 않으므로 진단은 Main 내에서 두 개의 생성자 호출에 생성됩니다.

위반 문제를 해결하는 방법

위반을 해결하는 방법에는 두 가지가 있습니다.

• 부모에 RequiresPreviewFeaturesAttribute 주석을 추가하여 호출 사이트를 주석 범위 내로 가져옵니다. 이전 예제에서 APreviewMethod는 RequiresPreviewFeatures 특성이 주석으로 추가되었으므로 분석기는 APreviewMethod 내부의 미리 보기 유형 사용을 무시합니다. 따라서 APreviewMethod의 호출자가 유사한 실행을 수행해야 합니다.

• 어셈블리 또는 모듈 수준에서 미리 보기 기능을 옵트인할 수도 있습니다. 이는 분석기에게 어셈블리에서 미리 보기 유형 사용이 필요함을 나타내며, 결과적으로 이 규칙에 따라 오류가 생성되지 않습니다. 미리 보기 종속성을 사용하는 기본 방법입니다. 전체 어셈블리 내에서 미리 보기 기능을 사용하도록 설정하려면 .csproj 파일에서 EnablePreviewFeatures 속성을 설정합니다.

  <PropertyGroup>
    <EnablePreviewFeatures>true</EnablePreviewFeatures>
  </PropertyGroup>

경고를 표시하지 않는 경우

이 규칙에서 경고를 표시하지 않는 것은 API에 대한 진단을 명시적으로 사용하지 않도록 설정해야 하는 고급 사용 사례에만 권장됩니다. 이 경우 미리 보기 API를 적절하게 표시해야 합니다. 예를 들어 기존 형식이 새 미리 보기 인터페이스를 구현하는 경우를 가정해 보겠습니다. 전체 형식을 미리 보기로 표시할 수 없기 때문에(이전 버전과의 호환성을 위해) 형식 정의에 대한 진단을 로컬에서 비활성화할 수 있습니다. 또한 미리 보기 인터페이스 구현을 미리 보기로 표시해야 합니다. 이제 기존 형식을 이전처럼 사용할 수 있지만 새 인터페이스 메서드를 호출하면 진단을 받게 됩니다. System.Private.CoreLib.csproj는 이 기술을 사용하여 Int32, Double, Decimal과 같은 숫자 형식에 일반적인 수학 기능을 노출합니다.

다음 이미지에서는 로컬에서 CA2252 분석기를 사용하지 않도록 설정하는 방법을 보여 줍니다.

경고 표시 안 함

단일 위반만 표시하지 않으려면 원본 파일에 전처리기 지시문을 추가하여 규칙을 사용하지 않도록 설정한 후 다시 사용하도록 설정합니다.

#pragma warning disable CA2252
// The code that's violating the rule is on this line.
#pragma warning restore CA2252

파일, 폴더 또는 프로젝트에 대한 규칙을 사용하지 않도록 설정하려면 구성 파일에서 심각도를 none으로 설정합니다.

[*.{cs,vb}]
dotnet_diagnostic.CA2252.severity = none

이 전체 규칙 범주를 사용하지 않도록 설정하려면 구성 파일에서 범주의 심각도를 none으로 설정합니다.

[*.{cs,vb}]
dotnet_analyzer_diagnostic.category-Usage.severity = none

자세한 내용은 방법: 코드 분석 경고 표시 안 함을 참조하세요.

참고 항목

• EnablePreviewFeatures 및 GenerateRequiresPreviewFeaturesAttribute
• 미리 보기 기능 디자인 문서