Udostępnij przez


Przewodnik wdrażania Windows App SDK dla aplikacji zależnych od platformy opartych na zewnętrznej lokalizacji lub niezapakowanych

Ten temat zawiera wskazówki dotyczące wdrażania aplikacji, które są spakowane z lokalizacją zewnętrzną lub niespakowane, oraz korzystają z Windows App SDK.

  • Takie aplikacje to aplikacje klasyczne (nie aplikacje platformy UWP).
  • Można je pisać w języku .NET, takim jak C#, lub w języku C++.
  • W przypadku interfejsu użytkownika mogą używać winUI 3, WPF lub WinForms albo innej struktury interfejsu użytkownika.

Przegląd

Deweloperzy aplikacji pakietowych z lokalizacjami zewnętrznymi i niepakietowych są odpowiedzialni za wdrażanie wymaganych pakietów środowiska uruchomieniowego Windows App SDK dla użytkowników końcowych. Można to zrobić, uruchamiając instalator lub bezpośrednio instalując pakiety MSIX. Te opcje opisano bardziej szczegółowo w sekcji Wdrażanie środowiska uruchomieniowego zestawu SDK aplikacji systemu Windows poniżej.

Spakowane z lokalizacją zewnętrzną i rozpakowane aplikacje mają również dodatkowe wymagania dotyczące środowiska uruchomieniowego. Należy zainicjować dostęp do środowiska uruchomieniowego zestawu SDK aplikacji systemu Windows przy użyciu interfejsu API programu Bootstrapper. Ponadto interfejs API zależności dynamicznych może być używany, jeśli aplikacja korzysta z innych pakietów platform poza zestawem SDK aplikacji systemu Windows. Te wymagania są szczegółowo opisane w sekcji Wymagania środowiska uruchomieniowego dla aplikacji pakowanych z lokalizacją zewnętrzną lub bez pakowania poniżej.

Wymagania wstępne

Dodatkowe wymagania wstępne

  • Wersje eksperymentalne i w wersji zapoznawczej zestawu SDK aplikacji systemu Windows wymagają włączenia ładowania bezpośredniego w celu zainstalowania środowiska uruchomieniowego.
    • "Sideloading" jest automatycznie włączony w systemie Windows 10 w wersji 2004 lub nowszej.

    • Jeśli na komputerze dewelopera lub na komputerze wdrożeniowym jest uruchomiony system Windows 11, upewnij się, czy ładowanie bezpośrednie jest włączone:

      • Ustawienia>Prywatność i zabezpieczenia>Dla deweloperów. Upewnij się, że ustawienie Tryb deweloperski jest włączone.
    • Jeśli na komputerze deweloperów lub komputerze wdrożeniowym jest uruchomiony system Windows 10 w wersji 1909 lub starszej, upewnij się, czy włączono ładowanie bezpośrednie:

      • Ustawienia>Aktualizuj i zabezpieczenia>Dla deweloperów>Korzystanie z funkcji dla deweloperów. Upewnij się, że wybrano opcję Aplikacje z zewnętrznych źródeł lub Tryb dewelopera.
    • Ustawienie Tryb dewelopera obejmuje "instalowanie aplikacji spoza sklepu" oraz inne funkcje.

      Uwaga / Notatka

      Jeśli komputer jest zarządzany w środowisku przedsiębiorstwa, mogą istnieć zasady uniemożliwiające zmianę tych ustawień. W takim przypadku, jeśli wystąpi błąd podczas próby zainstalowania środowiska uruchomieniowego zestawu SDK aplikacji systemu Windows, skontaktuj się z specjalistą IT, aby włączyć ładowanie bezpośrednie lub tryb dewelopera.

Wdrażanie środowiska uruchomieniowego zestawu SDK aplikacji systemu Windows

Spakowane z lokalizacją zewnętrzną i rozpakowane aplikacje mają dwie opcje wdrażania środowiska uruchomieniowego zestawu SDK aplikacji systemu Windows:

  • Opcja 1. Użyj Instalatora: instalator dyskretny dystrybuuje wszystkie pakiety MSIX zestawu SDK aplikacji systemu Windows. Oddzielny instalator jest dostępny dla każdej z architektur: X64, X86 i Arm64.
  • Opcja 2. Zainstaluj pakiety bezpośrednio: możesz mieć istniejące narzędzie instalacyjne lub MSI do przenoszenia i instalowania pakietów MSIX dla zestawu SDK aplikacji systemu Windows.

Opcja 1. Korzystanie z Instalatora

Wszystkie pakiety środowiska uruchomieniowego zestawu SDK aplikacji systemu Windows można wdrożyć, uruchamiając instalatora. Instalator jest dostępny w sekcji Pliki do pobrania dla zestawu SDK aplikacji systemu Windows. Podczas uruchamiania instalatora (.exe) powinny zostać wyświetlone dane wyjściowe podobne do następujących:

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: MicrosoftCorporationII.WindowsAppRuntime.Main.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.Singleton_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x6_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x8_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

All install operations successful.

Instalator można uruchomić bez interakcji użytkownika i pominąć wszystkie dane wyjściowe tekstowe z opcją --quiet :

WindowsAppRuntimeInstall.exe --quiet

Możesz również wymusić aktualizację pakietów MSIX i zamknąć wszystkie aktualnie uruchomione procesy zestawu SDK aplikacji systemu Windows przy użyciu --force opcji . Ta funkcja jest wprowadzana w wersji 1.1.

WindowsAppRuntimeInstall.exe --force

Aby wyświetlić wszystkie opcje wiersza polecenia instalatora, uruchom polecenie WindowsAppRuntimeInstall --h.

Po zakończeniu instalacji można uruchomić aplikację spakowaną z lokalizacją zewnętrzną lub niespakowaną. Aby zapoznać się z przykładem na budowanie i uruchamianie aplikacji spakowanej z lokalizacją zewnętrzną lub rozpakowanej, korzystającej z Windows App SDK, zobacz Samouczek: używanie interfejsu API bootstrapping w aplikacji spakowanej z lokalizacją zewnętrzną lub rozpakowanej, która korzysta z Windows App SDK.

Łączenie instalatora zestawu SDK aplikacji systemu Windows z konfiguracją aplikacji

Jeśli masz niestandardowy program instalacyjny dla aplikacji, możesz utworzyć łańcuch procesu konfiguracji zestawu SDK aplikacji systemu Windows w procesie instalacji aplikacji. Instalator zestawu SDK aplikacji systemu Windows obecnie nie udostępnia domyślnego interfejsu użytkownika, dlatego należy połączyć przy użyciu niestandardowego interfejsu użytkownika twojej konfiguracji.

Możesz w trybie dyskretnym uruchamiać i śledzić konfigurację zestawu SDK aplikacji systemu Windows, wyświetlając własny widok postępu instalacji przy użyciu narzędzia ShellExecute. Instalator zestawu SDK aplikacji systemu Windows dyskretnie rozpakuje pakiet MSIX aplikacji systemu Windows i wywołuje metodę PackageManager.AddPackageAsync w celu ukończenia instalacji. Jest to bardzo podobne do innych instalatorów środowiska uruchomieniowego, których można użyć, takich jak .NET, Visual C++lub DirectX.

Aby zapoznać się z przykładem kodu, który pokazuje, jak uruchomić instalatora zestawu SDK aplikacji systemu Windows z poziomu programu instalacyjnego, zobacz funkcję RunInstaller w testach funkcjonalnych instalatora.

Przykład instalatora

Zapoznaj się z poniższym przykładem, aby zobaczyć, jak uruchomić instalatora z poziomu programu instalacyjnego Win32 bez wyświetlania okna konsoli podczas instalacji:

Rozwiązywanie problemów

Kody powrotne

W poniższej tabeli wymieniono najbardziej typowe kody powrotne dla instalatora zestawu SDK aplikacji systemu Windows .exe. Kody powrotne są takie same dla wszystkich wersji instalatora.

Kod powrotny Description
0x0 Instalacja pakietu lub aprowizacja została ukończona pomyślnie.
0x80073d06 Instalacja co najmniej jednego pakietu nie powiodła się.
0x80070005 Nie można zainstalować lub udostępnić całego systemu, ponieważ aplikacja nie jest uruchomiona z podwyższonymi uprawnieniami lub użytkownik wykonujący instalację nie ma uprawnień administratora.

Błędy instalacji

Jeśli instalator zestawu SDK aplikacji systemu Windows zwróci błąd podczas instalacji, zwróci kod błędu opisujący problem.

Opcja 2. Bezpośrednie wdrażanie pakietów środowiska uruchomieniowego zestawu SDK aplikacji systemu Windows

Alternatywą dla korzystania z instalatora Windows App SDK do wdrożenia dla użytkowników końcowych jest ręczne wdrożenie pakietów MSIX przez program aplikacji lub MSI. Ta opcja może być najlepsza dla deweloperów, którzy chcą mieć większą kontrolę.

Aby zapoznać się z przykładem sposobu instalowania pakietów MSIX przez program instalacyjny, zobacz install.cpp w kodzie instalatora zestawu SDK aplikacji systemu Windows.

Aby sprawdzić, czy zestaw SDK aplikacji systemu Windows jest już zainstalowany (i, jeśli tak, jaka wersja), możesz sprawdzić określone rodziny pakietów, wywołując funkcję PackageManager.FindPackagesForUserWithPackageTypes.

W procesie typu mediumIL (pełnego zaufania, nieopakowanym) (zobacz Element aplikacji) możesz użyć następującego kodu, aby sprawdzić, czy pakiet został zarejestrowany dla bieżącego użytkownika:

using Windows.Management.Deployment;

public class WindowsAppSDKRuntime
{
    public static IsPackageRegisteredForCurrentUser(
        string packageFamilyName,
        PackageVersion minVersion,
        Windows.System.ProcessorArchitecture architecture,
        PackageTypes packageType)
    {
        ulong minPackageVersion = ToVersion(minVersion);

        foreach (var p : PackageManager.FindPackagesForUserWithPackageTypes(
            string.Empty, packageFamilyName, packageType)
        {
            // Is the package architecture compatible?
            if (p.Id.Architecture != architecture)
            {
                continue;
            }

            // Is the package version sufficient for our needs?
            ulong packageVersion = ToVersion(p.Id.Version);
            if (packageVersion < minPackageVersion)
            {
                continue;
            }

            // Success.
            return true;
        }

        // No qualifying package found.
        return false;
    }

    private static ulong ToVersion(PackageVersion packageVersion)
    {
        return ((ulong)packageVersion.Major << 48) |
               ((ulong)packageVersion.Minor << 32) |
               ((ulong)packageVersion.Build << 16) |
               ((ulong)packageVersion.Revision);
    }
}

W powyższym scenariuszu wywołanie metody FindPackagesForUserWithPackageTypes jest preferowane do wywołania polecenia FindPackagesForUser. Jest to spowodowane tym, że można zawęzić wyszukiwanie do (na potrzeby tego przykładu), tylko struktury lub głównych pakietów. Pozwala to uniknąć dopasowywania innych typów pakietów (takich jak zasób, opcjonalny lub pakiet), które nie są interesujące w tym przykładzie.

Aby użyć bieżącego/wywołującego kontekstu użytkownika, ustaw parametr userSecurityId na pusty ciąg.

A teraz niektóre informacje ułatwiające podjęcie decyzji o wywołaniu funkcji w powyższym przykładzie kodu. Poprawnie zainstalowane środowisko uruchomieniowe składa się z wielu pakietów, które zależą od architektury procesora CPU systemu:

  • Na maszynie x86: Fwk=[x86], Main=[x86], Singleton=[x86], DDLM=[x86].
  • Na maszynie x64: Fwk=[x86, x64], Main=[x64], Singleton=[x64], DDLM=[x86, x64].
  • Na maszynie arm64: Fwk=[x86, x64, arm64], Main=[arm64], Singleton=[arm64], DDLM=[x86, x64, arm64].

W przypadku pakietów Main i Singleton architektura powinna być zgodna z architekturą procesora CPU systemu; na przykład pakiety x64 w systemie x64. W przypadku pakietu framework system x64 może uruchamiać zarówno aplikacje x64, jak i x86; podobnie system arm64 może uruchamiać aplikacje arm64, x64 i x86. Sprawdzanie pakietu DDLM jest podobne do sprawdzania struktury , z tą różnicą, że PackageType=mainnazwa packagefamilyname różni się, a więcej niż jeden (inny) packagefamilyname może mieć zastosowanie z powodu unikatowego schematu nazewnictwa DDLM. Aby uzyskać więcej informacji, zobacz specyfikację pakietów MSIX . Dlatego kontrole są bardziej podobne do następujących:

public static bool IsRuntimeRegisteredForCurrentUser(PackageVersion minVersion)
{
    ProcessorArchitecture systemArchitecture = DetectSystemArchitecture();

    return IsFrameworkRegistered(systemArchitecture, minVersion) &&
           IsMainRegistered(systemArchitecture, minVersion) &&
           IsSingletonRegistered(systemArchitecture, minVersion) &&
           IsDDLMRegistered(systemArchitecture, minVersion);
}

private static ProcecssorArchitecture DetectSystemArchitecture()
{
    // ...see the call to IsWow64Process2(), and how the result is used...
    // ...as per `IsPackageApplicable()` in
    // [install.cpp](https://github.com/microsoft/WindowsAppSDK/blob/main/installer/dev/install.cpp)
    // line 99-116...
    // ...WARNING: Use IsWow64Process2 to detect the system architecture....
    // ...         Other similar APIs exist, but don't give reliably accurate results...
}

private static bool IsFrameworkRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    // Check x86.
    if (!IsPackageRegisteredForCurrentUser(
        global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
        minVersion, ProcessorArchitecture.X86,
        PackageTypes.Framework))
    {
        return false;
    }

    // Check x64 (if necessary).
    if ((systemArchitecture == ProcessorArchitecture.X64) || 
        (systemArchitecture == ProcessorArchitcture.Arm64))
    {
        if (!IsPackageRegisteredForCurrentUser(
            global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
            minVersion, ProcessorArchitecture.X64,
            PackageTypes.Framework))
        {
            return false;
        }
    }

    // Check arm64 (if necessary).
    if (systemArchitecture == ProcessorArchitcture.Arm64)
    {
        if (!IsPackageRegisteredForCurrentUser(
            global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
            minVersion, ProcessorArchitecture.Arm64,
            PackageTypes.Framework))
        {
            return false;
        }
    }

    return true;
}

private static bool IsMainRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    return IsPackageRegisteredForCurrentUser(
        global::Microsoft.WindowsAppSDK.Runtime.Packages.Main.PackageFamilyName,
        minVersion,
        systemArchitecture,
        PackageTypes.Main);
}

private static bool IsSingletonRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    return IsPackageRegisteredForCurrentUser(
        global::Microsoft.WindowsAppSDK.Runtime.Packages.Singleton.PackageFamilyName,
        minVersion,
        systemArchitecture,
        PackageTypes.Main);
}

private static bool IsDDLMRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    // ...similar to IsFrameworkRegistered, but the packageFamilyName is more complicated...
    // ...and no predefined constant is currently available...
    // ...for more details, see
    // https://github.com/microsoft/WindowsAppSDK/blob/main/specs/Deployment/MSIXPackages.md.
}

Powyższe informacje i kod obejmują podstawowy scenariusz wykrywania. Aby wykryć, czy środowisko uruchomieniowe jest aprowizowane dla wszystkich użytkowników, czy też wykonać powyższe czynności z kontenera aplikacji i/lub zrobić to z procesu spakowanego mediumIL , wymagana jest dodatkowa logika.

Scenariusze wdrażania

  • Instalowanie całego systemu środowiska uruchomieniowego zestawu SDK aplikacji systemu Windows: instalacja w całym systemie zmienia maszynę dla wszystkich użytkowników, w tym nowych użytkowników, którzy są dodawani w przyszłości. Jeśli aplikacja jest uruchomiona z podwyższonym poziomem uprawnień, a użytkownik wykonujący instalację ma uprawnienia administratora, instalator zarejestruje pakiet MSIX dla całego systemu, wywołując element ProvisionPackageForAllUsersAsync. Jeśli rejestracja w całym systemie nie powiedzie się, instalacja zostanie wykonana tylko dla bieżącego użytkownika wykonującego instalację. W zarządzanym środowisku przedsiębiorstwa administrator IT powinien mieć możliwość zapewniania zasobów dla wszystkich w zwykły sposób.

  • Architektury redystrybuowane przez instalatora zestawu SDK aplikacji systemu Windows: Instalator zestawu SDK aplikacji systemu Windows jest dostępny w x86architekturach , x64i Arm64 . Każda wersja instalatora zawiera pakiety MSIX tylko dla określonej architektury, dla którego została nazwana. Jeśli na przykład uruchomisz x86WindowsAppRuntimeInstall.exe na urządzeniu x64 lub Arm64, to x86 instalator wdroży na tym urządzeniu tylko pakiety dla architektury x86.

  • Wszystkie pakiety MSIX Windows App SDK są już zainstalowane na komputerze: Pakiety MSIX są instalowane w systemowej lokalizacji z tylko jedną kopią na dysku. Jeśli aplikacja próbuje zainstalować zestaw SDK aplikacji systemu Windows, gdy wszystkie zależności pakietu MSIX są już zainstalowane na maszynie, instalacja nie jest wykonywana.

  • Co najmniej jeden pakiet MSIX zestawu SDK aplikacji systemu Windows nie jest zainstalowany na komputerze: podczas wdrażania zestawu SDK aplikacji systemu Windows należy zawsze próbować zainstalować wszystkie pakiety MSIX (framework, main, singleton, DDLM), aby upewnić się, że wszystkie zależności są zainstalowane i uniknąć zakłóceń w środowisku użytkownika końcowego.

Wymagania dotyczące środowiska uruchomieniowego dla aplikacji spakowanych z zewnętrzną lokalizacją lub nieopakowanych

Aplikacje spakowane z lokalizacją zewnętrzną lub rozpakowane mają dodatkowe wymagania dotyczące środowiska uruchomieniowego do korzystania ze środowiska uruchomieniowego zestawu SDK aplikacji systemu Windows. Obejmuje to odwoływanie się do pakietu windows App SDK Framework i inicjowanie go w czasie wykonywania. Ponadto interfejs API zależności dynamicznych może służyć do odwoływania się do innych pakietów platform poza zestawem SDK aplikacji systemu Windows.

Korzystanie ze środowiska uruchomieniowego zestawu SDK aplikacji systemu Windows

Spakowane z lokalizacją zewnętrzną i rozpakowane aplikacje muszą wywołać interfejs Bootstrapper API, aby używać Windows App SDK podczas działania. Jest to wymagane, zanim aplikacja będzie mogła korzystać z funkcji zestawu SDK aplikacji systemu Windows, takich jak WinUI, Cykl życia aplikacji, MRT Core i DWriteCore. Składnik programu inicjującego umożliwia aplikacjom opakowanym z lokalizacją zewnętrzną i aplikacjom nieopakowanym wykonywanie następujących ważnych zadań:

  • Znajdź i załaduj pakiet frameworku Windows App SDK do struktury pakietu aplikacji.
  • Zainicjuj dynamiczny Menedżer Okresu Trwania Zależności (DDLM) dla pakietu frameworka Windows App SDK. Celem DDLM jest zapobieganie serwisowaniu pakietu frameworka Windows App SDK, gdy jest on używany przez aplikację spakowaną z zewnętrzną lokalizacją lub niezapakowaną aplikację.

Najprostszym sposobem załadowania środowiska uruchomieniowego Windows App SDK dla aplikacji spakowanych z lokalizacją zewnętrzną i aplikacji niespakowanych jest ustawienie właściwości <WindowsPackageType>None</WindowsPackageType> w pliku projektu (.csproj lub .vcxproj). Możesz również wywołać interfejs API programu inicjującego bezpośrednio w kodzie uruchamiania aplikacji, aby uzyskać większą kontrolę nad procesem inicjowania. Aby uzyskać więcej informacji, zobacz Wykorzystywanie środowiska wykonawczego Windows App SDK w aplikacjach spakowanych z lokalizacją zewnętrzną lub niespakowanych oraz Poradnik: Używanie interfejsu API programu bootstrapper w aplikacji spakowanej z lokalizacją zewnętrzną lub niespakowanej, która korzysta z Windows App SDK.

Obsługa zależności dynamicznych umożliwia aplikacjom spakowanym z lokalizacją zewnętrzną i aplikacjom nieopakowanym utrzymanie istniejącego mechanizmu wdrażania, takiego jak MSI lub dowolny inny instalator, oraz skorzystanie z Windows App SDK w swojej aplikacji. Zależności dynamiczne mogą być używane przez spakowane aplikacje, spakowane z lokalizacją zewnętrzną i rozpakowane aplikacje, chociaż mają być używane głównie przez spakowane z lokalizacją zewnętrzną i rozpakowane aplikacje.

Istnieje jeden DDLM dla każdej wersji i architektury pakietu frameworku Windows App SDK. Oznacza to, że na x64 komputerze może istnieć zarówno wersja DDLM x86, jak i x64, aby obsługiwać aplikacje obu architektur.

Odwołanie się do innych pakietów frameworków przy użyciu interfejsu API zależności dynamicznych

Jeśli chcesz używać funkcji w innych pakietach platformowych poza zestawem Windows App SDK (np. DirectX), aplikacje spakowane z zewnętrzną lokalizacją i aplikacje bez pakietu mogą wywoływać interfejs API dynamicznych zależności. Oprócz składnika programu inicjatora zestaw SDK aplikacji systemu Windows udostępnia również szerszy zestaw funkcji C/C++ i klas WinRT, które implementują interfejs API zależności dynamicznej. Ten interfejs API jest przeznaczony do dynamicznego odwoływania się do dowolnego pakietu struktury w czasie wykonywania.

Aby uzyskać więcej informacji, zobacz Dynamiczne używanie pakietów platformy MSIX z poziomu aplikacji klasycznej i przykładu Zależności dynamiczne

Wdrażanie plików winmd na maszynie docelowej

Wraz z aplikacją zalecamy wdrożenie plików metadanych systemu Windows (.winmd). Metadane mogą być używane przez różne interfejsy API i zachowania w czasie wykonywania, a ich brak może ograniczać lub przerywać funkcjonalność. Na przykład metadane mogą służyć do marshalingu obiektów przez granice mieszkań; i konieczność marshalingu może być funkcją wydajności maszyny. Ponieważ nie ma deterministycznego sposobu, aby wiedzieć, czy potrzebujesz metadanych, należy wdrożyć .winmdje, chyba że bardzo interesuje Cię rozmiar.