Teilen über

Windows App SDK-Bereitstellungsleitfaden für von Framework abhängige gepackte Apps mit externem Speicherort oder nicht gepackte Apps

  • Artikel

Dieses Thema enthält Anleitungen zum Bereitstellen von mit externem Speicherort gepackten Apps oder ungepackten Apps, die 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, WPF oder WinForms oder ein anderes Benutzeroberflächenframework verwenden.

Übersicht

Entwickler von mit externem Speicherort gepackten und ungepackten Apps sind für die Bereitstellung erforderlicher Windows App SDK-Laufzeitpakete für ihre Endbenutzer verantwortlich. Das kann entweder durch Ausführen des Installationsprogramms oder durch direkte Installation der MSIX-Pakete erfolgen. Diese Optionen werden im Abschnitt Bereitstellen der Windows App SDK-Laufzeit weiter unten ausführlicher 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 über die Bootstrapper-API initialisieren. Darüber hinaus kann die API für dynamische Abhängigkeiten eingesetzt werden, wenn Ihre App noch andere Frameworkpakete außerhalb des Windows App SDK verwendet. Diese Anforderungen werden im Abschnitt Laufzeitanforderungen für mit externem Speicherort gepackte oder ungepackte Apps weiter unten ausführlicher beschrieben.

Voraussetzungen

Zusätzliche Voraussetzungen

  • Für experimentelle Versionen und Vorschauversionen des Windows App SDK muss zum Installieren der Laufzeit das Querladen aktiviert sein.

    • Unter Windows 10, Version 2004 und höher, wird das Querladen automatisch aktiviert.

    • Wenn Ihr Entwicklungscomputer oder der Bereitstellungscomputer unter Windows 11 läuft, sollten Sie überprüfen, ob das Querladen aktiviert ist:

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

    • Wenn Ihr Entwicklungscomputer oder der Bereitstellungscomputer unter Windows 10 Version 1909 oder früher läuft, sollten Sie überprüfen, 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. Wenn Sie in diesem Fall eine Fehlermeldung erhalten, wenn von Ihnen oder Ihrer App versucht wird, 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

Für mit externem Speicherort gepackte und ungepackte Apps gibt es zwei Optionen zum Bereitstellen der Windows App SDK-Laufzeit:

Option 1: Verwenden des Installationsprogramms

Sie können alle Windows App SDK-Laufzeitpakete durch Ausführen des Installationsprogramms bereitstellen. Das Installationsprogramm steht unter Downloads für das Windows App SDK zur Verfügung. 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

Außerdem können Sie über die Option --force die Aktualisierung der MSIX-Pakete erzwingen und alle gerade laufenden Windows App SDK-Prozesse 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 einer mit externem Speicherort gepackten App oder einer ungepackten App, die Windows App SDK verwendet, finden Sie im Tutorial: Verwenden der Bootstrapping-API in einer gepackten App mit externem Speicherort oder nicht gepackten App, die Windows App SDK verwendet.

Verketten des Windows App SDK-Installationsprogramms mit dem Setup Ihrer App

Wenn Sie ein benutzerdefiniertes Setupprogramm für die App haben, können Sie den Windows App SDK-Setupvorgang mit dem Setupvorgang der App verketten (in das Setup einschließen). Das Windows App SDK-Installationsprogramm verfügt derzeit nicht über eine Standardbenutzeroberfläche, sodass Sie die Verkettung über die benutzerdefinierte Benutzeroberfläche Ihres Setups vornehmen müssen.

Sie können das Windows App SDK-Setup im Hintergrund starten und nachverfolgen und währenddessen ihre eigene Ansicht des Setupfortschritts über ShellExecute anzeigen. Das Windows App SDK-Installationsprogramm entpackt das Windows-App MSIX-Bündel im Hintergrund und ruft zum Abschließen der Installation die PackageManager.AddPackageAsync-Methode auf. Das ist ganz ähnlich wie bei anderen Laufzeitinstallationsprogrammen, die Sie vielleicht schon verwendet haben, z. B. .NET, Visual C++ oder DirectX.

Ein Codebeispiel, das veranschaulicht, wie das Windows App SDK-Installationsprogramm aus Ihrem Setupprogramm ausgeführt wird, finden Sie unter der Funktion RunInstaller in den Funktionstests für das Installationsprogramm.

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:

Erkunden des Beispiels zum Installationsprogramm

Problembehandlung

Rückgabecodes

In der folgenden Tabelle sind die gängigsten Rückgabecodes für das .exe-Installationsprogramm des Windows App SDK 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 das Windows App SDK-Installationsprogramm während der Installation einen Fehler zurückgibt, wird ein Fehlercode zurückgegeben, der das Problem beschreibt.

Option 2: Direktes Bereitstellen von Windows App SDK-Laufzeitpaketen

Als Alternative zur Verwendung des Windows App SDK-Installationsprogramms für die Bereitstellung für Endbenutzer können Sie die MSIX-Pakete über das Programm Ihrer App oder den MSI manuell 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 Code des Windows App SDK-Installationsprogramms.

Um zu überprüfen, ob das 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 auf (in diesem Beispiel) nur auf Framework oder 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 PackageType=mainsich der Paketamilyname unterscheidet, und mehr als ein (anderer) Paketfamilyname aufgrund des eindeutigen Benennungsschemas von DDLM anwendbar sein könnte. Weitere Informationen finden Sie in der MSIX-Paketspezifikation . Die Prüfungen sind also mehr wie folgt:

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 wird oder ob sie von einem App-Container ausgeführt werden soll und/oder ob sie aus einem verpackten mediumIL Prozess ausgeführt wird, ist zusätzliche Logik erforderlich.

Bereitstellungsszenarien

  • Systemweites Installieren der Windows App SDK-Laufzeit: Die systemweite Installation verändert den Computer für alle Benutzer, auch für neue 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.

  • Vom Windows App SDK-Installationsprogramm verteilte Architekturen: Das Windows App SDK-Installationsprogramm ist in den x86, x64und Arm64 Architekturen 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 x86 WindowsAppRuntimeInstall.exe Gerät auf einem x64- oder Arm64-Gerät ausführen, stellt dieses x86 Installationsprogramm nur die Pakete für die x86-Architektur auf diesem Gerät bereit.

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

  • Mindestens ein Windows App SDK-MSIX-Paket ist nicht auf dem Computer installiert: Beim Bereitstellen des Windows App SDK müssen Sie immer versuchen, alle MSIX-Pakete (Framework, Standard, Singleton, DDLM) zu installieren, um sicherzustellen, dass alle Abhängigkeiten installiert und Unterbrechungen der Endbenutzerumgebung vermieden werden.

Laufzeitanforderungen für mit externem Speicherort gepackte oder ungepackte Apps

Für mit externem Speicherort gepackte oder ungepackte Apps gelten zusätzliche Laufzeitanforderungen für die Verwendung der Windows App SDK-Laufzeit. Dazu gehört das Referenzieren und Initialisieren des Windows App SDK-Frameworkpakets zur Laufzeit. Darüber hinaus kann die API für dynamische Abhängigkeiten zum Referenzieren anderer Frameworkpakete außerhalb der Windows App SDK eingesetzt werden.

Verwenden der Windows App SDK-Laufzeit

Mit externem Speicherort gepackte und ungepackte Apps müssen zum Verwenden der Windows App SDK zur Laufzeit die Bootstrapper-API aufrufen. Das ist erforderlich, bevor Windows App SDK-Features wie WinUI, App-Lebenszyklus, MRT Core und DWriteCore von der App verwendet werden können. Eine Bootstrapper-Komponente ermöglicht den mit externem Speicherort gepackten und ungepackten Apps die Ausführung dieser wichtigen Aufgaben:

  • Suchen des Windows App SDK-Frameworkpakets und Laden in das Paketdiagramm der App.
  • Initialisieren des 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 einer mit externem Speicherort gepackten oder ungepackten App verwendet wird.

Die einfachste Möglichkeit, die Windows App SDK-Laufzeit für mit externem Speicherort gepackte und ungepackte Apps zu laden, ist das Festlegen der Eigenschaft <WindowsPackageType>None</WindowsPackageType> in der Projektdatei (.csproj or .vcxproj). 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 der Windows App SDK-Runtime für gepackte Apps mit externem Speicherort oder nicht gepackte Apps sowie unter Tutorial: Verwenden der Bootstrapping-API in einer gepackten App mit externem Speicherort oder nicht gepackten App, die Windows App SDK verwendet.

Die Unterstützung dynamischer Abhängigkeiten ermöglicht den mit externem Speicherort gepackten und ungepackten Apps das Beibehalten ihres vorhandenen Bereitstellungsmechanismus wie MSI oder eines Installationsprogramms und die Nutzung des Windows App SDK in ihrer Anwendung. 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 Frameworkpaketen außerhalb des Windows App SDK (z. B. DirectX) verwenden möchten, können mit externem Speicherort gepackte und ungepackte Apps die API für dynamische Abhängigkeiten aufrufen. Zusätzlich zur Bootstrapper-Komponente verfügt das Windows App SDK auch über umfangreichere C/C++-Funktionen und WinRT-Klassen, die die API für dynamische Abhängigkeiten implementieren. Diese API wurde für die dynamische Referenzierung von Frameworkpaketen zur Laufzeit entwickelt.

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 sich nicht eindeutig feststellen lässt, ob Sie Metadaten benötigen, sollten Sie .winmd bereitstellen, es sei denn, die Größe ist ein erhebliches Problem für Sie.