Share via

경고 CA1416: 플랫폼 호환성

  • 아티클

.NET 코드 분석기 규칙 CA1416은 .NET 5부터 기본적으로 사용됩니다. 운영 체제를 확인하지 않는 호출 사이트에서 플랫폼별 API에 대한 호출의 빌드 경고를 생성합니다.

변경 내용 설명

.NET 5부터 .NET SDK에는 .NET 소스 코드 분석기가 포함됩니다. CA1416을 포함하여 해당 규칙 중 여러 개가 기본적으로 사용됩니다. 해당 규칙을 위반하는 코드가 프로젝트에 포함되고 프로젝트가 경고를 오류로 처리하도록 구성된 경우 해당 변경으로 인해 빌드의 호환성이 손상될 수 있습니다. 규칙 CA1416은 플랫폼 컨텍스트가 확인되지 않는 위치에서 플랫폼별 API를 사용하는 경우 알림을 제공합니다.

규칙 CA1416, 플랫폼 호환성 분석기는 .NET 5에 새로 도입된 다른 일부 기능과 함께 작동합니다. .NET 5에는 API를 ‘지원’하거나 ‘지원하지 않는’ 플랫폼을 지정할 수 있는 SupportedOSPlatformAttribute 및 UnsupportedOSPlatformAttribute가 도입되었습니다. 이러한 특성이 없으면 API는 모든 플랫폼에서 지원되는 것으로 간주됩니다. 해당 특성은 핵심 .NET 라이브러리의 플랫폼별 API에 적용되었습니다.

해당 API를 사용할 수 없는 플랫폼을 대상으로 하는 프로젝트에서 규칙 CA1416은 플랫폼 컨텍스트가 확인되지 않는 플랫폼별 API 호출을 플래그로 지정합니다. 현재 SupportedOSPlatformAttribute 및 UnsupportedOSPlatformAttribute 특성으로 데코레이트된 대부분의 API는 지원되지 않는 운영 체제에서 호출되는 경우 PlatformNotSupportedException 예외를 throw합니다. 이러한 API는 플랫폼별로 표시되어 있으므로 규칙 CA1416을 사용하면 호출 사이트에 OS 검사를 추가하여 런타임 PlatformNotSupportedException 예외를 방지하는 데 도움이 됩니다.

예제

  • Console.Beep(Int32, Int32) 메서드는 Windows에서만 지원되고 [SupportedOSPlatform("windows")]으로 데코레이트됩니다. 다음 코드는 프로젝트가 net5.0(플랫폼 간)을 대상으로 하는 경우 빌드 시 CA1416 경고를 생성합니다. 하지만 프로젝트가 Windows(net5.0-windows)를 대상으로 하고 GenerateAssemblyInfo가 프로젝트에 대해 사용 설정된 경우 이 코드를 경고를 보내지 않습니다. 경고를 방지하기 위해 수행할 수 있는 작업은 권장 조치를 참조하세요.

    public void PlayCMajor()
{
    Console.Beep(261, 1000);
}

  • Image.FromFile(String) 메서드는 브라우저에서 지원되지 않으며 [UnsupportedOSPlatform("browser")]으로 데코레이트됩니다. 다음 코드는 프로젝트가 브라우저 플랫폼을 지원하는 경우 빌드 시 CA1416 경고를 생성합니다.

    public void CreateImage()
{
    Image newImage = Image.FromFile("SampImag.jpg");
}

    팁

    Blazor WebAssembly 프로젝트 및 Razor 클래스 라이브러리 프로젝트에는 브라우저 지원이 자동으로 포함됩니다. 프로젝트에 지원되는 플랫폼으로 수동으로 브라우저를 추가하려면 프로젝트 파일에 다음 항목을 추가하세요.

    <ItemGroup>
  <SupportedPlatform Include="browser" />
</ItemGroup>

도입된 버전

5.0

적절한 플랫폼에서 코드가 실행되는 경우에만 플랫폼별 API가 호출되도록 합니다. 플랫폼별 API를 호출하기 전에 System.OperatingSystem 클래스에서 Is<Platform> 메서드 중 하나(예: OperatingSystem.IsWindows())를 사용하여 현재 운영 체제를 확인할 수 있습니다.

if 문의 조건에 Is<Platform> 메서드 중 하나를 사용할 수 있습니다.

public void PlayCMajor()
{
    if (OperatingSystem.IsWindows())
    {
        Console.Beep(261, 1000);
    }
}

또는 런타임에 추가 if 문의 오버헤드를 원하지 않는다면 대신 Debug.Assert(Boolean)를 호출합니다.

public void PlayCMajor()
{
    Debug.Assert(OperatingSystem.IsWindows());
    Console.Beep(261, 1000);
}

라이브러리를 제작하는 경우 API를 플랫폼별로 표시할 수 있습니다. 이 경우 요구 사항을 확인하는 것은 호출자의 책임입니다. 특정 메서드나 유형 또는 전체 어셈블리를 표시할 수 있습니다.

[SupportedOSPlatform("windows")]
public void PlayCMajor()
{
    Console.Beep(261, 1000);
}

모든 호출 사이트를 수정하지는 않으려면 다음 옵션 중 하나를 선택하여 경고를 중지할 수 있습니다.

  • 규칙 CA1416을 중지하려면 #pragma 또는 NoWarn 컴파일러 플래그를 사용하거나 editorconfig 파일에서 규칙의 심각도를 none으로 설정하면 됩니다.

    public void PlayCMajor()
{
#pragma warning disable CA1416
    Console.Beep(261, 1000);
#pragma warning restore CA1416
}

  • 코드 분석을 완전히 사용하지 않으려면 프로젝트 파일에서 EnableNETAnalyzers를 false로 설정합니다. 자세한 내용은 EnableNETAnalyzers를 참조하세요.

영향을 받는 API

Windows 플랫폼:

Blazor WebAssembly 플랫폼:

참고 항목