Partage via


Guide de déploiement du SDK d’application Windows 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 Kit de développement logiciel (SDK) d’application Windows.

  • 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, WPF ou WinForms ou un autre framework d’interface utilisateur.

Vue d’ensemble

Les développeurs d’applications empaquetées avec un emplacement externe et des applications non empaquetées sont responsables du déploiement des packages d’exécution du Kit de développement logiciel (SDK) d’application Windows requis pour 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 Déployer le runtime du Kit de développement logiciel (SDK) d’application Windows ci-dessous.

Empaqueté avec un emplacement externe et des applications non empaquetées ont également des exigences supplémentaires en matière d’exécution. Vous devez initialiser l’accès au runtime du Kit de développement logiciel (SDK) d’application Windows à 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 du Kit de développement logiciel (SDK) d’application Windows. Ces exigences sont décrites plus en détail dans la configuration requise pour le runtime pour les applications empaquetées avec un emplacement externe ou une section non empaquetée ci-dessous.

Prérequis

Autres composants requis

  • Les versions expérimentales et préliminaires du Kit de développement logiciel (SDK) d’application Windows nécessitent que le chargement indépendant soit activé pour installer le runtime.
    • Le chargement indépendant 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 de mode développeur inclut le chargement indépendant 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 le runtime du Kit de développement logiciel (SDK) d’application Windows, contactez votre professionnel de l’informatique pour activer le chargement indépendant ou le mode développeur.

Déployer le runtime du Kit de développement logiciel (SDK) d’application Windows

Empaquetées à l’aide d’un emplacement externe et d’applications non empaquetées ont deux options pour déployer le runtime du Kit de développement logiciel (SDK) d’application Windows :

  • Option 1 : Utiliser le programme d’installation : le programme d’installation silencieux distribue tous les packages MSIX du SDK d’application Windows. Un programme d’installation distinct est disponible pour chacune des X64X86 architectures et Arm64 des architectures.
  • Option 2 : Installez les packages directement : vous pouvez disposer de votre outil d’installation ou MSI existant et installer les packages MSIX pour le Kit de développement logiciel (SDK) d’application Windows.

Option 1 : Utiliser un programme d'installation

Vous pouvez déployer tous les packages d’exécution du Kit de développement logiciel (SDK) d’application Windows en exécutant le programme d’installation. Le programme d’installation est disponible aux téléchargements pour le Kit de développement logiciel (SDK) d’application Windows. Lorsque vous exécutez l’programme d'installation (.exe), vous pouvez voir une sortie similaire à l’erreur suivante :

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 du SDK d’application Windows en cours d’exécution à l’aide de l’option --force. Cette fonctionnalité est introduite dans .

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 un exemple de construction et d'exécution d'une application packagée avec un emplacement externe ou non packagée qui utilise le SDK d'application Windows, consultez Tutoriel : Utiliser l'API bootstrapper dans une application packagée avec un emplacement externe ou non packagée qui utilise SDK d'application Windows.

Chaîner le programme d’installation du Kit de développement logiciel (SDK) d’application Windows à la configuration de votre application

Si vous créez un programme d'installation personnalisée pour votre application, vous pouvez chaîner (inclure) le processus d'installation du .NET Framework dans le processus d'installation de votre application. Actuellement, le programme d’installation du Kit de développement logiciel (SDK) d’application Windows ne fournit pas d’interface utilisateur par défaut. Vous devrez donc chaîner à l’aide de l’interface utilisateur personnalisée de votre installation.

Vous pouvez lancer et suivre silencieusement la configuration du Kit de développement logiciel (SDK) d’application Windows tout en affichant votre propre vue de la progression de l’installation à l’aide de ShellExecute. Le programme d’installation du Kit de développement logiciel (SDK) d’application Windows décompresse silencieusement le bundle MSIX de l’application Windows 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, tels que .NET, Visual C++ou DirectX.

Pour obtenir un exemple de code qui montre comment exécuter le programme d’installation du Kit de développement logiciel (SDK) d’application Windows à partir de votre programme d’installation, consultez la fonction RunInstaller dans les tests fonctionnels du programme d’installation.

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 :

Dépannage

Codes de retour

Le tableau suivant répertorie les codes de retour les plus courants pour le programme d’installation .exe du Kit de développement logiciel (SDK) d’application Windows. 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 du Kit de développement logiciel (SDK) d’application Windows 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.
  • Envoyez un problème avec le code d’erreur et les journaux des événements afin que le problème puisse être examiné.

Option 2 : Déployer directement les packages d’exécution du Kit de développement logiciel (SDK) d’application Windows

En guise d’alternative à l’utilisation du programme d’installation du Kit de développement logiciel (SDK) d’application Windows 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 qui montre comment votre programme d’installation peut installer les packages MSIX, consultez install.cpp dans le code du programme d’installation du Kit de développement logiciel (SDK) d’application Windows.

Pour vérifier si le SDK d’application Windows 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 non empaqueté mediumIL (voir l’élément Application), vous pouvez utiliser le code suivant pour rechercher un package inscrit à 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 à la fois des applications x64 et x86 ; de même, un système arm64 peut exécuter arm64, x64 et les applications x86. Une vérification de package DDLM est similaire à une vérification de l’infrastructure, sauf que PackageType=main, et le packagefamilyname diffère, et plusieurs (différents) packagefamilyname peuvent être applicables, en raison du schéma d’affectation de noms unique de DDLM. Pour plus d’informations, consultez la spécification des packages MSIX. Les vérifications sont donc plus similaires à ceci :

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 le faire à partir d’un processus empaqueté mediumIL , une logique supplémentaire est nécessaire.

Scénarios de déploiement

  • L’installation du runtime du SDK d’application Windows à l’échelle du système : l’installation à l’échelle du système modifie la machine pour tous les utilisateurs, y compris les nouveaux utilisateurs qui sont 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 du Kit de développement logiciel (SDK) d’application Windows : le programme d’installation du Kit de développement logiciel (SDK) d’application Windows est disponible dans les architectures et Arm64 les x86x64architectures. 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 l’appareil x86 WindowsAppRuntimeInstall.exe x64 ou Arm64, ce x86 programme d’installation se déploie sur cet appareil uniquement les packages de l’architecture x86.

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

  • Un ou plusieurs packages MSIX du Kit de développement logiciel (SDK) d’application Windows ne sont pas installés sur l’ordinateur : lors du déploiement du Kit de développement logiciel (SDK) d’application Windows, 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 utilisateur final.

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 du Kit de développement logiciel (SDK) d’application Windows. Cela implique de référencer et d’initialiser le 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 du Kit de développement logiciel (SDK) d’application Windows.

Utiliser le runtime SDK d’application Windows

Empaqueté avec un emplacement externe et des applications non empaquetées doivent appeler l’API bootstrapper pour utiliser le Kit de développement logiciel (SDK) d’application Windows au moment de l’exécution. Cette opération est requise pour que l’application puisse utiliser des fonctionnalités du Kit de développement logiciel (SDK) d’application Windows telles que WinUI, Cycle de vie des applications, MRT Core et DWriteCore. Un composant de programme d’amorçage permet d’empaquetager avec un emplacement externe et des applications non empaquetées pour effectuer ces tâches importantes :

  • Recherchez et chargez le package d’infrastructure du Kit de développement logiciel (SDK) d’application Windows dans le graphe de package de l’application.
  • Initialisez le Gestionnaire de durée de vie des dépendances dynamiques (DDLM) pour le package d’infrastructure du Kit de développement logiciel (SDK) d’application Windows. L’objectif du DDLM est d’empêcher la maintenance du package d’infrastructure du Kit de développement logiciel (SDK) d’application Windows lorsqu’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 du Kit de développement logiciel (SDK) d’application Windows pour empaqueté avec un emplacement externe et des applications non empaquetées consiste à définir la <WindowsPackageType>None</WindowsPackageType> propriété dans votre fichier 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 Utiliser le runtime du SDK d'application Windows pour les applications packagées avec un emplacement externe ou non packagées et Didacticiel : utiliser l’API du programme d’amorçage dans une application packagée avec un emplacement externe ou non packagée qui utilise le SDK d'application Windows.

La prise en charge des dépendances dynamiques permet d’empaqueté avec un emplacement externe et des applications non empaquetées de conserver leur mécanisme de déploiement existant, tel que MSI ou tout programme d’installation, et de pouvoir tirer parti du SDK d’application Windows dans leur application. Les dépendances dynamiques peuvent être utilisées par empaquetées, empaquetées à l’aide d’un emplacement externe et d’applications non empaquetées ; bien qu’il soit principalement destiné à être utilisé par empaquetage avec un emplacement externe et des applications non empaquetées.

Il existe une DDLM pour chaque version et architecture du package d’infrastructure du SDK d’application Windows. Cela signifie que sur un x64 ordinateur, vous pouvez avoir à la fois une version et une x86 x64 version 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

Si vous souhaitez utiliser des fonctionnalités dans d’autres packages d’infrastructure en dehors du Kit de développement logiciel (SDK) de l’application Windows (par exemple, DirectX), empaquetées avec un emplacement externe et des applications non empaquetées peuvent appeler l’API Dépendances dynamiques. Outre le composant de programme d’amorçage, le SDK d’application Windows fournit également un ensemble plus large de fonctions C/C++ et de classes WinRT qui implémentent l’API de dépendance dynamique. 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 marshaler des objets à travers des limites d’appartements ; et la nécessité de marshaler peut être une fonction des performances de l’ordinateur. Étant donné qu’il n’existe aucun moyen déterministe de savoir si vous avez besoin de métadonnées, vous devez déployer .winmds’il n’est pas extrêmement préoccupé par la taille.