CA1418: Überprüfender Plattformkompatibilität

  • Artikel
Eigenschaft Wert
Regel-ID CA1418
Titel Plattformkompatibilität überprüfen
Kategorie Interoperabilität
Fix führt oder führt nicht zur Unterbrechung Nicht unterbrechend
Standardmäßig in .NET 8 aktiviert Als Warnung

Ursache

Das Analyseprogramm für Plattformkompatibilität erfordert einen gültigen Plattformnamen und eine gültige Version. Verstöße werden gemeldet, wenn die an den OSPlatformAttribute-Konstruktor übergebene Plattformzeichenfolge aus einem unbekannten Plattformnamen besteht oder wenn der optionale Versionsteil ungültig ist.

Regelbeschreibung

Die von OSPlatformAttribute abgeleiteten Plattformkompatibilitätsattribute verwenden Zeichenfolgenliterale für Betriebssystem-Plattformnamen mit einem optionalen Versionsteil. Die Zeichenfolge sollte aus einem bekannten Plattformnamen und entweder keinem Versionsteil oder einem gültigen Versionsteil bestehen.

Die Liste der bekannten Plattformnamen wird aus zwei Quellen entnommen:

  • Dem PlatformName-Teil der OperatingSystem Schutzmethoden mit dem Namen OperatingSystem.Is<PlatformName>[VersionAtLeast](). Beispielsweise fügt die Schutzmethode OperatingSystem.IsWindows() der Liste der bekannten Plattformnamen Windows hinzu.

  • Der MSBuild-Elementgruppe der SupportedPlatform-Elemente des Projekts, einschließlich der Standardliste MSBuild SupportedPlatforms. Dies ist das projektspezifische Wissen über bekannte Plattformen. Dadurch können Klassenbibliotheksautoren der Liste der bekannten Plattformen weitere Plattformen hinzufügen. Beispiel:

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

Wenn die Plattformzeichenfolge einen Versionsteil enthält, sollte dies eine gültige Version im folgenden Format sein: major.minor[.build[.revision]].

Verletzungen

  • Solaris ist ein unbekannter Plattformname, da er nicht in der Standardliste MSBuild SupportedPlatforms enthalten ist und es keine Schutzmethode mit dem Namen OperatingSystem.IsSolaris() in der Klasse OperatingSystem gibt.

    [SupportedOSPlatform("Solaris")] // Warns: The platform 'Solaris' is not a known platform name.
public void SolarisApi() { }

  • Android ist eine bekannte Plattform, weil es eine OperatingSystem.IsAndroid()-Schutzmethode im Typ OperatingSystem gibt. Der Versionsteil ist jedoch keine gültige Version. Er sollten mindestens zwei ganze Zahlen aufweisen, die durch einen Punkt getrennt sind.

    [UnsupportedOSPlatform("Android10")] // Warns: Version '10' is not valid for platform 'Android'. Use a version with 2-4 parts for this platform.
public void DoesNotWorkOnAndroid() { }

  • Linux ist eine bekannte Plattform, da sie in der Standardliste MSBuild SupportedPlatforms enthalten ist und es auch eine Schutzmethode mit dem Namen OperatingSystem.IsLinux() gibt. Es gibt jedoch keine Schutzmethoden mit Versionsangabe wie System.OperatingSystem.IsLinuxVersionAtLeast(int,int) für die Linux-Plattform, daher wird unter Linux kein Versionsteil unterstützt.

    [SupportedOSPlatform("Linux4.8")] // Warns: Version '4.8' is not valid for platform 'Linux'. Do not use versions for this platform.
public void LinuxApi() { }

Behandeln von Verstößen

  • Ändern Sie die Plattform in einen bekannten Plattformnamen.

  • Wenn der Plattformname richtig ist und Sie ihn zu einer bekannten Plattform machen möchten, fügen Sie ihn der Liste „MSBuild SupportedPlatforms“ in Ihrer Projektdatei hinzu:

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

    [SupportedOSPlatform("Solaris")] // No warning
public void SolarisApi() { }

  • Korrigieren Sie die ungültige Version. Beispielsweise ist für Android10 keine gültige Version, aber 10.0 ist gültig.

    // Before
[UnsupportedOSPlatform("Android10")] // Warns: Version '10' is not valid for platform 'Android'. Use a version with 2-4 parts for this platform.
public void DoesNotWorkOnAndroid() { }

// After
[UnsupportedOSPlatform("Android10.0")] // No warning.
public void DoesNotWorkOnAndroid() { }

  • Wenn die Plattform keine Version unterstützt, entfernen Sie den Versionsteil.

    // Before
[SupportedOSPlatform("Linux4.8")] // Warns: Version '4.8' is not valid for platform 'Linux'. Do not use versions for this platform.
public void LinuxApi() { }

// After
[SupportedOSPlatform("Linux")] // No warning.
public void LinuxApi() { }

Wann sollten Warnungen unterdrückt werden?

Die Verwendung eines unbekannten Plattformnamens oder einer ungültigen Version wird nicht empfohlen, daher sollten Sie diese Regel nicht unterdrücken.

Weitere Informationen