Versionsanpassad kod

Du kan tänka dig att skriva anpassningsbar kod på samma sätt som du tänker på att skapa ett anpassningsbart användargränssnitt. Utforma baskoden så att den körs på den lägsta operativsystemversionen och lägg sedan till funktioner när du upptäcker att din app körs på en högre version där en ny funktion är tillgänglig.

Bakgrundsinformation om ApiInformation, API-kontrakt och konfiguration av Visual Studio finns i Version av anpassningsbara appar.

Förutsättningar

  • Ett Windows App SDK projekt (paketerat eller uppackat). Se Snabbstart: Skapa din första WinUI 3-app.
  • Kunskaper om systemet av typen Windows Runtime (WinRT), eftersom ApiInformation kontroller endast gäller för Windows.* namnområdestyper.

API-kontroller vid körning

Använd klassen Windows.Foundation.Metadata.ApiInformation i ett villkor i din kod för att testa om det API du vill anropa finns. Det här villkoret utvärderas var din app än körs, men utvärderas till true endast på enheter där API:et finns och är tillgängligt att anropa.

Important

ApiInformation kontroller fungerar endast för Windows Runtime-typer i Windows.* namnrymden. De identifierar inte WinUI-typer (Microsoft.UI.Xaml.*) eftersom dessa typer är en del av Windows App SDK-ramverkspaketet, inte operativsystemet, och är inte registrerade som WinRT-metadata som ApiInformation kan fråga. #if preprocessor-direktiv hjälper inte här heller – de utvärderas vid kompileringstid baserat på målramverk, inte vid körning baserat på operativsystemet eller SDK-versionen som appen faktiskt körs på. Om du vill aktivera en WinUI-funktion villkorligt kontrollerar du vilken version av Windows App SDK appen byggdes mot (se versionsanpassade appar), eller omger anropet med ett try/catch-block och använder en reservlösning om det misslyckas vid körning.

Tip

Många API-kontroller vid körning kan påverka appens prestanda. Utför kontrollen en gång och lagra resultatet i cache, och använd sedan det cachelagrade resultatet i hela appen.

Anpassningsbara kodalternativ

Det finns två sätt att skapa anpassningsbar kod:

  • Appkod – Använd körnings-API-kontroller i koden bakom. Detta är den rekommenderade metoden för de flesta scenarier.
  • Tillståndsutlösare – Använd utökningsbara tillståndsutlösare som aktiverar visuella tillstånd baserat på förekomsten av ett API. Använd tillståndsutlösare när du har en enkel ändring av en egenskap eller uppräkningstyp mellan OS-versioner som är kopplad till ett visuellt tillstånd.

Exempel: Kontrollera om det finns ett enum-värde

Det här exemplet visar hur du kontrollerar om ett visst uppräkningsvärde finns innan du använder det. Om värdet inte finns, återgår koden till ett alternativ. EnergySaverStatus och PowerManager är äkta Windows Runtime-typer i namnområdet Windows.System.Power, så ApiInformation kan fråga om dem korrekt.

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

När du cachelagr resultatet av en API-kontroll använder du det cachelagrade värdet konsekvent i hela appen. Upprepa inte kontrollen på flera platser – kontrollera en gång, lagra resultatet och referera till det överallt.

Exempel: Sök efter en metod

Använd IsMethodPresent för att kontrollera att en specifik metod är tillgänglig innan du anropar den:

DisplayRequest displayRequest = new DisplayRequest();

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

Exempel: Sök efter en egenskap

Använd IsPropertyPresent för att kontrollera att en specifik egenskap är tillgänglig innan du läser den:

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

Metodtips

Practice Guidance
Använda statiska strängar När du kontrollerar API-namn med ApiInformation använder du hårdkodade strängar i stället för .NET-reflektion för att undvika problem med typinläsning vid körning
Cacheresultat Utför varje API-kontroll en gång vid start och lagra resultatet för återanvändning
Håll lägsta version låg Ställ in projektets lägsta version så lågt som praktiskt för att nå den bredaste målgruppen och använd anpassningsbar kod för att lysa upp funktioner i nyare OS-versioner
Testa på lägsta version Testa alltid den lägsta version av operativsystemet som stöds för att kontrollera att återställningsvägarna fungerar korrekt

Relaterat innehåll

  • Last updated on