Udostępnij za pośrednictwem

Aplikacje adaptacyjne wersji: używanie nowych interfejsów API przy zachowaniu zgodności z poprzednimi wersjami

Każda wersja zestawu SDK Windows 10 dodaje ekscytujące nowe funkcje, które warto wykorzystać. Jednak nie wszyscy klienci zaktualizują swoje urządzenia do najnowszej wersji Windows 10 jednocześnie i chcesz upewnić się, że aplikacja działa na najszerszym możliwym zakresie urządzeń. W tym miejscu pokazano, jak zaprojektować aplikację tak, aby była uruchamiana we wcześniejszych wersjach Windows 10, ale także korzysta z nowych funkcji, gdy aplikacja działa na urządzeniu z zainstalowaną najnowszą aktualizacją.

Aby upewnić się, że aplikacja obsługuje najszerszy zakres urządzeń Windows 10, należy wykonać 3 kroki.

  • Najpierw skonfiguruj projekt Visual Studio, aby był przeznaczony dla najnowszych interfejsów API. Ma to wpływ na to, co się stanie podczas kompilowania aplikacji.
  • Po drugie, przeprowadzaj kontrole w czasie wykonywania, aby upewnić się, że wywołujesz tylko te interfejsy API, które są dostępne na urządzeniu, na którym działa Twoja aplikacja.
  • Po trzecie przetestuj aplikację w wersji minimalnej i wersji docelowej Windows 10.

Konfigurowanie projektu Visual Studio

Pierwszym krokiem obsługi wielu wersji Windows 10 jest określenie Target i Minimum obsługiwanych wersji systemu operacyjnego/zestawu SDK w projekcie Visual Studio.

  • Target: wersja zestawu SDK, którą Visual Studio kompiluje kod aplikacji i uruchamia wszystkie narzędzia w odniesieniu do tego kodu. Wszystkie interfejsy API i zasoby w tej wersji zestawu SDK są dostępne w kodzie aplikacji w czasie kompilacji.
  • Minimum: wersja zestawu SDK obsługująca najwcześniejszą wersję systemu operacyjnego, na którym może działać Twoja aplikacja (i zostanie wdrożona przez sklep), a także wersja, wobec której Visual Studio kompiluje kod znaczników aplikacji.

W czasie wykonywania aplikacja zostanie uruchomiona w wersji systemu operacyjnego, do której jest wdrożona, dlatego aplikacja zgłosi wyjątki, jeśli używasz zasobów lub wywołasz interfejsy API, które nie są dostępne w tej wersji. W dalszej części tego artykułu pokazano, jak używać kontroli środowiska uruchomieniowego w celu wywołania poprawnych interfejsów API.

Ustawienia Docelowe i Minimalne określają końce zakresu wersji systemu operacyjnego/zestawu SDK. Jeśli jednak przetestujesz aplikację w minimalnej wersji, możesz mieć pewność, że będzie ona działać we wszystkich wersjach między wartościami Minimum i Target.

Wskazówka

Visual Studio nie ostrzega o zgodności interfejsu API. Twoim zadaniem jest przetestowanie i upewnienie się, że aplikacja działa zgodnie z oczekiwaniami na wszystkich wersjach systemu operacyjnego, począwszy od wersji minimalnej aż do wersji docelowej włącznie.

Podczas tworzenia nowego projektu w wersji Visual Studio 2015, Update 2 lub nowszej zostanie wyświetlony monit o ustawienie wersji Docelowej i Minimalnej obsługiwanej przez aplikację. Domyślnie wersja docelowa to najwyższa zainstalowana wersja zestawu SDK, a minimalna wersja to najniższa zainstalowana wersja zestawu SDK. Możesz wybrać opcję Target i Minimum tylko z wersji zestawu SDK zainstalowanych na komputerze.

Ustaw docelowy zestaw SDK w Visual Studio

Zazwyczaj zalecamy pozostawienie wartości domyślnych. Jeśli jednak masz zainstalowaną wersję zapoznawcza zestawu SDK i piszesz kod produkcyjny, zmień wersję docelową z zestawu SDK w wersji zapoznawczej na najnowszą oficjalną wersję zestawu SDK.

Aby zmienić minimalną i docelową wersję projektu, który został już utworzony w Visual Studio, przejdź do Projekt -> Właściwości -> karta Aplikacja -> Ustawienia wersji docelowej.

Zmień docelowy zestaw SDK w Visual Studio

W poniższej tabeli przedstawiono numery kompilacji dla każdego zestawu SDK.

Przyjazna nazwa Wersja Kompilacja systemu operacyjnego/zestawu SDK
RTM 1507 10240
Aktualizacja listopada 1511 10586
Rocznicowa aktualizacja 1607 14393
Aktualizacja dla twórców 1703 15063
Fall Creators Update 1709 16299
Aktualizacja z kwietnia 2018 r. 1803 17134
Aktualizacja z października 2018 r. 1809 17763
Aktualizacja z maja 2019 r. 1903 18362

Możesz pobrać dowolną wydaną wersję zestawu SDK z archiwum Windows SDK i emulatora. Najnowszą Windows insider Preview SDK możesz pobrać z sekcji deweloperów witryny Windows Insider.

Aby uzyskać więcej informacji na temat aktualizacji Windows 10, zobacz informacje o wydaniu Windows 10. Aby uzyskać ważne informacje na temat cyklu życia wsparcia Windows 10, zobacz arkusz informacyjny cyklu życia Windows.

Przeprowadzanie kontroli interfejsu API

Kluczem do działania aplikacji dostosowujących się do wersji jest kombinacja kontraktów API i klasy ApiInformation. Ta klasa umożliwia wykrywanie, czy określony kontrakt interfejsu API, typ lub element członkowski jest obecny, dzięki czemu można bezpiecznie wykonywać wywołania interfejsu API w różnych urządzeniach i wersjach systemu operacyjnego.

Umowy API

Zestaw interfejsów API w rodzinie urządzeń jest podzielony na podpodziały znane jako kontrakty interfejsu API. Aby przetestować obecność kontraktu interfejsu API, możesz użyć metody ApiInformation.IsApiContractPresent . Jest to przydatne, jeśli chcesz przetestować obecność wielu interfejsów API, które istnieją w tej samej wersji kontraktu interfejsu API.

    bool isScannerDeviceContract_1_Present =
        Windows.Foundation.Metadata.ApiInformation.IsApiContractPresent
            ("Windows.Devices.Scanners.ScannerDeviceContract", 1);

Co to jest kontrakt interfejsu API? Zasadniczo kontrakt interfejsu API reprezentuje funkcję — zestaw powiązanych interfejsów API, które razem zapewniają określone funkcje. Hipotetyczny kontrakt API może odzwierciedlać zestaw interfejsów i klas API, zawierający dwie klasy, pięć interfejsów, jedną strukturę, dwa wyliczenia (enum) itd.

Logicznie powiązane typy są grupowane w kontrakt interfejsu API, a począwszy od Windows 10, każdy interfejs API Windows Runtime jest członkiem niektórych kontraktów interfejsu API. W przypadku kontraktów interfejsu API sprawdzasz dostępność określonej funkcji lub interfejsu API na urządzeniu, skutecznie sprawdzając możliwości urządzenia, zamiast sprawdzać dostępność określonego urządzenia lub systemu operacyjnego. Platforma, która implementuje dowolny interfejs API w kontrakcie interfejsu API, jest wymagana do zaimplementowania każdego interfejsu API w tym kontrakcie interfejsu API. Oznacza to, że można sprawdzić, czy uruchomiony system operacyjny obsługuje określony kontrakt interfejsu API, a jeśli tak, wywołaj dowolny z interfejsów API w tym kontrakcie interfejsu API bez konieczności sprawdzania poszczególnych interfejsów API.

Największy i najczęściej używany kontrakt interfejsu API to Windows. Foundation.UniversalApiContract. Zawiera większość interfejsów API w ramach Universal Windows Platform. W dokumentacji zestawów SDK rozszerzeń dla rodziny urządzeń i kontraktów interfejsu API opisano różnorodność kontraktów API. Zobaczysz, że większość z nich reprezentuje zestaw funkcjonalnie powiązanych interfejsów API.

Uwaga / Notatka

Jeśli masz zainstalowany zestaw Windows SDK (Software Development Kit) w wersji zapoznawczej, który nie został jeszcze udokumentowany, możesz również znaleźć informacje o obsłudze kontraktu interfejsu API w pliku "Platform.xml" znajdującym się w folderze instalacyjnym zestawu SDK w lokalizacji "(Program Files (x86))\Windows Kits\10\Platforms<platform><SDK version>\Platform.xml' .

Kod adaptacyjny wersji i warunkowy kod XAML

We wszystkich wersjach Windows 10 możesz użyć klasy ApiInformation w warunku w kodzie, aby przetestować obecność interfejsu API, który chcesz wywołać. W kodzie adaptacyjnym można użyć różnych metod klasy, takich jak IsTypePresent, IsEventPresent, IsMethodPresent i IsPropertyPresent, aby przetestować interfejsy API na poziomie szczegółowości, którego potrzebujesz.

Aby uzyskać więcej informacji i przykładów, zobacz Kod adaptacyjny wersji.

Jeśli minimalna wersja aplikacji to kompilacja 15063 (aktualizacja dla twórców) lub nowsza, możesz użyć warunkowego XAML do ustawiania właściwości i tworzenia wystąpień obiektów w znaczniku bez potrzeby korzystania z kodu w tle. Warunkowy kod XAML umożliwia użycie metody ApiInformation.IsApiContractPresent w adiustacji.

Aby uzyskać więcej informacji i przykładów, zobacz Warunkowy kod XAML.

Interfejsy API ładowane z opóźnieniem

Funkcja QueryOptionalDelayLoadedAPI umożliwia aplikacjom Sklepu, które nie mogą korzystać z wywoływania LoadLibrary zgodnie z zasadami, wykrywanie, czy ich funkcja ładowana z opóźnieniem została rzeczywiście znaleziona.

#include <windows.h>
#include <commdlg.h>
#include <libloaderapi2.h>
#include <stdio.h>

EXTERN_C IMAGE_DOS_HEADER __ImageBase;
#define HMODULE_THISCOMPONENT reinterpret_cast<HMODULE>(&__ImageBase)

int __cdecl main(int argc, char** argv)
{
    if (QueryOptionalDelayLoadedAPI(HMODULE_THISCOMPONENT,
          "comdlg32.dll", "GetOpenFileNameW", 0))
    {
        printf("GetOpenFileNameW can be called!\n");
    }
    return 0;
}

Testowanie aplikacji adaptacyjnej wersji

Jeśli używasz kodu adaptacyjnego wersji lub warunkowego kodu XAML do pisania aplikacji adaptacyjnej wersji, musisz przetestować ją na urządzeniu z uruchomioną minimalną wersją i na urządzeniu z uruchomioną wersją docelową Windows 10.

Nie można przetestować wszystkich ścieżek kodu warunkowego na jednym urządzeniu. Aby upewnić się, że wszystkie ścieżki kodu są testowane, należy wdrożyć i przetestować aplikację na urządzeniu zdalnym (lub maszynie wirtualnej) z minimalną obsługiwaną wersją systemu operacyjnego. Aby uzyskać więcej informacji na temat zdalnego debugowania, zobacz Wdrażanie i debugowanie aplikacji platformy UWP.

  • Last updated on