警告 CA1416:プラットフォームの互換性

  • [アーティクル]

.NET コード アナライザー ルール CA1416 は、.NET 5 以降では既定で有効になっています。 オペレーティング システムが検証されていない呼び出しサイトからのプラットフォーム固有の API への呼び出しに対し、ビルドの警告が生成されます。

変更内容

.NET 5 以降、.NET SDK には .NET ソース コード アナライザーが含まれています。 これらのルールのいくつかは、CA1416 を含め、既定で有効になっています。 このルールに違反し、警告をエラーとして扱うように構成されているコードがプロジェクトに含まれている場合、この変更によってビルドが破損する可能性があります。 ルール CA1416 では、プラットフォームのコンテキストが検証されていない場所からプラットフォーム固有の API を使用していることが通知されます。

ルール CA1416 のプラットフォーム互換性アナライザーは、.NET 5 の他の新機能の一部と連携して動作します。 .NET 5 において導入された SupportedOSPlatformAttribute と UnsupportedOSPlatformAttribute では、API がサポートされて "いる"、またはサポートされて "いない" プラットフォームを指定できます。 これらの属性が存在しない場合、API はすべてのプラットフォームでサポートされているものと見なされます。 これらの属性は、Core .NET ライブラリ内のプラットフォーム固有の API に適用されています。

プロジェクトで使用されている API が、プロジェクトのターゲット プラットフォームでは使用できないものである場合、ルール CA1416 により、プラットフォームのコンテキストが検証されないプラットフォーム固有のすべての API 呼び出しに、フラグが設定されます。 SupportedOSPlatformAttribute 属性および UnsupportedOSPlatformAttribute 属性で装飾されている API のほとんどでは、サポートされていないオペレーティング システムで呼び出されると、PlatformNotSupportedException 例外がスローされます。 これらの 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 の場合:

関連項目