Průvodce nasazením Windows App SDK pro aplikace závislé na frameworku, zabalené s externím umístěním nebo nerozbalené

Toto téma obsahuje pokyny k nasazení aplikací, které jsou zabalené s externím umístěním, nebo nebalených, a které používají Windows App SDK.

  • Takové aplikace jsou desktopové aplikace (ne aplikace pro UPW).
  • Dají se psát v .NET jazyce, jako je C#, nebo v jazyce C++.
  • Pro své uživatelské rozhraní můžou použít WinUI 3 nebo WPF, WinForms nebo jinou architekturu uživatelského rozhraní.

Přehled

Vývojáři zabalených aplikací s externím umístěním a rozbalených aplikací zodpovídají za nasazení požadovaných balíčků modulu runtime Windows App SDK koncovým uživatelům. Můžete to provést buď spuštěním instalačního programu, nebo přímo instalací balíčků MSIX. Tyto možnosti jsou podrobněji popsány v části Deploy Windows App SDK runtime níže.

Aplikace zabalené s externím umístěním a aplikace bez balení mají také další požadavky za běhu. Musíte inicializovat přístup k modulu runtime Windows App SDK pomocí rozhraní API Bootstrapperu. Kromě toho je možné použít rozhraní API pro dynamické závislosti, pokud vaše aplikace využívá další balíčky architektury kromě Windows App SDK. Tyto požadavky jsou podrobněji popsány v požadavcích na runtime pro aplikace zabalené s externím umístěním nebo bez balíčku části níže.

Požadavky

Další požadavky

  • Experimentální a předběžné verze Windows App SDK vyžadují, aby bylo pro instalaci runtime povoleno zkušební načítání.

    • Postranní načítání je automaticky povoleno na Windows 10 verze 2004 a novější.

    • Pokud na počítači pro vývoj nebo na počítači nasazení běží Windows 11, zkontrolujte, zda je povoleno vedlejší načítání:

      • Nastavení>Ochrana osobních údajů a zabezpečení>Pro vývojáře. Ujistěte se, že je zapnuté nastavení vývojářského režimu .

    • Pokud váš vývojový nebo nasazovací počítač běží na Windows 10 verze 1909 nebo starší verzi, zkontrolujte, zda je povolené sideloading:

      • Nastavení>Aktualizace a zabezpečení>Pro vývojáře>Používejte funkce pro vývojáře. Potvrďte, že je vybrána možnost Instalace aplikací z neznámých zdrojů nebo Režim pro vývojáře.

    • Nastavení vývojářského režimu zahrnuje sideloading a další funkce.

      Poznámka:

      Pokud je počítač spravovaný v podnikovém prostředí, může existovat zásada, která brání změně těchto nastavení. Pokud při pokusu o instalaci modulu runtime Windows App SDK dojde k chybě, obraťte se na IT profesionála, aby povolil sideloading nebo Režim vývojáře.

Nasazení modulu runtime Windows App SDK

Balíčkované aplikace s externím umístěním a nebalíčkované aplikace mají dvě možnosti, jak nasadit Windows App SDK runtime:

Možnost 1: Použití instalačního programu

Všechny balíčky modulu runtime Windows App SDK můžete nasadit spuštěním instalačního programu. Instalační program je k dispozici na Stahování pro Windows App SDK. Při spuštění instalačního programu (.exe) by se měl zobrazit výstup podobný následujícímu:

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.

Instalační program můžete spustit bez zásahu uživatele a potlačit veškerý textový výstup pomocí --quiet možnosti:

WindowsAppRuntimeInstall.exe --quiet

Pomocí možnosti --force můžete také vynutit aktualizaci balíčků MSIX a vypnout všechny aktuálně spuštěné procesy Windows App SDK. Tato funkce je představena ve verzi 1.1.

WindowsAppRuntimeInstall.exe --force

Pokud chcete zobrazit všechny možnosti příkazového řádku instalačního programu, spusťte WindowsAppRuntimeInstall --hpříkaz .

Po dokončení instalace můžete spustit svou zabalenou aplikaci s externím umístěním nebo rozbalenou aplikaci. Příklad sestavení a spuštění balíčku s externím umístěním nebo nerozbalené aplikace, která používá Windows App SDK, viz Tutorial: Použití rozhraní API bootstrapperu v aplikaci zabalené s externím umístěním nebo nerozbalené, které používá Windows App SDK.

Zřetězte instalační program Windows App SDK s nastavením vaší aplikace.

Pokud máte vlastní instalační program pro aplikaci, můžete zřetězovat proces nastavení Windows App SDK v procesu nastavení aplikace. Instalační program Windows App SDK momentálně neposkytuje výchozí uživatelské rozhraní, takže budete muset řetězit pomocí vlastního uživatelského rozhraní vašeho nastavení.

Můžete tiše spustit a sledovat nastavení Windows App SDK a zároveň zobrazit vlastní pohled na průběh instalace pomocí ShellExecute. Instalační program Windows App SDK bezobslužně rozbalí sadu Windows App MSIX a zavolá metodu PackageManager.AddPackageAsync k dokončení instalace. Je to velmi podobné ostatním instalačním programům modulu runtime, které jste možná použili, například .NET, Visual C++ nebo DirectX.

Příklad kódu, který ukazuje, jak spustit instalační program Windows App SDK z instalačního programu, najdete v RunInstaller ve funkčních testech installer.

Ukázka instalačního programu

V následující ukázce se dozvíte, jak spustit instalační program z instalačního programu Win32, aniž by se během instalace zobrazilo okno konzoly:

Ukázka instalačního programu Explore

Řešení problémů

Návratové kódy

Následující tabulka uvádí nejběžnější návratové kódy pro instalační program Windows App SDK .exe. Návratové kódy jsou stejné pro všechny verze instalačního programu.

Návratový kód Description
0x0 Instalace nebo zprovoznění balíčku byly úspěšně dokončeny.
0x80073d06 Nepodařilo se nainstalovat jeden nebo více balíčků.
0x80070005 Instalace nebo zřizování pro celý systém nebylo možné, protože aplikace není spuštěná se zvýšenými oprávněními nebo uživatel provádějící instalaci nemá oprávnění správce.

Chyby instalace

Pokud instalační program Windows App SDK během instalace vrátí chybu, vrátí kód chyby, který problém popisuje.

Možnost 2: Přímé nasazení balíčků modulu runtime Windows App SDK

Alternativou k použití instalačního programu Windows App SDK pro nasazení koncovým uživatelům můžete balíčky MSIX ručně nasadit prostřednictvím programu nebo MSI vaší aplikace. Tato možnost může být nejvhodnější pro vývojáře, kteří chtějí mít větší kontrolu.

Příklad, který ukazuje, jak instalační program může nainstalovat balíčky MSIX, viz install.cpp v kódu instalačního programu Windows App SDK.

Pokud chcete zkontrolovat, jestli už je Windows App SDK nainstalovaný (a pokud ano, jakou verzi), můžete vyhledat konkrétní rodiny balíčků voláním PackageManager.FindPackagesForUserWithPackageTypes.

Z procesu (úplné důvěry, bez balíčku) (viz Prvek aplikace) můžete pomocí následujícího kódu ověřit balíček zaregistrovaný aktuálnímu uživateli:

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);
    }
}

Pro výše uvedený scénář je vhodnější volání FindPackagesForUserWithPackageTypes než volání FindPackagesForUser. Je to proto, že můžete vyhledávání zúžit (v tomto příkladu) jenom na framework nebo hlavní balíčky. A tím se vyhnete porovnávání jiných typů balíčků (například prostředků, volitelných prostředků nebo sad), které nejsou pro tento příklad zajímavé.

Pokud chcete použít kontext aktuálního nebo volajícího uživatele, nastavte parametr userSecurityId na prázdný řetězec.

A teď některé informace, které vám pomůžou rozhodnout , jak volat funkci v příkladu kódu výše. Správně nainstalovaný modul runtime se skládá z několika balíčků, které závisí na architektuře procesoru systému:

  • Na počítači x86: Fwk=[x86], Main=[x86], Singleton=[x86], DDLM=[x86].
  • Na počítači x64: Fwk=[x86, x64], Main=[x64], Singleton=[x64], DDLM=[x86, x64].
  • Na platformě arm64: Fwk=[x86, x64, arm64], Main=[arm64], Singleton=[arm64], DDLM=[x86, x64, arm64].

Pro balíčky Main a Singleton by jejich architektura měla odpovídat architektuře procesoru systému; Například balíčky x64 v systému x64. Pro balíček Framework může systém x64 spouštět aplikace x64 i x86; Podobně systém arm64 může spouštět aplikace arm64, x64 a x86. Kontrola balíčku DDLM se podobá kontrole architektury s tím rozdílem, že PackageType=maina název packagefamilyname se liší a může být možné použít více než jeden (jiný) název balíčku , protože je to jedinečné schéma pojmenování DDLM. Další informace naleznete ve specifikaci balíčků MSIX. Kontroly jsou tedy více jako toto:

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

Výše uvedené informace a kód se týkají základního scénáře detekce. Abyste zjistili, zda je runtime zřízen pro všechny uživatele, nebo zda se to provádí z kontejneru aplikací a/nebo z baleného procesu mediumIL, je zapotřebí další logika.

Scénáře nasazení

  • Instalace systému Windows App SDK Runtime: Systémová instalace změní počítač pro všechny uživatele, včetně nových uživatelů přidaných v budoucnu. Pokud aplikace běží se zvýšenými oprávněními a uživatel provádějící instalaci má oprávnění správce, instalační program zaregistruje balíčky MSIX v celém systému voláním ProvisionPackageForAllUsersAsync. Pokud registrace pro celý systém není úspěšná, instalace se provede pouze pro aktuálního uživatele, který provádí instalaci. Ve spravovaném podnikovém prostředí by měl být správce IT schopný zajistit služby pro všechny, jak je zvykem.

  • Architectures redistributed by the Windows App SDK installer: Instalační program Windows App SDK je k dispozici v architekturách x86, x64 a Arm64. Každá verze instalačního programu obsahuje balíčky MSIX pouze pro konkrétní architekturu, pro které má název. Pokud například spustíte x86WindowsAppRuntimeInstall.exe na zařízení x64 nebo Arm64, tento x86 instalační program na toto zařízení nasadí pouze balíčky pro architekturu x86.

  • Všechny balíčky MSIX Windows App SDK jsou již nainstalovány v počítači: Balíčky MSIX jsou nainstalovány do systémového umístění pouze s jednou kopií na disku. Pokud se aplikace pokusí nainstalovat Windows App SDK, pokud jsou na počítači již nainstalovány všechny závislosti balíčků MSIX, instalace se neprovádí.

  • Jeden nebo více balíčků MSIX pro Windows App SDK nejsou na počítači nainstalovány: Při nasazování Windows App SDK se vždy pokuste nainstalovat všechny balíčky MSIX (framework, main, singleton, DDLM), aby bylo zajištěno, že jsou nainstalovány všechny závislosti a zamezíte narušení uživatelského prostředí.

Požadavky na runtime pro aplikace zabalené s externím umístěním nebo nezabalené

Aplikace balené s externě umístěnými soubory nebo rozbalené mají dodatečné požadavky na použití runtime Windows App SDK. To zahrnuje odkazování a inicializaci balíčku Windows App SDK Framework za běhu. Kromě toho je možné použít rozhraní API pro dynamické závislosti k odkazování na další balíčky rozhraní mimo Windows App SDK.

Použijte Windows App SDK runtime

Aplikace zabalené s externím umístěním a rozbalené aplikace musí volat rozhraní API Bootstrapperu, aby bylo možné používat Windows App SDK během běhu. To se vyžaduje před tím, než může aplikace používat Windows App SDK funkce, jako jsou WinUI, Životní cyklus aplikací, MRT Core a DWriteCore. Komponenta bootstrapperu umožňuje zabaleným s externím umístěním a nebaleným aplikacím provádět tyto důležité úlohy:

  • Vyhledejte a načtěte balíček architektury Windows App SDK do grafu balíčku aplikace.
  • Inicializace nástroje DDLM (Dynamic Dependency Lifetime Manager) pro balíček architektury Windows App SDK Účelem DDLM je zabránit údržbě balíčku architektury Windows App SDK, když ho používá balíček zabalený s externím umístěním nebo rozbalenou aplikací.

Nejjednodušší způsob, jak načíst modul runtime Windows App SDK pro balíčkované aplikace s externím umístěním a nebalíčkové aplikace, je nastavení vlastnosti <WindowsPackageType>None</WindowsPackageType> v souboru Project (.csproj nebo .vcxproj). Můžete také volat rozhraní API bootstrapperu přímo ve spouštěcím kódu vaší aplikace, abyste měli větší kontrolu nad inicializací. Další podrobnosti najdete v tématu Použití modulu runtime Windows App SDK pro aplikace zabalené s externím umístěním nebo nebalené a Návod: Použijte bootstrapper API v aplikaci zabalené s externím umístěním nebo nebalené, které používají Windows App SDK.

Podpora dynamických závislostí umožňuje aplikacím zabaleným s externím umístěním a nebaleným aplikacím zachovat stávající mechanismus nasazení, jako je MSI nebo libovolný instalační program, a umožňuje využít Windows App SDK v jejich aplikaci. Dynamické závislosti mohou být používány zabalenými, zabalenými s externím umístěním a rozbalenými aplikacemi; i když jsou primárně určeny pro použití zabalenými s externím umístěním a rozbalenými aplikacemi.

Pro každou verzi a architekturu balíčku architektury Windows App SDK existuje jeden DDLM. To znamená, že na x64 počítači můžete mít jak verzi x86, tak verzi x64 DDLM, aby bylo možné podporovat aplikace obou architektur.

Odkaz na další balíčky architektury pomocí rozhraní API dynamických závislostí

Pokud chcete používat funkce v jiných balíčcích rámce mimo Windows App SDK (např. DirectX), aplikace zabalené s externím umístěním i ty bez balení mohou volat API dynamických závislostí. Kromě komponenty bootstrapper poskytuje Windows App SDK také širší sadu funkcí C/C++ a winRT tříd, které implementují dynamické závislé rozhraní API. Toto rozhraní API je navržené tak, aby bylo možné dynamicky odkazovat na jakýkoli balíček architektury za běhu.

Další informace najdete v tématu Použití balíčků architektury MSIX dynamicky z desktopové aplikace a ukázky dynamických závislostí.

Nasazení souborů .winmd do cílového počítače

Společně s vaší aplikací doporučujeme nasadit soubory metadat (.winmdWindows Metadata). Metadata můžou používat různá rozhraní API a chování za běhu a její absence může omezit nebo přerušit funkčnost. Metadata lze například použít k zařazování objektů přes hranice apartmánů; a nutnost zařazování může být funkcí výkonu počítače. Vzhledem k tomu, že neexistuje žádný deterministický způsob, jak zjistit, jestli potřebujete metadata, měli byste nasadit .winmds, pokud nejste příliš znepokojeni velikostí.

  • Architektura nasazení pro Windows App SDK
  • Last updated on