Peringatan CA1416: Kompatibilitas platform

Artikel
10/04/2023

Aturan penganalisis kode .NET CA1416 diaktifkan, secara default, dimulai di .NET 5. Ini menghasilkan peringatan build untuk panggilan ke API khusus platform dari situs panggilan yang tidak memverifikasi sistem operasi.

Deskripsi perubahan

Mulai dari .NET 5, .NET SDK menyertakan penganalisis kode sumber .NET. Beberapa aturan ini diaktifkan, secara default, termasuk CA1416. Jika proyek Anda berisi kode yang melanggar aturan ini dan dikonfigurasi untuk memperlakukan peringatan sebagai kesalahan, perubahan ini dapat merusak build Anda. Aturan CA1416 memberi tahu Anda saat Anda menggunakan API khusus platform dari tempat di mana konteks platform tidak diverifikasi.

Aturan CA1416, penganalisis kompatibilitas platform, bekerja bersama dengan beberapa fitur lain yang baru di .NET 5. .NET 5 memperkenalkan SupportedOSPlatformAttribute dan UnsupportedOSPlatformAttribute, yang memungkinkan Anda menentukan platform tempat API atau tidak didukung. Dengan tidak adanya atribut ini, API diasumsikan didukung di semua platform. Atribut ini telah diterapkan ke API khusus platform di pustaka .NET inti.

Dalam proyek yang menargetkan platform tempat API yang mereka gunakan tidak tersedia, aturan CA1416 menandai panggilan API khusus platform di mana konteks platform tidak diverifikasi. Sebagian besar API yang sekarang dihiasi dengan SupportedOSPlatformAttribute atribut dan UnsupportedOSPlatformAttribute melemparkan PlatformNotSupportedException pengecualian ketika dipanggil pada sistem operasi yang tidak didukung. Sekarang setelah API ini ditandai sebagai khusus platform, aturan CA1416 membantu Anda mencegah pengecualian run-time PlatformNotSupportedException dengan menambahkan pemeriksaan OS ke situs panggilan Anda.

Contoh

Metode Console.Beep(Int32, Int32) ini hanya didukung pada Windows dan dihiasi dengan [SupportedOSPlatform("windows")]. Kode berikut akan menghasilkan peringatan CA1416 pada waktu build jika proyek menargetkan net5.0 (lintas platform). Tetapi kode ini tidak akan memperingatkan jika proyek menargetkan Windows (net5.0-windows) dan GenerateAssemblyInfo diaktifkan untuk proyek. Untuk tindakan yang dapat Anda ambil untuk menghindari peringatan, lihat Tindakan yang direkomendasikan.
```
public void PlayCMajor()
{
    Console.Beep(261, 1000);
}
```
Metode Image.FromFile(String) ini tidak didukung di browser dan dihiasi dengan [UnsupportedOSPlatform("browser")]. Kode berikut akan menghasilkan peringatan CA1416 pada waktu build jika proyek mendukung platform browser.
```
public void CreateImage()
{
    Image newImage = Image.FromFile("SampImag.jpg");
}
```
Tip

Proyek Blazor WebAssembly dan proyek pustaka kelas Razor menyertakan dukungan browser secara otomatis. Untuk menambahkan browser secara manual sebagai platform yang didukung untuk proyek Anda, tambahkan entri berikut ke file proyek Anda:
```
<ItemGroup>
  <SupportedPlatform Include="browser" />
</ItemGroup>
```

Versi yang diperkenalkan

5.0

Tindakan yang direkomendasikan

Pastikan API khusus platform hanya dipanggil saat kode berjalan pada platform yang sesuai. Anda dapat memeriksa sistem operasi saat ini menggunakan salah Is<Platform> satu metode di System.OperatingSystem kelas , misalnya, OperatingSystem.IsWindows(), sebelum memanggil API khusus platform.

Anda dapat menggunakan salah Is<Platform> satu metode dalam kondisi if pernyataan:

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

Atau, jika Anda tidak ingin overhead pernyataan tambahan if pada waktu proses, panggil Debug.Assert(Boolean) sebagai gantinya:

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

Jika Anda menulis pustaka, Anda dapat menandai API Anda sebagai khusus platform. Dalam hal ini, beban persyaratan pemeriksaan jatuh pada penelepon Anda. Anda dapat menandai metode atau jenis tertentu atau seluruh perakitan.

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

Jika Anda tidak ingin memperbaiki semua situs panggilan, Anda bisa memilih salah satu opsi berikut untuk menekan peringatan:

Untuk menekan aturan CA1416, Anda dapat melakukannya menggunakan #pragma atau bendera pengompilasi NoWarn, atau dengan mengatur tingkat keparahan aturan ke none dalam file .editorconfig.
```
public void PlayCMajor()
{
#pragma warning disable CA1416
    Console.Beep(261, 1000);
#pragma warning restore CA1416
}
```
Untuk menonaktifkan analisis kode sepenuhnya, atur EnableNETAnalyzers ke false dalam file proyek Anda. Untuk informasi selengkapnya, lihat EnableNETAnalyzers.

API yang Terpengaruh

Untuk platform Windows:

Untuk platform Blazor WebAssembly:

Semua API yang tercantum di https://github.com/dotnet/runtime/issues/41087.

Bagikan melalui