Adaptieve versiecode

U kunt denken aan het schrijven van adaptieve code op dezelfde manier als het maken van een adaptieve gebruikersinterface. Ontwerp uw basiscode om uit te voeren op de laagste versie van het besturingssysteem en voeg vervolgens functies toe wanneer u detecteert dat uw app wordt uitgevoerd op een hogere versie waar een nieuwe functie beschikbaar is.

Zie ApiInformation voor achtergrondinformatie over API-contracten en het configureren van Visual Studio.

Prerequisites

  • Een Windows App SDK project (verpakt of uitgepakt). Zie Snel aan de slag: uw eerste WinUI 3-app maken.
  • Bekendheid met het Windows Runtime -typesysteem (WinRT), omdat ApiInformation controles alleen van toepassing zijn op Windows.* naamruimtetypen.

controles van de Runtime API

Gebruik de Windows. Foundation.Metadata.ApiInformation-klasse in een voorwaarde in uw code om te testen op de aanwezigheid van de API die u wilt aanroepen. Deze voorwaarde wordt overal geëvalueerd waar uw app wordt uitgevoerd, maar resulteert alleen in true op apparaten waarop de API aanwezig is en kan worden aangeroepen.

Important

ApiInformationcontroles werken alleen voor typen van Windows Runtime in de naamruimte Windows.*. Ze detecteren geen WinUI-typen (Microsoft.UI.Xaml.*) omdat deze typen deel uitmaken van het Windows App SDK framework-pakket, niet het besturingssysteem en niet zijn geregistreerd als WinRT-metagegevens die ApiInformation query's kunnen uitvoeren. #if preprocessorrichtlijnen helpen hier ook niet: ze worden geëvalueerd tijdens het compileren op basis van het doelframework, niet tijdens runtime op basis van de besturingssysteem- of SDK-versie waarop de app daadwerkelijk wordt uitgevoerd. Als u een WinUI-functie voorwaardelijk wilt oplichten, controleert u de Windows App SDK versie waarop uw app is gebouwd (zie adaptieve versie-apps) of verpakt u de aanroep in een try/catch en valt u terug als deze tijdens runtime mislukt.

Tip

Talloze runtime-API-controles kunnen van invloed zijn op de prestaties van uw app. Voer de controle eenmaal uit en sla het resultaat in de cache op en gebruik vervolgens het resultaat in de cache in uw app.

Aanpasbare codeopties

Er zijn twee manieren om adaptieve code te maken:

  • App-code : gebruik runtime-API-controles in code achter. Dit is de aanbevolen benadering voor de meeste scenario's.
  • Statustriggers : gebruik uitbreidbare statustriggers die visuele statussen activeren op basis van de aanwezigheid van een API. Gebruik statustriggers wanneer u een eenvoudige eigenschap of opsommingswijziging hebt tussen besturingssysteemversies die zijn verbonden met een visuele status.

Voorbeeld: Controleren op een enumwaarde

In dit voorbeeld ziet u hoe u kunt controleren of een specifieke enumwaarde aanwezig is voordat u deze gebruikt. Als de waarde niet aanwezig is, valt de code terug op een alternatief. EnergySaverStatus en PowerManager zijn echte Windows Runtime-types in de naamruimte Windows.System.Power, zodat ApiInformation ze correct kan opvragen.

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

Wanneer u het resultaat van een API-controle in de cache opscachet, gebruikt u die waarde in de cache consistent in uw app. Herhaal de controle niet op meerdere plaatsen: controleer het eenmaal, sla het resultaat op en verwijs ernaar overal.

Voorbeeld: Controleren of er een methode is

Gebruik IsMethodPresent dit om te controleren of een specifieke methode beschikbaar is voordat u deze aanroept:

DisplayRequest displayRequest = new DisplayRequest();

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

Voorbeeld: Controleren op een eigenschap

Gebruik IsPropertyPresent dit om te controleren of een specifieke eigenschap beschikbaar is voordat u deze leest:

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

Aanbevolen procedures

Practice Begeleiding
Statische tekenreeksen gebruiken Wanneer u API-namen controleert metApiInformation, gebruikt u in code vastgelegde tekenreeksen in plaats van .NET reflectie om problemen met het laden van runtimetypen te voorkomen
Cacheresultaten Elke API-controle eenmaal uitvoeren bij het opstarten en het resultaat opslaan voor hergebruik
Minimale versie laag houden Stel de minimale versie van uw project zo laag mogelijk in om de breedste doelgroep te bereiken en gebruik adaptieve code om functies op nieuwere besturingssysteemversies te verlichten
Testen op minimale versie Test altijd op de minimaal ondersteunde versie van het besturingssysteem om te controleren of terugvalpaden correct werken

Verwante onderwerpen

  • Last updated on