Adaptivní kód verze

Můžete přemýšlet o psaní adaptivního kódu podobně jako při vytváření adaptivního uživatelského rozhraní. Navrhněte základní kód tak, aby běžel na nejnižší verzi operačního systému, a potom přidejte funkce, když zjistíte, že vaše aplikace běží na vyšší verzi, kde je k dispozici nová funkce.

Základní informace o ApiInformationkontraktech rozhraní API a konfiguraci Visual Studio najdete v tématu Adaptivní aplikace pro verze.

Předpoklady

  • Projekt Windows App SDK (zabalený nebo rozbalený). Viz Rychlý start: Vytvoření první aplikace WinUI 3.
  • Znalost systému typů prostředí Windows Runtime (WinRT), protože kontroly ApiInformation platí pouze pro typy v oboru názvů Windows.*.

Kontroly rozhraní API za běhu

Použijte třídu Windows.Foundation.Metadata.ApiInformation v podmínce ve svém kódu k ověření dostupnosti rozhraní API, které chcete volat. Tato podmínka se vyhodnocuje všude, kde je vaše aplikace spuštěná, ale jako true se vyhodnotí pouze na zařízeních, na kterých je rozhraní API přítomné a dostupné pro volání.

Important

Kontroly ApiInformation fungují pouze pro typy prostředí Windows Runtime v oboru názvů Windows.*. Nerozpoznávají typy WinUI (Microsoft.UI.Xaml.*), protože tyto typy jsou součástí balíčku rozhraní Windows App SDK, nikoli operačního systému, a nejsou zaregistrované jako metadata WinRT, která ApiInformation mohou dotazovat. #if Direktivy preprocesoru zde ani nepomáhají – vyhodnocují se v době kompilace na základě cílové architektury, nikoli za běhu na základě verze operačního systému nebo sady SDK, na které aplikace skutečně běží. Chcete-li podmíněně zpřístupnit funkci WinUI, zkontrolujte verzi sady Windows App SDK, vůči které byla vaše aplikace sestavena (viz Aplikace adaptivní vůči verzím), nebo obalte volání blokem try/catch a pokud za běhu selže, použijte náhradní řešení.

Tip

Na výkon vaší aplikace může mít vliv celá řada kontrol rozhraní API modulu runtime. Proveďte kontrolu jednou a vložte výsledek do mezipaměti a pak použijte výsledek uložený v mezipaměti v celé aplikaci.

Adaptivní možnosti kódu

Adaptivní kód můžete vytvořit dvěma způsoby:

  • Kód aplikace – Používejte kontroly rozhraní API modulu runtime v kódu za sebou. Tento přístup se doporučuje pro většinu scénářů.
  • Spouštěče stavů – Použijte rozšiřitelné spouštěče stavů, které aktivují vizuální stavy na základě dostupnosti rozhraní API. Triggery stavu použijte, pokud mezi verzemi operačního systému dochází k jednoduché změně vlastnosti nebo hodnoty výčtu, která souvisí s vizuálním stavem.

Příklad: Ověření hodnoty výčtu

Tento příklad ukazuje, jak před použitím zkontrolovat, jestli je k dispozici konkrétní hodnota výčtu. Pokud hodnota není k dispozici, kód se vrátí na alternativu. EnergySaverStatus a PowerManager jsou skutečné typy prostředí Windows Runtime v oboru názvů Windows.System.Power, takže ApiInformation je může správně dotazovat.

if (ApiInformation.IsEnumNamedValuePresent(
    "Windows.System.Power.EnergySaverStatus", "On"))
{
    if (PowerManager.EnergySaverStatus == EnergySaverStatus.On)
    {
        // Reduce background work to save battery.
        ReduceBackgroundActivity();
    }
}
else
{
    // Energy Saver status isn't available on this OS version; skip the check.
}

void ReduceBackgroundActivity()
{
    // Pause non-essential timers, syncs, and animations here.
}

Important

Když výsledek kontroly rozhraní API ukládáte do mezipaměti, použijte tuto hodnotu v mezipaměti konzistentně v celé aplikaci. Neopakujte kontrolu na více místech – zkontrolujte ji jednou, uložte výsledek a používejte jej všude.

Příklad: Kontrola metody

Pomocí IsMethodPresent ověřte, že je určitá metoda k dispozici, než ji zavoláte:

DisplayRequest displayRequest = new DisplayRequest();

if (ApiInformation.IsMethodPresent(
    "Windows.System.Display.DisplayRequest", "RequestActive"))
{
    displayRequest.RequestActive();
}

Příklad: Ověření vlastnosti

Pomocí IsPropertyPresent ověřte, zda je konkrétní vlastnost k dispozici, než ji začnete číst:

if (ApiInformation.IsPropertyPresent(
    "Windows.System.Power.PowerManager", "RemainingChargePercent"))
{
    int chargePercent = PowerManager.RemainingChargePercent;
}

Osvědčené postupy

Practice Guidance
Použití statických řetězců Při kontrole názvů API pomocí ApiInformation používejte místo reflexe v .NET pevně zadané řetězce, abyste se vyhnuli problémům s načítáním typů za běhu.
Výsledky ukládání do mezipaměti Proveďte každou kontrolu rozhraní API jednou při spuštění a uložte výsledek pro opakované použití.
Udržujte minimální verzi co nejnižší Nastavte minimální verzi projektu co nejníže, jak je to praktické, abyste oslovili co nejširší okruh uživatelů, a pomocí adaptivního kódu zpřístupněte funkce v novějších verzích OS.
Testování minimální verze Vždy otestujte minimální podporovanou verzi operačního systému a ověřte, že náhradní cesty fungují správně.

Související obsah

  • Last updated on