Platformkompatibilitás-elemző

2025-06-17

Valószínűleg hallotta a "One .NET" mottóját: egyetlen, egységes platform bármilyen típusú alkalmazás létrehozásához. A .NET SDK tartalmazza ASP.NET Core, Entity Framework Core, Windows Forms, WPF és ML.NET, és idővel több platform támogatását is biztosítja. A .NET 5+ arra törekszik, hogy olyan élményt nyújtson, amelyben nem kell törődnie a .NET különböző változataival, de nem próbálja teljesen eltávolítani az alapul szolgáló operációs rendszert (OS). Továbbra is meghívhat platformspecifikus API-kat, például P/Invokes és WinRT.

A platformspecifikus API-k összetevőn való használata azonban azt jelenti, hogy a kód már nem működik az összes platformon. Szükség volt egy módszerre a tervezéskor, hogy a fejlesztők diagnosztikát kapnak, amikor véletlenül platformspecifikus API-kat használnak. E cél elérése érdekében a .NET 5 bevezette a platformkompatibilitás-elemzőt és a kiegészítő API-kat, hogy a fejlesztők szükség esetén könnyebben azonosíthassák és használhassák a platformspecifikus API-kat.

A kiegészítő API-k a következők:

SupportedOSPlatformAttribute az API-k platformspecifikusként való megjegyzése, valamint UnsupportedOSPlatformAttribute az API-k megjegyzése, mivel azok nem támogatottak egy adott operációs rendszeren. Ezek az attribútumok opcionálisan magukban foglalhatják a verziószámot, és már alkalmazták őket az alapvető .NET-kódtárak platformspecifikus API-jaira.
Is<Platform>() és Is<Platform>VersionAtLeast(int major, int minor = 0, int build = 0, int revision = 0) statikus metódusok az osztályban a System.OperatingSystem platformspecifikus API-k biztonságos meghívásához. Használható például OperatingSystem.IsWindows() egy Windows-specifikus API-ra irányuló hívások őrzésére, és OperatingSystem.IsWindowsVersionAtLeast() egy verziószámozott Windows-specifikus API-hívás őrzésére. Tekintse meg ezeket a példákat arra, hogyan használhatók ezek a módszerek platformspecifikus API-hivatkozások őreiként.

Előfeltételek

A platformkompatibilitás-elemző a Roslyn-kódminőség-elemzők egyike. Ezek az elemzők a .NET SDK részét képezik. A platformkompatibilitás-elemző alapértelmezés szerint csak a megcélzott net5.0 vagy újabb verziójú projektek esetében engedélyezett. Más keretrendszereket célzó projektek esetében azonban engedélyezheti .

Hogyan határozza meg az elemző a platformfüggőséget?

Attribútum nélküli API úgy tekinthető, hogy minden operációs rendszer platformon működik.
A [SupportedOSPlatform("platform")] jelöléssel ellátott API-kat csak a megadott platformon és minden olyan platformon tekintjük hordozhatónak, amelynek egy részhalmaza.
- Az attribútum többször is alkalmazható több platform támogatásának jelzésére, például [SupportedOSPlatform("windows"), SupportedOSPlatform("Android29.0")].
- Ha a platform egy másik platform részhalmaza, az attribútum azt jelenti, hogy a szuperhalmazplatform is támogatott. Például, [SupportedOSPlatform("iOS")] azt jelenti, hogy az API támogatott a iOS platformon, valamint a szuperhalmazplatformján is, MacCatalyst.
- Az elemző figyelmeztetést küld, ha a platformspecifikus API-kra megfelelő platformkörnyezet nélkül hivatkoznak:
  - Figyelmeztet, ha a projekt nem a támogatott platformot célozza (például egy iOS-t <TargetFramework>net5.0-ios14.0</TargetFramework>célzó projektből hívott Windows-specifikus API- t).
  - Figyelmeztet, ha a projekt platformfüggetlen, és platformspecifikus API-kat hív meg (például egy Platformfüggetlen TFM-ről <TargetFramework>net5.0</TargetFramework>hívott Windows-specifikus API-t).
  - Nem figyelmeztet, ha a platformspecifikus API-ra olyan projekten belül hivatkozik, amely a megadott platformok bármelyikét célozza (például egy Windows-specifikus API-t, amelyet egy windowsos <TargetFramework>net5.0-windows</TargetFramework> projekt hív meg, és a AssemblyInfo.cs fájlgenerálás engedélyezve van a projekthez).
  - Nem figyelmeztet, ha a platformspecifikus API-hívást megfelelő platformellenőrzési metódusok védik (például egy Windows-specifikus API-hívást).OperatingSystem.IsWindows()
  - Nem figyelmeztet, ha a platformspecifikus API-ra ugyanabból a platformspecifikus környezetből hivatkozik (a hívási hely is hozzá van rendelve[SupportedOSPlatform("platform")).
A megjelölt [UnsupportedOSPlatform("platform")] API-k nem támogatottak a megadott platformon és annak részplatformjain, de támogatottak az összes többi platformon.
- Az attribútum több alkalommal is alkalmazható különböző platformokon, például [UnsupportedOSPlatform("iOS"), UnsupportedOSPlatform("Android29.0")].
- Ha a platform egy másik platform részhalmaza, az attribútum azt jelenti, hogy a szuperhalmazplatform szintén nem támogatott. Például, [UnsupportedOSPlatform("iOS")] azt jelenti, hogy az API nem támogatott iOS-en, valamint annak szuperhalmazplatformján is, MacCatalyst.
- Az elemző csak akkor állít elő figyelmeztetést , ha a platform híváshely érvényes:
  - Figyelmezteti , ha a projekt a nem támogatottnak tulajdonított platformot célozza meg (például ha az API-t [UnsupportedOSPlatform("windows")] hozzárendelték, és a híváshely céljait <TargetFramework>net5.0-windows</TargetFramework>).
  - Figyelmeztet, ha a projekt több célplatformot céloz meg és az platform az alapértelmezett MSBuild <SupportedPlatform> elemek csoportjához lett hozzáadva, vagy manuálisan van szerepeltetve a platform elem a MSBuild<TámogatottPlatform> elemek csoportjában.
```
<ItemGroup>
    <SupportedPlatform Include="platform" />
</ItemGroup>
```
  - Nem figyelmeztet, ha olyan alkalmazást készít, amely nem a nem támogatott platformot célozza meg, vagy több célplatformot céloz, és a platform nem szerepel az alapértelmezett MSBuild <SupportedPlatform> elemek csoportjában.
Mindkét attribútum példányosítható verziószámmal vagy anélkül a platformnév részeként. A verziószámok formátuma major.minor[.build[.revision]]kötelező, major.minor és az buildrevision alkatrészek nem kötelezőek. A "Windows6.1" például a Windows 6.1-es verzióját jelzi, a "Windows" azonban Windows 0.0-ként van értelmezve.

További információ: példák az attribútumok működésére és az általuk okozott diagnosztikára.

Hogyan ismeri fel az elemző a TFM-célplatformokat?

Az elemző nem ellenőrzi a cél-keretrendszer-moniker (TFM) célplatformokat az MSBuild tulajdonságokból, például <TargetFramework> vagy <TargetFrameworks>. Ha a TFM célplatformmal rendelkezik, az MSBuild egy attribútumot injektál SupportedOSPlatform a célplatform nevével a AssemblyInfo.cs fájlba, amelyet az elemző használ. Például, ha a TFM `net5.0-windows10.0.19041`, akkor az MSBuild a `[assembly: System.Runtime.Versioning.SupportedOSPlatform("windows10.0.19041")]` attribútumot a `AssemblyInfo.cs` fájlba injektálja, és az egész összeállítás csak Windows-ként van kezelve. Ezért a csak a 7.0-s vagy újabb verziójú Windows API-k meghívása nem okoz figyelmeztetést a projektben.

Megjegyzés:

Ha a AssemblyInfo.cs fájl generálása le van tiltva a projektben (azaz a <GenerateAssemblyInfo> tulajdonság értéke false), a szükséges szerelvényszintű SupportedOSPlatform attribútumot az MSBuild nem tudja hozzáadni. Ebben az esetben a platformspecifikus API-k használatára vonatkozó figyelmeztetések akkor is megjelenhetnek, ha a platformot célozza. A figyelmeztetések feloldásához engedélyezze a AssemblyInfo.cs fájlgenerálást, vagy adja hozzá manuálisan az attribútumot a projekthez.

Platformintegrálás

A .NET 6 bevezette a platformbefoglalás fogalmát, amelyben az egyik platform egy másik platform részhalmaza lehet. Az alhalmazplatform széljegyzetei ugyanazt a támogatást (vagy annak hiányát) jelentik a szuperhalmazplatform esetében. Ha a típusban egy OperatingSystem platformellenőrzési módszer attribútummal rendelkezik SupportedOSPlatformGuard("supersetPlatform")] , akkor supersetPlatform az operációsrendszer-platform azon szuperhalmazának minősül, amelyet a metódus ellenőriz.

Például a OperatingSystem.IsIOS() metódust [SupportedOSPlatformGuard("MacCatalyst")]-nek tulajdonítják. Ezért a következő utasítások érvényesek:

A OperatingSystem.IsIOS() és OperatingSystem.IsIOSVersionAtLeast metódusok nemcsak a iOS platformot, hanem a MacCatalyst platformot is ellenőrzik.
[SupportedOSPlatform("iOS")] azt jelenti, hogy az API-t a iOS és annak szuperhalmaz platformján, a MacCatalyst is támogatják. Az attribútummal kizárhatja ezt a [UnsupportedOSPlatform("MacCatalyst")] vélelmezett támogatást.
[UnsupportedOSPlatform("iOS") azt jelenti, hogy az API nem támogatott sem iOS-en, sem MacCatalyst-on. Az attribútum használatával kizárhatja ezt a [SupportedOSPlatform("MacCatalyst")] vélelmezett támogatáshiányt.

Vegye figyelembe a következő lefedettségi mátrixot, amely ✔️ azt jelzi, hogy a platform támogatott, és ❌ azt jelzi, hogy a platform nem támogatott.

Plattform	`SupportedOSPlatform(subset)`	`SupportedOSPlatform(superset)`	`UnsupportedOSPlatform(subset)`	`UnsupportedOSPlatform(superset)`
Részhalmaz	✔️	❌	✔️	❌
Szuperszett	✔️	✔️	✔️	✔️

Jótanács

Ugyanezek a szabályok vonatkoznak a SupportedOSPlatformGuard és a UnsupportedOSPlatformGuard attribútumokra is.

Az alábbi kódrészlet bemutatja, hogyan kombinálhatja az attribútumokat a megfelelő támogatási szint beállításához.

  // MacCatalyst is a superset of iOS therefore supported on iOS and MacCatalyst
  [SupportedOSPlatform("iOS")]
  public void ApiOnlySupportedOnIOSAndMacCatalyst() { }

  // Does not imply iOS, only supported on MacCatalyst
  [SupportedOSPlatform("MacCatalyst")]
  public void ApiOnlySupportedOnMacCatalyst() { }

  [SupportedOSPlatform("iOS")] // Supported on iOS and MacCatalyst
  [UnsupportedOSPlatform("MacCatalyst")] // Removes implied MacCatalyst support
  public void ApiOnlySupportedOnIos() { }

  // Unsupported on iOS and MacCatalyst
  [UnsupportedOSPlatform("iOS")]
  public void ApiUnsupportedOnIOSAndMacCatalyst();

  // Does not imply iOS, only unsupported on MacCatalyst
  [UnsupportedOSPlatform("MacCatalyst")]
  public void ApiUnsupportedOnMacCatalyst() { }

  [UnsupportedOSPlatform("iOS")] // Unsupported on iOS and MacCatalyst
  [SupportedOSPlatform("MacCatalyst")] // Removes implied MacCatalyst unsupportedness
  public void ApiUnsupportedOnIos() { }

Speciális forgatókönyvek attribútumkombinációkhoz

Ha [SupportedOSPlatform] és [UnsupportedOSPlatform] attribútumok kombinációi vannak jelen, az összes attribútum a platformazonosító szerint van csoportosítva:
- Csak támogatott lista. Ha az egyes operációsrendszer-platformok legalacsonyabb verziója egy [SupportedOSPlatform] attribútum, az API-t csak a felsorolt platformok támogatják, és az összes többi platform nem támogatja. Az egyes platformok opcionális [UnsupportedOSPlatform] attribútumai csak a minimálisan támogatott verzió magasabb verziójával rendelkezhetnek, ami azt jelzi, hogy az API a megadott verziótól kezdve el lett távolítva.
```
// API is only supported on Windows from version 6.2 to 10.0.19041.0 and all versions of Linux
// The API is considered not supported for all other platforms.
[SupportedOSPlatform("windows6.2")]
[UnsupportedOSPlatform("windows10.0.19041.0")]
[SupportedOSPlatform("linux")]
public void ApiSupportedFromWindows80SupportFromCertainVersion();
```
- Csak nem támogatott elemek listája. Ha az egyes operációsrendszer-platformok legalacsonyabb verziója egy [UnsupportedOSPlatform] attribútum, akkor az API-t csak a felsorolt platformok nem támogatják, és az összes többi platform támogatja. A lista rendelkezhet [SupportedOSPlatform] ugyanahhoz a platformhoz tartozó attribútummal, de egy magasabb verzióval, ami azt jelzi, hogy az API az adott verziótól kezdve támogatott.
```
// The API is unsupported on all Linux versions was unsupported on Windows until version 10.0.19041.0.
// The API is considered supported everywhere else without constraints.
[UnsupportedOSPlatform("windows")]
[SupportedOSPlatform("windows10.0.19041.0")]
[UnsupportedOSPlatform("linux")]
public void ApiSupportedFromWindows8UnsupportedFromWindows10();
```
- Inkonzisztens lista. Ha egyes platformok esetében [SupportedOSPlatform] a legalacsonyabb verzió, míg más platformoknál [UnsupportedOSPlatform], akkor inkonzisztensnek minősül, amit az elemző nem támogat. Inkonzisztencia esetén az elemző figyelmen kívül hagyja a [UnsupportedOSPlatform] platformokat.
  - Ha a [SupportedOSPlatform] és [UnsupportedOSPlatform] attribútumok legalacsonyabb verziói egyenlőek, akkor az elemző a platformot a csak a támogatott listára sorolja.
A platformattribútumok különböző platformnevekkel vagy -verziókkal rendelkező típusokra, tagokra (metódusokra, mezőkre, tulajdonságokra és eseményekre) és szerelvényekre alkalmazhatók.
- A felső szinten target alkalmazott attribútumok az összes tagot és típust érintik.
- A gyermekszintű attribútumok csak akkor érvényesek, ha betartják a "gyermekjegyzetek szűkíthetik a platformok támogatását, de nem szélesíthetik" szabályt.
  - Ha a szülő csak támogatott listát tartalmaz, akkor a gyermektag-attribútumok nem adhatnak hozzá új platformtámogatást, mivel az a szülőtámogatás kiterjesztését jelentené. Az új platform támogatása csak a szülőhöz adható hozzá. A gyermek azonban rendelkezhet ugyanahhoz a Supported platformhoz tartozó attribútummal a későbbi verziókkal, ami szűkíti a támogatást. Emellett a gyermek ugyanazzal a Unsupported platformmal rendelkezhet az attribútummal, mint amely a szülőtámogatást is szűkíti.
  - Ha a szülő kizárólag nem támogatott listával rendelkezik, akkor a gyermektag attribútumok támogatást adhatnak egy új platformhoz, amivel szűkítik a szülő támogatottsági körét. De nem rendelkezhet az Supported attribútummal ugyanahhoz a platformhoz, mint a szülő, mert ez kiterjeszti a szülőtámogatást. Ugyanannak a platformnak a támogatása csak az eredeti Unsupported attribútumot alkalmazó szülőhöz adható hozzá.
- Ha [SupportedOSPlatform("platformVersion")] egy azonos platform nevű API-t többször alkalmaz, az elemző csak a minimális verziójút veszi figyelembe.
- Ha [UnsupportedOSPlatform("platformVersion")] az azonos platform nevű API-k esetében több mint kétszer alkalmazzák, az elemző csak a legkorábbi verziókkal rendelkező kettőt veszi figyelembe.
Megjegyzés:

Az eredetileg támogatott, de egy későbbi verzióban nem támogatott (eltávolított) API-k várhatóan nem lesznek újra támogatottak egy még későbbi verzióban.

Példák az attribútumok működésére és az általuk előállított diagnosztikára

// An API supported only on Windows all versions.
[SupportedOSPlatform("Windows")]
public void WindowsOnlyApi() { }

// an API supported on Windows and Linux.
[SupportedOSPlatform("Windows")]
[SupportedOSPlatform("Linux")]
public void SupportedOnWindowsAndLinuxOnly() { }

// an API only supported on Windows 6.2 and later, not supported for all other.
// an API is removed/unsupported from version 10.0.19041.0.
[SupportedOSPlatform("windows6.2")]
[UnsupportedOSPlatform("windows10.0.19041.0")]
public void ApiSupportedFromWindows8UnsupportedFromWindows10() { }

// an Assembly supported on Windows, the API added from version 10.0.19041.0.
[assembly: SupportedOSPlatform("Windows")]
[SupportedOSPlatform("windows10.0.19041.0")]
public void AssemblySupportedOnWindowsApiSupportedFromWindows10() { }

public void Caller()
{
    WindowsOnlyApi(); // warns: This call site is reachable on all platforms. 'WindowsOnlyApi()' is only supported on: 'windows'

    // This call site is reachable on all platforms. 'SupportedOnWindowsAndLinuxOnly()' is only supported on: 'Windows', 'Linux'
    SupportedOnWindowsAndLinuxOnly();

    // This call site is reachable on all platforms. 'ApiSupportedFromWindows8UnsupportedFromWindows10()' is only supported on: 'windows' from version 6.2 to 10.0.19041.0
    ApiSupportedFromWindows8UnsupportedFromWindows10();

    // for same platform analyzer only warn for the latest version.
    // This call site is reachable on all platforms. 'AssemblySupportedOnWindowsApiSupportedFromWindows10()' is only supported on: 'windows' 10.0.19041.0 and later
    AssemblySupportedOnWindowsApiSupportedFromWindows10();
}

// an API not supported on android but supported on all other.
[UnsupportedOSPlatform("android")]
public void DoesNotWorkOnAndroid() { }

// an API was unsupported on Windows until version 6.2.
// The API is considered supported everywhere else without constraints.
[UnsupportedOSPlatform("windows")]
[SupportedOSPlatform("windows6.2")]
public void StartedWindowsSupportFromVersion8() { }

// an API was unsupported on Windows until version 6.2.
// Then the API is removed (unsupported) from version 10.0.19041.0.
// The API is considered supported everywhere else without constraints.
[UnsupportedOSPlatform("windows")]
[SupportedOSPlatform("windows6.2")]
[UnsupportedOSPlatform("windows10.0.19041.0")]
public void StartedWindowsSupportFrom8UnsupportedFrom10() { }

public void Caller2()
{
    DoesNotWorkOnAndroid(); // This call site is reachable on all platforms.'DoesNotWorkOnAndroid()' is unsupported on: 'android'

    // This call site is reachable on all platforms. 'StartedWindowsSupportFromVersion8()' is unsupported on: 'windows' 6.2 and before.
    StartedWindowsSupportFromVersion8();

    // This call site is reachable on all platforms. 'StartedWindowsSupportFrom8UnsupportedFrom10()' is supported on: 'windows' from version 6.2 to 10.0.19041.0
    StartedWindowsSupportFrom8UnsupportedFrom10();
}

Jelentett figyelmeztetések kezelése

A diagnosztika kezelésének ajánlott módja, hogy a megfelelő platformon való futtatáskor csak platformspecifikus API-kat hívjon meg. A következő lehetőségeket használhatja a figyelmeztetések kezelésére; válassza ki a helyzetének leginkább megfelelőt:

Őrizd meg a hívást. Ezt úgy érheti el, hogy futtatáskor feltételesen meghívja a kódot. Ellenőrizze, hogy a kívánt Platform platformon fut-e az egyik platformellenőrzési módszer, például a OperatingSystem.Is<Platform>() vagy a OperatingSystem.Is<Platform>VersionAtLeast(int major, int minor = 0, int build = 0, int revision = 0) használatával. példa.
Jelölje meg a híváswebhelyet platformspecifikusként. Dönthet úgy is, hogy a saját API-kat platformspecifikusként jelöli meg, így hatékonyan továbbítja a követelményeket a hívóknak. Jelölje meg a tartalmazó metódust vagy típust vagy a teljes szerelvényt ugyanazokkal az attribútumokkal, mint a hivatkozott platformfüggő hívás. Példák.
A hívás helyének érvényesítése platformellenőrzéssel. Ha nem szeretné, hogy futásidőben további if utasítás többletterhelése legyen, használja a következőt Debug.Assert(Boolean): példa.
Törölje a kódot. Általában nem az, amit szeretne, mert ez azt jelenti, hogy elveszíti a hűséget, amikor a kódot a Windows-felhasználók használják. Platformfüggetlen alternatíva esetén valószínűleg jobb, ha ezt platformspecifikus API-kon keresztül használja.
Tiltsa le a figyelmeztetést. A figyelmeztetést egyszerűen letilthatja egy EditorConfig bejegyzéssel vagy #pragma warning disable CA1416. Ennek a lehetőségnek azonban végső megoldásnak kell lennie platformspecifikus API-k használatakor.

Jótanács

Ha letiltja a figyelmeztetéseket az #pragma előfordítási irányelvek használatával, a megcélzott azonosítók megkülönböztetik a kis- és nagybetűket. Például ca1416 nem tiltaná le a CA1416 figyelmeztetést.

Platform-specifikus API-kat őrző metódusokkal

Az őr metódus platformnevének meg kell egyeznie a hívó platformfüggő API-platform nevével. Ha a hívó API platformsztringje tartalmazza a verziót:

Az [SupportedOSPlatform("platformVersion")] attribútum esetében a guard metódus platformjának version nagyobbnak vagy egyenlőnek kell lennie a hívó platform Version értékével.

Az [UnsupportedOSPlatform("platformVersion")] attribútum esetében a védelmi metódus platformjának version kisebbnek vagy egyenlőnek kell lennie a hívó platforméval Version.

public void CallingSupportedOnlyApis() // Allow list calls
{
    if (OperatingSystem.IsWindows())
    {
        WindowsOnlyApi(); // will not warn
    }

    if (OperatingSystem.IsLinux())
    {
        SupportedOnWindowsAndLinuxOnly(); // will not warn, within one of the supported context
    }

    // Can use &&, || logical operators to guard combined attributes
    if (OperatingSystem.IsWindowsVersionAtLeast(6, 2) && !OperatingSystem.IsWindowsVersionAtLeast(10, 0, 19041)))
    {
        ApiSupportedFromWindows8UnsupportedFromWindows10();
    }

    if (OperatingSystem.IsWindowsVersionAtLeast(10, 0, 19041, 0))
    {
        AssemblySupportedOnWindowsApiSupportedFromWindows10(); // Only need to check latest supported version
    }
}

public void CallingUnsupportedApis()
{
    if (!OperatingSystem.IsAndroid())
    {
        DoesNotWorkOnAndroid(); // will not warn
    }

    if (!OperatingSystem.IsWindows() || OperatingSystem.IsWindowsVersionAtLeast(6, 2))
    {
        StartedWindowsSupportFromVersion8(); // will not warn
    }

    if (!OperatingSystem.IsWindows() || // supported all other platforms
       (OperatingSystem.IsWindowsVersionAtLeast(6, 2) && !OperatingSystem.IsWindowsVersionAtLeast(10, 0, 19041)))
    {
        StartedWindowsSupportFrom8UnsupportedFrom10(); // will not warn
    }
}

Ha olyan kódot kell védenie, amely a netstandard vagy a netcoreapp célpontja, és ahol az új OperatingSystem API-k nem érhetők el, használhatja a RuntimeInformation.IsOSPlatform API-t, amelyet az elemző tiszteletben tart. De ez nem olyan optimalizált, mint az új API-k, amelyeket a OperatingSystem-ben adtak hozzá. Ha a platform nem támogatott a OSPlatform szerkezetben, meghívhatja OSPlatform.Create(String) és átadhatja a platform nevét, amelyet az elemző is tiszteletben tart.
```
public void CallingSupportedOnlyApis()
{
    if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
    {
        SupportedOnWindowsAndLinuxOnly(); // will not warn
    }

    if (RuntimeInformation.IsOSPlatform(OSPlatform.Create("browser")))
    {
        ApiOnlySupportedOnBrowser(); // call of browser specific API
    }
}
```

API-k annotálása platform guard attribútumokkal, és egyéni védőként való alkalmazása

Ahogy korábban már láthattuk, az elemző felismeri a platformőr statikus metódusokat a OperatingSystem típusban, például a OperatingSystem.IsWindows és a RuntimeInformation.IsOSPlatform is. Előfordulhat azonban, hogy az őrzési eredményt gyorsítótárban tárolja egy mezőben, és újra felhasználja azt, vagy egyéni őrzési módszereket alkalmaz egy platform ellenőrzésére. Az elemzőnek egyéni védőként kell felismernie az ilyen API-kat, és ne figyelmeztessen az általuk őrzött API-kra. A .NET 6-ban bevezettük a védőattribútumokat a forgatókönyv támogatásához:

SupportedOSPlatformGuardAttribute jelöli az API-kat, melyek védőként használhatók a SupportedOSPlatformAttribute-sel jegyzetelt API-khoz.
UnsupportedOSPlatformGuardAttribute jelöli az API-kat, melyek védőként használhatók a UnsupportedOSPlatformAttribute-sel jegyzetelt API-khoz.

Ezek az attribútumok opcionálisan tartalmazhatnak verziószámot. Ezek többször is alkalmazhatók több platform őrzésére, és használhatók mező, tulajdonság vagy metódus megjegyzéséhez.

class Test
{
    [UnsupportedOSPlatformGuard("browser")] // The platform guard attribute
#if TARGET_BROWSER
    internal bool IsSupported => false;
#else
    internal bool IsSupported => true;
#endif

    [UnsupportedOSPlatform("browser")]
    void ApiNotSupportedOnBrowser() { }

    void M1()
    {
        ApiNotSupportedOnBrowser();  // Warns: This call site is reachable on all platforms.'ApiNotSupportedOnBrowser()' is unsupported on: 'browser'

        if (IsSupported)
        {
            ApiNotSupportedOnBrowser();  // Not warn
        }
    }

    [SupportedOSPlatform("Windows")]
    [SupportedOSPlatform("Linux")]
    void ApiOnlyWorkOnWindowsLinux() { }

    [SupportedOSPlatformGuard("Linux")]
    [SupportedOSPlatformGuard("Windows")]
    private readonly bool _isWindowOrLinux = OperatingSystem.IsLinux() || OperatingSystem.IsWindows();

    void M2()
    {
        ApiOnlyWorkOnWindowsLinux();  // This call site is reachable on all platforms.'ApiOnlyWorkOnWindowsLinux()' is only supported on: 'Linux', 'Windows'.

        if (_isWindowOrLinux)
        {
            ApiOnlyWorkOnWindowsLinux();  // Not warn
        }
    }
}

Híváswebhely megjelölése platformspecifikusként

A platformneveknek meg kell egyeznie a hívó platformfüggetlen API-val. Ha a platform szövege tartalmaz egy verziót:

Az attribútum esetében a [SupportedOSPlatform("platformVersion")] híváshelyplatformnak version nagyobbnak vagy egyenlőnek kell lennie, mint a hívóplatform Version

Az [UnsupportedOSPlatform("platformVersion")] attribútum esetében a hívási hely platformjának version kisebbnek vagy egyenlőnek kell lennie a hívó platform Version platformjával

// an API supported only on Windows.
[SupportedOSPlatform("windows")]
public void WindowsOnlyApi() { }

// an API supported on Windows and Linux.
[SupportedOSPlatform("Windows")]
[SupportedOSPlatform("Linux")]
public void SupportedOnWindowsAndLinuxOnly() { }

// an API only supported on Windows 6.2 and later, not supported for all other.
// an API is removed/unsupported from version 10.0.19041.0.
[SupportedOSPlatform("windows6.2")]
[UnsupportedOSPlatform("windows10.0.19041.0")]
public void ApiSupportedFromWindows8UnsupportedFromWindows10() { }

// an Assembly supported on Windows, the API added from version 10.0.19041.0.
[assembly: SupportedOSPlatform("Windows")]
[SupportedOSPlatform("windows10.0.19041.0")]
public void AssemblySupportedOnWindowsApiSupportedFromWindows10() { }

[SupportedOSPlatform("windows6.2")] // call site attributed Windows 6.2 or above.
public void Caller()
{
    WindowsOnlyApi(); // will not warn as call site is for Windows.

    // will not warn as call site is for Windows all versions.
    SupportedOnWindowsAndLinuxOnly();

    // will not warn for the [SupportedOSPlatform("windows6.2")] attribute, but warns for [UnsupportedOSPlatform("windows10.0.19041.0")]
    // This call site is reachable on: 'windows' 6.2 and later. 'ApiSupportedFromWindows8UnsupportedFromWindows10()' is unsupported on: 'windows' 10.0.19041.0 and later.
    ApiSupportedFromWindows8UnsupportedFromWindows10();

    // The call site version is lower than the calling version, so warns:
    // This call site is reachable on: 'windows' 6.2 and later. 'AssemblySupportedOnWindowsApiSupportedFromWindows10()' is only supported on: 'windows' 10.0.19041.0 and later
    AssemblySupportedOnWindowsApiSupportedFromWindows10();
}

[SupportedOSPlatform("windows10.0.22000")] // call site attributed with windows 10.0.22000 or above.
public void Caller2()
{
    // This call site is reachable on: 'windows' 10.0.22000 and later. 'ApiSupportedFromWindows8UnsupportedFromWindows10()' is unsupported on: 'windows' 10.0.19041.0 and later.
    ApiSupportedFromWindows8UnsupportedFromWindows10();

    // will not warn as call site version higher than calling API.
    AssemblySupportedOnWindowsApiSupportedFromWindows10();
}

[SupportedOSPlatform("windows6.2")]
[UnsupportedOSPlatform("windows10.0.19041.0")] // call site supports Windows from version 6.2 to 10.0.19041.0.
public void Caller3()
{
    // will not warn as caller has exact same attributes.
    ApiSupportedFromWindows8UnsupportedFromWindows10();

    // The call site reachable for the version not supported in the calling API, therefore warns:
    // This call site is reachable on: 'windows' from version 6.2 to 10.0.19041.0. 'AssemblySupportedOnWindowsApiSupportedFromWindows10()' is only supported on: 'windows' 10.0.19041.0 and later.
    AssemblySupportedOnWindowsApiSupportedFromWindows10();
}

// an API not supported on Android but supported on all other.
[UnsupportedOSPlatform("android")]
public void DoesNotWorkOnAndroid() { }

// an API was unsupported on Windows until version 6.2.
// The API is considered supported everywhere else without constraints.
[UnsupportedOSPlatform("windows")]
[SupportedOSPlatform("windows6.2")]
public void StartedWindowsSupportFromVersion8() { }

// an API was unsupported on Windows until version 6.2.
// Then the API is removed (unsupported) from version 10.0.19041.0.
// The API is considered supported everywhere else without constraints.
[UnsupportedOSPlatform("windows")]
[SupportedOSPlatform("windows6.2")]
[UnsupportedOSPlatform("windows10.0.19041.0")]
public void StartedWindowsSupportFrom8UnsupportedFrom10() { }

[UnsupportedOSPlatform("windows")] // Caller no support Windows for any version.
public void Caller4()
{
    // This call site is reachable on all platforms.'DoesNotWorkOnAndroid()' is unsupported on: 'android'
    DoesNotWorkOnAndroid();

    // will not warns as the call site not support Windows at all, but supports all other.
    StartedWindowsSupportFromVersion8();

    // same, will not warns as the call site not support Windows at all, but supports all other.
    StartedWindowsSupportFrom8UnsupportedFrom10();
}

[UnsupportedOSPlatform("windows")]
[UnsupportedOSPlatform("android")] // Caller not support Windows and Android for any version.
public void Caller4()
{
    DoesNotWorkOnAndroid(); // will not warn as call site not supports Android.

    // will not warns as the call site not support Windows at all, but supports all other.
    StartedWindowsSupportFromVersion8();

    // same, will not warns as the call site not support Windows at all, but supports all other.
    StartedWindowsSupportFrom8UnsupportedFrom10();
}

A híváshely érvényesítése platformellenőrzéssel

A platform őrző példákban használt összes feltételes ellenőrzés használható feltételként Debug.Assert(Boolean)-hez is.

// An API supported only on Linux.
[SupportedOSPlatform("linux")]
public void LinuxOnlyApi() { }

public void Caller()
{
    Debug.Assert(OperatingSystem.IsLinux());

    LinuxOnlyApi(); // will not warn
}