Windows App SDK guide de déploiement pour les applications dépendantes de l’infrastructure empaquetées avec un emplacement externe ou non empaquetées

Cette rubrique fournit des conseils sur le déploiement d’applications empaquetées avec un emplacement externe, ou non empaquetées, et qui utilisent le Windows App SDK.

  • Ces applications sont des applications de bureau (et non des applications UWP).
  • Ils peuvent être écrits dans un langage .NET tel que C#, ou en C++.
  • Pour leur interface utilisateur, ils peuvent utiliser WinUI 3 ou WPF, WinForms ou un autre framework d’interface utilisateur.

Vue d’ensemble

Les développeurs d’applications empaquetées avec un emplacement externe et d’applications non empaquetées sont responsables du déploiement des packages d’exécution requis du Windows App SDK à leurs utilisateurs finaux. Pour ce faire, exécutez le programme d’installation ou installez directement les packages MSIX. Ces options sont décrites plus en détail dans la section Deploy Windows App SDK runtime ci-dessous.

Les applications empaquetées avec un emplacement externe et les apps non empaquetées ont également des exigences d'exécution supplémentaires. Vous devez initialiser l'accès à l'environnement d'exécution Windows App SDK à l’aide de l’API Bootstrapper. En outre, l’API Dépendances dynamiques peut être utilisée si votre application utilise d’autres packages d’infrastructure en dehors de la Windows App SDK. Ces exigences sont décrites plus en détail dans la section des exigences d'exécution pour les applications empaquetées avec un emplacement externe ou non empaquetées ci-dessous.

Prérequis

Autres composants requis

  • Les versions expérimentales et préliminaires de l’Windows App SDK nécessitent que le chargement indépendant soit activé pour installer le runtime.

    • Le sideloading est automatiquement activé sur Windows 10 version 2004 et ultérieure.

    • Si votre ordinateur de développement ou l’ordinateur de déploiement exécute Windows 11, vérifiez si le chargement indépendant est activé :

      • Paramètres>Confidentialité et sécurité>Pour les développeurs. Assurez-vous que le mode développeur est activé.

    • Si votre ordinateur de développement ou l’ordinateur de déploiement exécute Windows 10 version 1909 ou une version antérieure, vérifiez si le chargement indépendant est activé :

      • Paramètres>Mise à jour et sécurité>Pour les développeurs>Utiliser les fonctionnalités du développeur. Vérifiez que les applications de chargement indépendant ou le mode développeur sont sélectionnés.

    • Le paramètre mode développeur inclut le sideloading ainsi que d’autres fonctionnalités.

      Remarque

      Si l’ordinateur est géré dans un environnement d’entreprise, une stratégie peut empêcher ces paramètres d’être modifiés. Dans ce cas, si vous recevez une erreur lorsque vous ou votre application tente d’installer l’environnement d'exécution Windows App SDK, contactez votre administrateur réseau pour activer le sideloading ou le mode développeur.

Déployer Windows App SDK runtime

Les applications empaquetées avec un emplacement externe et les applications non empaquetées ont deux options pour déployer le moteur d'exécution du Windows App SDK :

Option 1 : Utiliser un programme d'installation

Vous pouvez déployer tous les packages d’exécution Windows App SDK en exécutant le programme d’installation. Le programme d’installation est disponible à Downloads pour le Windows App SDK. Lorsque vous exécutez le programme d'installation (.exe), vous devriez voir un résultat similaire à ce qui suit :

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.

Vous pouvez exécuter le programme d’installation sans interaction utilisateur et supprimer toutes les sorties de texte avec l’option --quiet :

WindowsAppRuntimeInstall.exe --quiet

Vous pouvez également choisir de forcer la mise à jour des packages MSIX et d’arrêter les processus en cours d’exécution Windows App SDK à l’aide de l’option --force. Cette fonctionnalité est introduite dans la version 1.1.

WindowsAppRuntimeInstall.exe --force

Pour consulter toutes les options de ligne de commande du programme d'installation, exécutez WindowsAppRuntimeInstall --h.

Une fois l’installation terminée, vous pouvez exécuter votre package avec un emplacement externe ou une application non empaquetée. Pour obtenir un exemple de génération et d’exécution d’un package avec un emplacement externe ou une application non empaquetée qui utilise le Windows App SDK, consultez Tutorial : Utilisez l’API de programme d’amorçage dans une application empaquetée avec un emplacement externe ou non empaquetée qui utilise le Windows App SDK.

Chaîner le programme d'installation Windows App SDK à la configuration de votre application

Si vous avez un programme d'installation personnalisé pour votre application, vous pouvez chaîner le processus d'installation Windows App SDK dans le processus d'installation de votre application. Actuellement, le programme d'installation du Windows App SDK ne fournit pas d'interface utilisateur par défaut. Vous devrez donc intégrer l'interface utilisateur personnalisée de votre installation.

Vous pouvez lancer et suivre silencieusement la configuration de Windows App SDK tout en affichant votre propre vue de la progression de l’installation à l’aide de ShellExecute. Le programme d’installation Windows App SDK décompresse silencieusement le bundle MSIX Windows App et appelle la méthode PackageManager.AddPackageAsync pour terminer l’installation. Cela est très similaire à d’autres programmes d’installation d’exécution que vous avez peut-être utilisés, comme .NET, Visual C++ou DirectX.

Pour obtenir un exemple de code qui montre comment exécuter le programme d’installation de Windows App SDK à partir de votre programme d’installation, consultez la fonction RunInstaller dans les tests fonctionnels installer.

Exemple de programme d’installation

Consultez l’exemple ci-dessous pour voir comment lancer le programme d’installation à partir d’un programme d’installation Win32 sans afficher une fenêtre de console pendant l’installation :

exemple Explore Installer

Dépannage

Codes de retour

Le tableau suivant répertorie les codes de retour les plus courants pour le programme d’installation Windows App SDK .exe. Les codes de retour sont identiques pour toutes les versions du programme d'installation.

Code de retour Description
0x0 L’installation ou l’approvisionnement du package a été correctement effectué.
0x80073d06 Un ou plusieurs packages n’ont pas pu être installés.
0x80070005 L’installation ou l’approvisionnement à l’échelle du système n’était pas possible, car l’application n’est pas en cours d’exécution avec élévation de privilèges ou l’utilisateur effectuant l’installation n’a pas de privilèges d’administrateur.

Erreurs d’installation

Si le programme d’installation Windows App SDK retourne une erreur pendant l’installation, il retourne un code d’erreur qui décrit le problème.

  • Consultez la liste des codes d’erreur courants.
  • Si le code d’erreur ne fournit pas suffisamment d’informations, vous trouverez plus d’informations de diagnostic dans les journaux d’événements détaillés.
  • Veuillez fichier un problème avec le code d’erreur et les journaux des événements afin que le problème puisse être examiné.

Option 2 : Installer directement les paquets d'exécution du Windows App SDK

En guise d'alternative à l'utilisation du programme d'installation de Windows App SDK pour le déploiement vers les utilisateurs finaux, vous pouvez déployer manuellement les packages MSIX via le programme ou MSI de votre application. Cette option peut être optimale pour les développeurs qui souhaitent plus de contrôle.

Pour obtenir un exemple montrant comment votre programme d’installation peut installer les packages MSIX, consultez install.cpp dans le code du programme d’installation Windows App SDK.

Pour vérifier si le Windows App SDK est déjà installé (et, le cas échéant, quelle version), vous pouvez rechercher des familles de packages spécifiques en appelant PackageManager.FindPackagesForUserWithPackageTypes.

À partir d’un processus medium IL de confiance totale non empaqueté (voir l’élément Application), vous pouvez utiliser le code suivant pour rechercher un package enregistré pour l'utilisateur actuel :

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

Pour le scénario ci-dessus, l’appel de FindPackagesForUserWithPackageTypes est préférable à l’appel de FindPackagesForUser. Cela est dû au fait que vous pouvez limiter la recherche à (pour cet exemple), simplement l’infrastructure ou les packages principaux. Et cela évite de mettre en correspondance d’autres types de packages (par exemple, ressource, facultatif ou bundle) qui ne sont pas intéressants pour cet exemple.

Pour utiliser le contexte utilisateur actuel/appelant, définissez le paramètre userSecurityId sur une chaîne vide.

Et maintenant quelques informations pour vous aider à décider comment appeler la fonction dans l’exemple de code ci-dessus. Un runtime correctement installé se compose de plusieurs packages qui dépendent de l’architecture du processeur du système :

  • Sur une machine x86 : Fwk=[x86], Main=[x86], Singleton=[x86], DDLM=[x86].
  • Sur une machine x64 : Fwk=[x86, x64], Main=[x64], Singleton=[x64], DDLM=[x86, x64].
  • Sur une machine arm64 : Fwk=[x86, x64, arm64], Main=[arm64], Singleton=[arm64], DDLM=[x86, x64, arm64].

Pour les packages Main et Singleton , leur architecture doit correspondre à l’architecture du processeur du système ; par exemple, les packages x64 sur un système x64. Pour le package Framework, un système x64 peut exécuter simultanément des applications x64 et x86 ; de même, un système arm64 peut exécuter simultanément des applications arm64, x64 et x86. Une vérification de package DDLM est similaire à une vérification du Framework, sauf que PackageType=main, et le packagefamilyname diffère, et plusieurs (différents) packagefamilyname peuvent être applicables, en raison de l’unicité du schéma de nommage de DDLM. Pour plus d'informations, consultez la documentation des paquets MSIX. Les vérifications sont donc plus similaires à cela :

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

Les informations et le code ci-dessus couvrent le scénario de détection de base. Pour détecter si le runtime est approvisionné pour tous les utilisateurs, ou pour effectuer les actions ci-dessus à partir d’un conteneur d’applications et/ou d’un processus package mediumIL, une logique supplémentaire est nécessaire.

Scénarios de déploiement

  • Installation de l’Windows App SDK runtime à l’échelle du système : l’installation à l’échelle du système modifie la machine pour tous les utilisateurs, y compris les nouveaux utilisateurs ajoutés à l’avenir. Si l’application est en cours d’exécution avec élévation de privilèges et que l’utilisateur effectuant l’installation dispose de privilèges d’administrateur, le programme d’installation inscrit les packages MSIX à l’échelle du système en appelant ProvisionPackageForAllUsersAsync. Si l’inscription à l’échelle du système n’est pas réussie, l’installation est effectuée pour l’utilisateur actuel qui effectue l’installation uniquement. Dans un environnement d’entreprise géré, l’administrateur informatique doit être en mesure de provisionner tous les utilisateurs comme d’habitude.

  • Architectures redistribuées par le programme d’installation de Windows App SDK : le programme d’installation Windows App SDK est disponible dans les architectures x86, x64 et Arm64. Chaque version du programme d’installation inclut les packages MSIX uniquement pour l’architecture spécifique dont il est nommé. Par exemple, si vous exécutez x86WindowsAppRuntimeInstall.exe sur un appareil x64 ou Arm64, ce programme d’installation x86 déploiera uniquement les paquets de l’architecture x86 sur cet appareil.

  • Tous les packages MSIX Windows App SDK sont déjà installés sur l’ordinateur : les packages MSIX sont installés dans un emplacement à l’échelle du système avec une seule copie sur le disque. Si une application tente d’installer le Windows App SDK lorsque toutes les dépendances de package MSIX sont déjà installées sur l’ordinateur, l’installation n’est pas effectuée.

  • One ou plusieurs packages MSIX Windows App SDK ne sont pas installés sur l’ordinateur : lors du déploiement du Windows App SDK, essayez toujours d’installer tous les packages MSIX (framework, principal, singleton, DDLM) pour vous assurer que toutes les dépendances sont installées et que vous évitez toute interruption de l’expérience de l’utilisateur final.

Exigences d'exécution pour les applications packagées avec un emplacement externe ou non packagées.

Les applications empaquetées avec un emplacement externe ou non empaquetées ont des exigences de runtime supplémentaires pour utiliser le runtime Windows App SDK. Cela implique le référencement et l’initialisation du package Windows App SDK Framework au moment de l’exécution. En outre, l’API Dépendances dynamiques peut être utilisée pour référencer d’autres packages d’infrastructure en dehors de la Windows App SDK.

Utiliser le runtime Windows App SDK

Les applications empaquetées avec un emplacement externe et les applications non empaquetées doivent appeler l’API Bootstrapper pour utiliser le SDK d'application Windows à l'exécution. Cela est nécessaire pour que l’application puisse utiliser Windows App SDK fonctionnalités telles que WinUI, Cycle de vie des applications, MRT Core et DWriteCore. Un composant bootstrapper permet aux applications empaquetées avec un emplacement externe et aux applications non empaquetées de réaliser ces tâches importantes :

  • Recherchez et chargez le package d'infrastructure Windows App SDK sur le graphique de package de l'application.
  • Initialisez le Gestionnaire de durée de vie des dépendances dynamiques (DDLM) pour le package d’infrastructure Windows App SDK. L’objectif du DDLM est d’empêcher la maintenance du package d’infrastructure Windows App SDK alors qu’il est utilisé par un package avec un emplacement externe ou une application non empaquetée.

Le moyen le plus simple de charger le runtime Windows App SDK pour les applications empaquetées avec une localisation externe et les applications non empaquetées est en définissant la propriété <WindowsPackageType>None</WindowsPackageType> dans votre fichier de projet (.csproj ou .vcxproj). Vous pouvez également appeler l’API de démarrage directement dans le code de démarrage de votre application pour plus de contrôle sur l’initialisation. Pour plus d’informations, consultez Utilisez le runtime Windows App SDK pour les applications empaquetées avec un emplacement externe ou non empaquetés et Tutorial : Utilisez l’API de démarrage dans une application empaquetée avec un emplacement externe ou non empaquetée qui utilise le Windows App SDK.

La prise en charge des Dynamic Dependencies permet aux applications empaquetées avec des dépendances externes et aux applications non empaquetées de garder leur mécanisme de déploiement existant, comme MSI ou tout autre programme d'installation, tout en pouvant tirer parti de Windows App SDK dans leur application. Les dépendances dynamiques peuvent être utilisées par des applications empaquetées, empaquetées avec un emplacement externe, et non empaquetées ; bien qu'elles soient principalement destinées à être utilisées par des applications empaquetées avec un emplacement externe et non empaquetées.

Il existe une DDLM pour chaque version et architecture du package d’infrastructure Windows App SDK. Cela signifie que sur un x64 ordinateur, vous pouvez avoir à la fois une version x86 et une version x64 de DDLM pour prendre en charge les applications des deux architectures.

Référencer d’autres packages d’infrastructure à l’aide de l’API Dépendances dynamiques

Pour utiliser des fonctionnalités dans d'autres packages de framework en dehors de la Windows App SDK (par exemple, DirectX), les applications empaquetées avec un emplacement externe et les applications non empaquetées peuvent appeler l'API Dépendances dynamiques. Outre le composant de programme d’amorçage, le Windows App SDK fournit également un ensemble plus large de fonctions C/C++ et de classes WinRT qui implémentent l’API de dépendance dynamic dependency API. Cette API est conçue pour être utilisée pour référencer dynamiquement n’importe quel package d’infrastructure au moment de l’exécution.

Pour plus d’informations, consultez Utilisation dynamique de packages d’infrastructure MSIX à partir d’une application bureautique et l'exemple de dépendances dynamiques

Déployer des fichiers .winmd sur l’ordinateur cible

En plus de votre application, nous vous recommandons d’aller de l’avant et de déployer des fichiers de métadonnées Windows (.winmd). Les métadonnées peuvent être utilisées par diverses API et comportements au moment de l’exécution, et son absence peut limiter ou interrompre les fonctionnalités. Par exemple, les métadonnées peuvent être utilisées pour marshaliser des objets à travers des limites de compartiments ; et le besoin de marshaliser peut dépendre des performances de la machine. Étant donné qu'il n'existe pas de moyen précis de savoir si vous avez besoin de métadonnées, vous devriez déployer .winmds, sauf si vous êtes extrêmement préoccupé par la taille.

  • Last updated on