Kod adaptacyjny wersji

Możesz myśleć o pisaniu kodu adaptacyjnego w podobny sposób, jak myślisz o tworzeniu adaptacyjnego interfejsu użytkownika. Zaprojektuj kod podstawowy, aby działał w najniższej wersji systemu operacyjnego, a następnie dodaj funkcje po wykryciu, że aplikacja działa w nowszej wersji, w której jest dostępna nowa funkcja.

Aby uzyskać informacje ogólne na temat ApiInformation, kontraktów interfejsu API i konfigurowania programu Visual Studio, zobacz Aplikacje adaptacyjne względem wersji.

Wymagania wstępne

  • Projekt Zestaw SDK do aplikacji systemu Windows (spakowany lub rozpakowany). Zobacz Szybki start: tworzenie pierwszej aplikacji WinUI 3.
  • Znajomość systemu typów środowisko wykonawcze systemu Windows (WinRT), ponieważ sprawdzenia ApiInformation dotyczą wyłącznie typów z przestrzeni nazw Windows.*.

Kontrole API środowiska uruchomieniowego

Użyj klasy Windows.Foundation.Metadata.ApiInformation w warunku w kodzie, aby sprawdzić dostępność interfejsu API, które chcesz wywołać. Ten warunek jest oceniany wszędzie tam, gdzie aplikacja działa, ale ocenia wartość true tylko na urządzeniach, na których jest obecny interfejs API i jest dostępny do wywołania.

Ważna

ApiInformation Kontrole działają tylko dla typów środowiska środowisko wykonawcze systemu Windows w przestrzeni nazw Windows.*. Nie wykrywają typów WinUI (Microsoft.UI.Xaml.*), ponieważ te typy są częścią pakietu platformy Zestaw SDK do aplikacji systemu Windows, a nie systemu operacyjnego i nie są zarejestrowane jako metadane WinRT, które ApiInformation mogą wykonywać zapytania. #if Dyrektywy preprocesora nie pomagają w tym miejscu — są one oceniane w czasie kompilacji na podstawie platformy docelowej, a nie w czasie wykonywania na podstawie wersji systemu operacyjnego lub zestawu SDK, na której aplikacja jest rzeczywiście uruchomiona. Aby warunkowo włączyć funkcję WinUI, sprawdź, względem której wersji pakietu Zestaw SDK do aplikacji systemu Windows skompilowano aplikację (zobacz Aplikacje adaptacyjne względem wersji), lub umieść wywołanie w bloku try/catch i zastosuj mechanizm awaryjny, jeśli zakończy się ono niepowodzeniem w czasie wykonywania.

Wskazówka

Liczne kontrole interfejsu API środowiska uruchomieniowego mogą wpływać na wydajność Twojej aplikacji. Przeprowadź sprawdzanie raz i buforuj wynik, a następnie użyj buforowanego wyniku w całej aplikacji.

Opcje kodu adaptacyjnego

Istnieją dwa sposoby tworzenia kodu adaptacyjnego:

  • Kod aplikacji — użyj kontroli interfejsu API środowiska uruchomieniowego w kodzie. Jest to zalecane podejście dla większości scenariuszy.
  • Wyzwalacze stanu — Używaj rozszerzalnych wyzwalaczy stanu, które aktywują stany wizualne w zależności od dostępności interfejsu API. Użyj wyzwalaczy stanu, jeśli między wersjami systemu operacyjnego występuje prosta zmiana właściwości lub wartości typu wyliczeniowego powiązana ze stanem wizualnym.

Przykład: Sprawdzanie wartości typu wyliczeniowego

W tym przykładzie pokazano, jak sprawdzić, czy określona wartość typu wyliczeniowego występuje przed jej użyciem. Jeśli wartość nie jest obecna, kod wraca do alternatywy. EnergySaverStatus i PowerManager są rzeczywistymi typami środowiska środowisko wykonawcze systemu Windows w przestrzeni nazw Windows.System.Power, więc ApiInformation może poprawnie je odpytywać.

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

Ważna

Gdy buforujesz wynik sprawdzania interfejsu API, użyj tej buforowanej wartości spójnie w całej aplikacji. Nie powtarzaj tego samego sprawdzenia w wielu miejscach — sprawdź to raz, zapisz wynik i odwołuj się do niego wszędzie.

Przykład: sprawdź, czy istnieje metoda

Użyj IsMethodPresent polecenia , aby sprawdzić, czy określona metoda jest dostępna przed wywołaniem:

DisplayRequest displayRequest = new DisplayRequest();

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

Przykład: Sprawdzanie właściwości

Użyj IsPropertyPresent, aby sprawdzić, czy określona właściwość jest dostępna, zanim ją odczytasz:

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

Najlepsze praktyki

Practice Guidance
Używanie ciągów statycznych Podczas sprawdzania nazw interfejsów API w programie ApiInformationnależy używać ciągów zakodowanych w kodzie, a nie .NET odbicia, aby uniknąć problemów z ładowaniem typu środowiska uruchomieniowego
Buforowanie wyników Wykonaj każdą kontrolę interfejsu API raz podczas uruchamiania i zapisz wynik do ponownego użycia
Utrzymuj minimalną wersję Ustaw minimalną wersję projektu na możliwie najniższą praktyczną, aby dotrzeć do jak najszerszego grona odbiorców, i stosuj kod adaptacyjny, aby udostępniać funkcje w nowszych wersjach systemu operacyjnego
Testowanie minimalnej wersji Zawsze testuj minimalną obsługiwaną wersję systemu operacyjnego, aby sprawdzić, czy ścieżki powrotu działają prawidłowo

Treści powiązane

  • Last updated on