Freigeben über

Windows App SDK Bereitstellungshandbuch für frameworkabhängige Apps, die mit externem Speicherort verpackt oder entpackt sind

Dieses Thema enthält Anleitungen zum Bereitstellen von Apps, die mit externem Speicherort verpackt oder entpackt sind und das Windows App SDK verwenden.

  • Solche Apps sind Desktop-Apps (nicht UWP-Apps).
  • Sie können in einer .NET Sprache wie C# oder in C++ geschrieben werden.
  • Für die Benutzeroberfläche können sie WinUI 3 oder WPF oder WinForms oder ein anderes Benutzeroberflächenframework verwenden.

Übersicht

Entwickler von Apps, die entweder als Pakete mit externem Speicherort oder als entpackte Apps bereitgestellt werden, sind dafür verantwortlich, die notwendigen Windows App SDK-Laufzeitpakete für ihre Endbenutzer bereitzustellen. Das kann entweder durch Ausführen des Installationsprogramms oder durch direkte Installation der MSIX-Pakete erfolgen. Diese Optionen werden im Abschnitt Deploy Windows App SDK runtime weiter unten beschrieben.

Für mit externem Speicherort gepackte und ungepackte Apps gelten auch zusätzliche Laufzeitanforderungen. Sie müssen den Zugriff auf die Windows App SDK-Laufzeit mithilfe der Bootstrapper-API initialisieren. Darüber hinaus kann die DYNAMISCHE Abhängigkeits-API verwendet werden, wenn Ihre App andere Frameworkpakete verwendet, abgesehen von der Windows App SDK. Diese Anforderungen werden im Abschnitt Laufzeitanforderungen für mit externem Speicherort gepackte oder ungepackte Apps weiter unten ausführlicher beschrieben.

Voraussetzungen

Zusätzliche Voraussetzungen

  • Experimentelle und Vorschauversionen der Windows App SDK setzen voraus, dass Sideloading aktiviert wird, um die Laufzeitumgebung zu installieren.

    • Das Querladen wird auf Windows 10 Version 2004 und höher automatisch aktiviert.

    • Wenn Ihr Entwicklungscomputer oder der Bereitstellungscomputer Windows 11 ausführt, überprüfen Sie, ob das Sideloading aktiviert ist:

      • Einstellungen>Datenschutz und Sicherheit>Für Entwickler. Stellen Sie sicher, dass die Einstellung Entwicklermodus aktiviert ist.

    • Wenn ihr Entwicklungscomputer oder der Bereitstellungscomputer Windows 10 Version 1909 oder eine frühere Version ausgeführt wird, überprüfen Sie, ob das Querladen aktiviert ist:

      • Einstellungen>Update und Sicherheit>Für Entwickler>Entwicklerfunktionen verwenden. Vergewissern Sie sich, dass Apps querladen oder Entwicklermodus ausgewählt ist.

    • Die Einstellung Entwicklermodus beinhaltet das Querladen wie auch andere Features.

      Hinweis

      Wenn der Computer in einer Unternehmensumgebung verwaltet wird, gibt es möglicherweise eine Richtlinie, die das Ändern dieser Einstellungen verhindert. Falls bei Ihnen oder Ihrer App ein Fehler auftritt, wenn Sie versuchen, die Windows App SDK-Laufzeit zu installieren, wenden Sie sich an Ihren IT-Experten, um das Querladen oder den Entwicklermodus zu aktivieren.

Bereitstellen der Windows App SDK Laufzeit

Verpackte Apps mit externen Speicherorten und nicht verpackte Apps haben zwei Optionen für die Bereitstellung der Windows-App-SDK-Laufzeitumgebung:

Option 1: Verwenden des Installationsprogramms

Sie können alle Windows App SDK Laufzeitpakete bereitstellen, indem Sie das Installationsprogramm ausführen. Das Installationsprogramm ist unter Downloads für die Windows App SDK verfügbar. Beim Ausführen des Installationsprogramms (.exe) sollte eine Ausgabe folgender Art angezeigt werden:

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.

Mit der Option --quiet können Sie das Installationsprogramm ohne Benutzereingriff ausführen und jegliche Textausgabe unterdrücken:

WindowsAppRuntimeInstall.exe --quiet

Sie können auch die Aktualisierung der MSIX-Pakete erzwingen und alle derzeit ausgeführten Windows App SDK Prozesse mithilfe der Option --force herunterfahren. Dieses Feature wird in 1.1 eingeführt.

WindowsAppRuntimeInstall.exe --force

Führen Sie WindowsAppRuntimeInstall --h aus, um alle Befehlszeilenoptionen des Installationsprogramms zu sehen.

Nach Abschluss der Installation können Sie Ihre mit externem Speicherort gepackte oder ungepackte App ausführen. Ein Beispiel zum Erstellen und Ausführen eines Pakets mit externem Speicherort oder entpackten Apps, die die Windows App SDK verwenden, finden Sie unter Tutorial: Verwenden der Bootstrapper-API in einer App, die mit externem Speicherort verpackt ist oder entpackt wird, die die Windows App SDK verwendet.

Verketten des Windows App SDK Installers an das Setup Ihrer App

Wenn Sie über ein benutzerdefiniertes Setupprogramm für Ihre App verfügen, können Sie den Windows App SDK Setupprozess im Setupprozess Ihrer App verketten. Das Windows App SDK-Installationsprogramm stellt derzeit keine Standard-UI bereit, daher müssen Sie die benutzerdefinierte Benutzeroberfläche Ihres Setups verwenden.

Sie können das Windows App SDK Setup automatisch starten und nachverfolgen, während Sie ihre eigene Ansicht des Setupfortschritts anzeigen, indem Sie ShellExecute verwenden. Der Windows App SDK Installer entpackt das Windows App MSIX-Bundle im Hintergrund und ruft die PackageManager.AddPackageAsync-Methode auf, um die Installation abzuschließen. Dies ähnelt anderen Laufzeitinstallationsprogrammen, die Sie möglicherweise verwendet haben, z. B. .NET, Visual C++ oder DirectX.

Ein Codebeispiel, das veranschaulicht, wie das Windows App SDK Installationsprogramm von Ihrem Setupprogramm ausgeführt wird, finden Sie in der RunInstaller Funktion in den Funktionstests des Installers.

Beispiel zum Installationsprogramm

Im folgenden Beispiel können Sie sehen, wie das Installationsprogramm über ein Win32-Setupprogramm gestartet werden kann, ohne dass sich während des Setups ein Konsolenfenster öffnet:

Explore Installer-Beispiel

Problembehandlung

Rückgabecodes

In der folgenden Tabelle sind die am häufigsten verwendeten Rückgabecodes für das Windows App SDK .exe-Installationsprogramm aufgeführt. Die Rückgabecodes sind für alle Versionen des Installationsprogramms identisch.

Rückgabecode Beschreibung
0x0 Die Paketinstallation oder Bereitstellung wurde erfolgreich abgeschlossen.
0x80073d06 Mindestens ein Paket konnte nicht installiert werden.
0x80070005 Systemweite Installation oder Bereitstellung war nicht möglich, da die App nicht mit erhöhten Rechten ausgeführt wird oder der Benutzer, der die Installation durchführt, keine Administratorrechte hat.

Installationsfehler

Wenn der Windows App SDK Installer während der Installation einen Fehler zurückgibt, wird ein Fehlercode zurückgegeben, der das Problem beschreibt.

Option 2: Bereitstellen von Windows App SDK Laufzeitpaketen direkt

Als Alternative zur Verwendung des Windows App SDK Installers für die Bereitstellung für Endbenutzer können Sie die MSIX-Pakete manuell über das Programm oder MSI Ihrer App bereitstellen. Diese Option kann für Entwickler, die mehr Kontrolle wünschen, die beste Möglichkeit sein.

Ein Beispiel, das veranschaulicht, wie Ihr Setupprogramm die MSIX-Pakete installieren kann, finden Sie unter install.cpp im Windows App SDK Installer-Code.

Um zu überprüfen, ob die Windows App SDK bereits installiert ist (und falls ja, welche Version), können Sie nach bestimmten Paketfamilien suchen, indem Sie PackageManager.FindPackagesForUserWithPackageTypes aufrufen.

Aus einem mediumIL (voll vertrauenswürdigen) entpackten Prozess (siehe Application-Element) können Sie den folgenden Code verwenden, um nach einem Paket zu suchen, das für den aktuellen Benutzer registriert ist:

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

Für das obige Szenario ist das Aufrufen von FindPackagesForUserWithPackageTypes vorzuziehen, um FindPackagesForUser aufzurufen. Das liegt daran, dass Sie die Suche (in diesem Beispiel) nur auf das Framework oder die Hauptpakete einschränken können. Und das verhindert das Abgleichen anderer Pakettypen (z . B. Ressource, Optional oder Bündel), die für dieses Beispiel nicht von Interesse sind.

Um den aktuellen/aufrufenden Benutzerkontext zu verwenden, legen Sie den Parameter "userSecurityId " auf eine leere Zeichenfolge fest.

Und jetzt einige Informationen, mit denen Sie entscheiden können, wie die Funktion im obigen Codebeispiel aufgerufen wird. Eine ordnungsgemäß installierte Laufzeit besteht aus mehreren Paketen, die von der CPU-Architektur des Systems abhängen:

  • Auf einem x86-Computer: Fwk=[x86], Main=[x86], Singleton=[x86], DDLM=[x86].
  • Auf einem x64-Computer: Fwk=[x86, x64], Main=[x64], Singleton=[x64], DDLM=[x86, x64].
  • Auf einem ARM64-Computer: Fwk=[x86, x64, arm64], Main=[arm64], Singleton=[arm64], DDLM=[x86, x64, arm64].

Für die Main - und Singleton-Pakete sollte ihre Architektur der CPU-Architektur des Systems entsprechen, z. B. x64-Pakete auf einem x64-System. Für das Framework-Paket kann ein x64-System sowohl x64- als auch x86-Apps ausführen. Ebenso kann ein arm64-System arm64-, x64- und x86-Apps ausführen. Eine DDLM-Paketüberprüfung ähnelt einer Framework-Überprüfung, mit der Ausnahme, dass sich der PackageType=main unterscheidet und mehr als ein (anderer) Paketfamilienname aufgrund des eindeutigen Benennungsschemas von DDLM anwendbar sein könnte. Weitere Informationen finden Sie in der MSIX-Pakete Spezifikation. Somit sehen die Prüfungen eher so aus:

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

Die obigen Informationen und Code decken das grundlegende Erkennungsszenario ab. Um zu ermitteln, ob die Laufzeit für alle Benutzer bereitgestellt ist, oder ob dies aus einem App-Container und/oder aus einem verpackten mediumIL-Prozess heraus erfolgen soll, ist zusätzliche Logik erforderlich.

Bereitstellungsszenarien

  • Das Windows App SDK Runtime systemweit installieren: Die systemweite Installation verändert das System für alle Benutzer, einschließlich der Konfiguration neuer Benutzer, die in Zukunft hinzugefügt werden. Wenn die App mit erhöhten Rechten ausgeführt wird und der Benutzer, der die Installation durchführt, über Administratorrechte verfügt, registriert das Installationsprogramm die MSIX-Pakete systemweit durch Aufrufen von ProvisionPackageForAllUsersAsync. Wenn die systemweite Registrierung nicht erfolgreich ist, wird die Installation nur für den aktuellen Benutzer ausgeführt, der die Installation vornimmt. In einer verwalteten Unternehmensumgebung sollte der IT-Administrator wie üblich in der Lage sein, die Bereitstellung für alle vorzunehmen.

  • Architectures wird vom Windows App SDK Installer neu verteilt: Das Windows App SDK-Installationsprogramm ist in den Architekturen x86, x64 und Arm64 verfügbar. Jede Version des Installers enthält die MSIX-Pakete für die spezifische Architektur, nach der sie benannt ist. Wenn Sie beispielsweise das x86WindowsAppRuntimeInstall.exe auf einem x64- oder Arm64-Gerät ausführen, installiert dieses x86-Installationsprogramm auf diesem Gerät nur die Pakete für die x86-Architektur.

  • Alle Windows App SDK MSIX-Pakete sind bereits auf dem Computer installiert: MSIX-Pakete werden an einem systemweiten Speicherort mit nur einer Kopie auf dem Datenträger installiert. Wenn eine App versucht, die Windows App SDK zu installieren, wenn alle MSIX-Paketabhängigkeiten bereits auf dem Computer installiert sind, wird die Installation nicht ausgeführt.

  • One oder mehr der Windows App SDK MSIX-Pakete werden nicht auf dem Computer installiert: Versuchen Sie beim Bereitstellen der Windows App SDK immer, alle MSIX-Pakete (Framework, Main, Singleton, DDLM) zu installieren, um sicherzustellen, dass alle Abhängigkeiten installiert sind und Sie Unterbrechungen der Endbenutzerumgebung vermeiden.

Laufzeitanforderungen für mit externem Speicherort gepackte oder ungepackte Apps

Apps, die mit einem externen Speicherort verpackt sind oder entpackt sind, weisen zusätzliche Laufzeitanforderungen auf, um die Windows App SDK Laufzeit zu verwenden. Dies umfasst das Referenzieren und Initialisieren des Windows App SDK-Framework-Pakets zur Laufzeit. Darüber hinaus kann die DYNAMISCHE Abhängigkeits-API verwendet werden, um auf andere Frameworkpakete außerhalb der Windows App SDK zu verweisen.

Verwenden Sie die Windows App-SDK-Laufzeit

Verpackte Apps mit externem Speicherort und entpackte Apps müssen die Bootstrapper-API aufrufen, um die Windows App SDK zur Laufzeit zu verwenden. Dies ist erforderlich, bevor die App Windows App SDK Features wie WinUI, App Lifecycle, MRT Core und DWriteCore verwenden kann. Eine Bootstrapper-Komponente ermöglicht den mit externem Speicherort gepackten und ungepackten Apps die Ausführung dieser wichtigen Aufgaben:

  • Suchen und laden Sie das Windows App SDK Framework-Paket in die Paketstruktur der App.
  • Initialisieren Sie den Dynamic Dependency Lifetime Manager (DDLM) für das Windows App SDK Frameworkpaket. Der Zweck des DDLM besteht darin, die Wartung des Windows App SDK Frameworkpakets zu verhindern, während es von einem Paket mit externem Speicherort oder einer entpackten App verwendet wird.

Der einfachste Weg, die Windows App SDK-Laufzeitumgebung für paketierte Apps mit externem Speicherort und nicht paketierte Apps zu laden, besteht darin, die Eigenschaft <WindowsPackageType>None</WindowsPackageType> in der Projektdatei (.csproj oder .vcxproj) festzulegen. Sie können auch die Bootstrapper-API direkt im Startcode Ihrer App aufrufen, um mehr Kontrolle über die Initialisierung zu haben. Weitere Informationen finden Sie unter Verwenden Sie das Windows-App-SDK-Laufzeitprogramm für Apps, die mit einem externen Speicherort verpackt oder unverpackt sind und Anleitung: Verwenden Sie die Bootstrapper-API in einer App, die mit einem externen Speicherort verpackt oder unverpackt ist und das Windows-App-SDK verwendet.

Die Unterstützung für dynamische Abhängigkeiten ermöglicht es, Anwendungen, die mit externen Speicherorten gepackt oder nicht gepackt sind, ihren bestehenden Bereitstellungsmechanismus wie MSI oder einen beliebigen Installer beizubehalten und die Windows App SDK in der Anwendung zu nutzen. Dynamische Abhängigkeiten können von gepackten, mit externem Speicherort gepackten und ungepackten Apps verwendet werden, obwohl sie in erster Linie für mit externem Speicherort gepackte und ungepackte Apps vorgesehen sind.

Es gibt einen DDLM für jede Version und Architektur des Windows App SDK Frameworkpakets. Dies bedeutet, dass Sie auf einem x64-Computer eine x86- und eine x64-Version des DDLM haben können, damit Apps beider Architekturen unterstützt werden.

Referenzieren anderer Frameworkpakete mit der API für dynamischen Abhängigkeiten

Wenn Sie Features in anderen Framework-Paketen außerhalb des Windows App SDK verwenden möchten (z. B. DirectX), können sowohl verpackte als auch entpackte Apps die Dynamische Abhängigkeits-API aufrufen. Zusätzlich zur Bootstrapperkomponente bietet die Windows App SDK auch eine breitere Gruppe von C/C++-Funktionen und WinRT-Klassen, die die dynamic dependency API implementieren. Diese API ist dafür konzipiert, Framework-Pakete zur Laufzeit dynamisch zu referenzieren.

Weitere Informationen finden Sie unter Dynamisches Verwenden von MSIX-Frameworkpaketen von Ihrer Desktop-App aus und im Beispiel zu dynamischen Abhängigkeiten.

Bereitstellen von .winmd-Dateien auf dem Zielcomputer

Bei Ihrer App empfehlen wir Ihnen, einen Schritt weiter zu gehen und Windows-Metadatendateien (.winmd) bereitzustellen. Metadaten können von verschiedenen APIs und Verhaltensweisen zur Laufzeit verwendet werden, und ihr Fehlen kann die Funktionalität einschränken oder unterbrechen. Beispielsweise können Metadaten zum Marshallen von Objekten über Apartmentgrenzen hinweg verwendet werden. Die Notwendigkeit des Marshallens kann eine Funktion der Computerleistung sein. Da es keinen deterministischen Weg gibt, um festzustellen, ob Sie Metadaten benötigen, sollten Sie .winmd bereitstellen, es sei denn, Sie sind extrem besorgt über die Größe.

  • Last updated on