Code adaptatif de version

Vous pouvez réfléchir à l’écriture de code adaptatif de la même façon que la création d’une interface utilisateur adaptative. Concevez votre code de base pour qu’il s’exécute sur la version la plus basse du système d’exploitation, puis ajoutez des fonctionnalités lorsque vous détectez que votre application s’exécute sur une version supérieure où une nouvelle fonctionnalité est disponible.

Pour plus d’informations sur ApiInformationles contrats API et la configuration de Visual Studio, consultez Applications adaptatives de version.

Prerequisites

  • Un projet SDK d'application Windows (empaqueté ou non empaqueté). Consultez démarrage rapide : Créer votre première application WinUI 3.
  • Une bonne connaissance du système de types de Windows Runtime (WinRT), car les vérifications ApiInformation s’appliquent uniquement aux types de l’espace de noms Windows.*.

Vérifications de l’API runtime

Utilisez la classe Windows.Foundation.Metadata.ApiInformation dans une condition de votre code pour vérifier la présence de l’API que vous souhaitez appeler. Cette condition est évaluée partout où votre application s’exécute, mais elle ne prend la valeur true que sur les appareils où l’API est présente et peut être appelée.

Important

ApiInformation les vérifications fonctionnent uniquement pour les types Windows Runtime dans l’espace de noms Windows.*. Ils ne détectent pas les types WinUI (Microsoft.UI.Xaml.*) car ces types font partie du package d'infrastructure SDK d'application Windows, et non le système d'exploitation et ne sont pas inscrits en tant que métadonnées WinRT qui ApiInformation peuvent interroger. #if Les directives de préprocesseur n’aident pas non plus ici : elles sont évaluées au moment de la compilation en fonction de l’infrastructure cible, et non au moment de l’exécution en fonction de la version du système d’exploitation ou du SDK sur laquelle l’application s’exécute réellement. Pour allumer une fonctionnalité WinUI de manière conditionnelle, vérifiez la version de SDK d'application Windows sur laquelle votre application a été générée (voir Applications adaptatives de version) ou mettez à jour l’appel dans un essai/catch et revenez en arrière en cas d’échec au moment de l’exécution.

Tip

De nombreuses vérifications d’API runtime peuvent affecter les performances de votre application. Effectuez la vérification une fois et cachez le résultat, puis utilisez le résultat mis en cache dans votre application.

Options de code adaptatif

Il existe deux façons de créer du code adaptatif :

  • Code d’application — utilisez les vérifications de l’API d’exécution dans le code associé. Il s’agit de l’approche recommandée pour la plupart des scénarios.
  • Déclencheurs d’état : utilisez des déclencheurs d’état extensibles qui activent des états visuels en fonction de la présence d’une API. Utilisez des déclencheurs d’état lorsque vous avez une propriété ou une modification d’énumération simple entre les versions du système d’exploitation connectées à un état visuel.

Exemple : Vérifier une valeur d’énumération

Cet exemple montre comment vérifier si une valeur d’énumération spécifique est présente avant de l’utiliser. Si la valeur n’est pas présente, le code revient à une alternative. EnergySaverStatus et PowerManager sont de véritables types Windows Runtime dans l’espace de noms Windows.System.Power, de sorte que ApiInformation peut les interroger correctement.

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

Lorsque vous cachez le résultat d’une vérification d’API, utilisez cette valeur mise en cache de manière cohérente dans votre application. Ne répétez pas l’enregistrement à plusieurs endroits : vérifiez une fois, stockez le résultat et référencez-le partout.

Exemple : Rechercher une méthode

Permet IsMethodPresent de vérifier qu’une méthode spécifique est disponible avant de l’appeler :

DisplayRequest displayRequest = new DisplayRequest();

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

Exemple : Vérifier la présence d’une propriété

Permet IsPropertyPresent de vérifier qu’une propriété spécifique est disponible avant de la lire :

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

Bonnes pratiques

Pratique Conseils
Utiliser des chaînes statiques Lors de la vérification des noms d’API avec ApiInformation, utilisez des chaînes codées en dur plutôt que la réflexion .NET afin d’éviter les problèmes de chargement de types à l’exécution
Résultats du cache Effectuer chaque vérification d’API une fois au démarrage et stocker le résultat pour la réutilisation
Maintenir une version minimale basse Définissez la version minimale de votre projet aussi faible que pratique pour atteindre le public le plus large et utilisez du code adaptatif pour éclairer les fonctionnalités sur les versions plus récentes du système d’exploitation
Test sur la version minimale Testez toujours sur la version minimale prise en charge du système d’exploitation pour vérifier que les chemins de secours fonctionnent correctement

Contenu connexe

  • Last updated on