Codice adattivo alla versione

È possibile pensare alla scrittura di codice adattivo in modo analogo a come si pensa alla creazione di un'interfaccia utente adattiva. Progettare il codice di base per l'esecuzione nella versione più bassa del sistema operativo e quindi aggiungere funzionalità quando si rileva che l'app viene eseguita in una versione successiva in cui è disponibile una nuova funzionalità.

Per informazioni di base su ApiInformation, i contratti API e la configurazione di Visual Studio, vedere App adattive alla versione.

Prerequisiti

  • Un progetto SDK per app di Windows (pacchettizzato o non pacchettizzato). Vedi Avvio rapido: Creare la prima app WinUI 3.
  • Conoscenza del sistema di tipi di Windows Runtime (WinRT), poiché i controlli ApiInformation si applicano solo ai tipi del namespace Windows.*.

Controlli dell'API di runtime

Usa la classe Windows.Foundation.Metadata.ApiInformation in una condizione del codice per verificare la presenza dell'API che vuoi chiamare. Questa condizione viene valutata ovunque venga eseguita l'app, ma restituisce true solo nei dispositivi in cui l'API è presente e disponibile per chiamare.

Importante

ApiInformationcontrolla il funzionamento solo per i tipi Windows Runtime nello spazio dei Windows.* nomi. Non rilevano i tipi WinUI (Microsoft.UI.Xaml.*) perché questi tipi fanno parte del pacchetto framework di SDK per app di Windows, non del sistema operativo e non sono registrati come metadati WinRT che ApiInformation possono eseguire query. #if Le direttive del preprocessore non sono utili in questo caso, ma vengono valutate in fase di compilazione in base al framework di destinazione, non in fase di esecuzione in base alla versione del sistema operativo o dell'SDK in cui l'app è effettivamente in esecuzione. Per abilitare in modo condizionale una funzionalità di WinUI, verifica la versione di SDK per app di Windows con cui l'app è stata compilata (vedi App adattive alla versione) oppure racchiudi la chiamata in un blocco try/catch e usa una soluzione di fallback se non riesce in fase di esecuzione.

Tip

Numerosi controlli api di runtime possono influire sulle prestazioni dell'app. Eseguire il controllo una volta e memorizzare nella cache il risultato, quindi usare il risultato memorizzato nella cache nell'intera app.

Opzioni del codice adattivo

Esistono due modi per creare codice adattivo:

  • Codice dell'app — Usa i controlli API in fase di esecuzione nel codice sottostante. Questo è l'approccio consigliato per la maggior parte degli scenari.
  • Trigger di stato — Usa trigger di stato estendibili che attivano stati visivi in base alla presenza di un'API. Usa i trigger di stato quando tra le versioni del sistema operativo si verifica una semplice modifica di una proprietà o di un valore enum associata a uno stato visivo.

Esempio: Verificare se è presente un valore enum

In questo esempio viene illustrato come verificare se è presente un valore di enumerazione specifico prima di usarlo. Se il valore non è presente, il codice restituisce un'alternativa. EnergySaverStatus e PowerManager sono tipi Windows Runtime effettivi nel namespace Windows.System.Power, quindi ApiInformation può interrogarli correttamente.

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.
}

Importante

Quando si memorizza nella cache il risultato di un controllo API, usare il valore memorizzato nella cache in modo coerente nell'intera app. Non ripetere il controllo in più posizioni: controllare una sola volta, archiviare il risultato e farvi riferimento ovunque.

Esempio: Verificare la presenza di un metodo

Usare IsMethodPresent per verificare che un metodo specifico sia disponibile prima di chiamarlo:

DisplayRequest displayRequest = new DisplayRequest();

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

Esempio: Verificare la presenza di una proprietà

Usare IsPropertyPresent per verificare che una proprietà specifica sia disponibile prima di leggerla:

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

Procedure consigliate

Pratica Guidance
Usare stringhe statiche Quando si verificano i nomi delle API con ApiInformation, usare stringhe codificate anziché la reflection di .NET per evitare problemi di caricamento dei tipi in fase di esecuzione
Risultati della cache Eseguire ogni controllo API una sola volta all'avvio e archiviare il risultato per il riutilizzo
Mantenere bassa la versione minima Imposta la versione minima del progetto al livello più basso possibile per raggiungere il pubblico più ampio e usa codice adattivo per abilitare le funzionalità sulle versioni più recenti del sistema operativo
Testare la versione minima Testare sempre la versione minima supportata del sistema operativo per verificare che i percorsi di fallback funzionino correttamente

Contenuti correlati

  • Last updated on