Accorder une identité de package en empaquetant avec un emplacement externe

  • Article

Si vous avez une application de bureau existante avec son propre programme d’installation, très peu de modifications sont nécessaires pour tirer parti de l’identité de package.

De nombreuses fonctionnalités d'extensibilité de Windows—notamment les mosaïques en arrière-plan, les notifications, les vignettes dynamiques, les extensions de menu contextuel personnalisées et les cibles de partage—peuvent être utilisées par une application de bureau uniquement si cette application possède une identité de package au moment de l'exécution. Ceci est dû au fait que le système d’exploitation doit être en mesure d’identifier l’appelant de l’API correspondante. Consultez Fonctionnalités nécessitant une identité de package.

Seules les applications empaquetées ont une identité de package au moment de l’exécution. Pour connaître les définitions d’applications empaquetées, non empaquetées et empaquetées avec un emplacement externe, consultez Vue d’ensemble du déploiement.

  • Dans Windows 10 version 2004 et antérieur, la seule façon d’accorder une identité de package à une application est de l’empaqueter dans un package MSIX signé (consultez Création d’un package MSIX à partir de votre code). Dans ce cas, l’identité est spécifiée dans le manifeste du package et l’inscription de l’identité est gérée par le pipeline de déploiement MSIX en fonction des informations contenues dans le manifeste. Tout le contenu référencé dans le manifeste du package est présent dans le package MSIX.
  • Mais à compter de Windows 10 version 2004, vous pouvez accorder une identité de package à une application simplement en créant et en inscrivant un package avec un emplacement externe auprès de votre application. Ceci la transforme en application empaquetée, plus précisément en une application empaquetée avec un emplacement externe. C’est parce que certaines applications de bureau ne sont pas encore prêtes pour que tout leur contenu soit présent à l’intérieur d’un package MSIX. Ainsi, cette prise en charge permet à ces applications d’avoir une identité de package, ce qui leur permet d’utiliser des fonctionnalités d’extensibilité Windows qui nécessitent une identité de package. Pour plus d’informations, consultez le billet de blog Identité, inscription et activation des applications Win32 non empaquetées.

Pour créer et inscrire un package avec un emplacement externe (qui accorde une identité de package à votre application), suivez ces étapes.

  1. Créer un manifeste de package pour le package avec un emplacement externe
  2. Créer et signer le package avec un emplacement externe
  3. Ajouter les métadonnées d’identité de package au manifeste de votre application de bureau
  4. Inscrire votre package avec un emplacement externe au moment de l’exécution

Concepts importants

Les fonctionnalités suivantes permettent aux applications de bureau non empaquetées d’acquérir une identité de package.

Package avec un emplacement externe

Un package avec un emplacement externe contient un manifeste de package, mais aucun autre fichier binaire et contenu d’application. Le manifeste d’un package avec un emplacement externe peut référencer des fichiers extérieurs au package à un emplacement externe prédéterminé. Comme mentionné ci-dessus, cette prise en charge permet aux applications qui ne sont pas encore prêtes pour que tout leur contenu soit présent à l’intérieur d’un package MSIX d’utiliser les fonctionnalités d’extensibilité Windows qui nécessitent une identité de package.

Note

Une application de bureau utilisant un package avec un emplacement externe ne bénéficie pas de tous les avantages d’un déploiement complet via un package MSIX. Parmi ces avantages figurent la protection contre les falsifications, l’installation dans un emplacement verrouillé et la gestion complète par le système d’exploitation du déploiement, de l’exécution et de la désinstallation.

Autoriser le contenu externe

Pour prendre en charge les packages avec un emplacement externe, le schéma du manifeste de package prend maintenant en charge un élément uap10:AllowExternalContent facultatif sous l’élément Properties. Le manifeste de votre package peut ainsi référencer du contenu en dehors du package, à un emplacement spécifique sur le disque.

Par exemple, si votre application de bureau non empaquetée installe le fichier exécutable et d’autres contenus de l’application dans C:\Program Files\MyDesktopApp, vous pouvez créer un package avec un emplacement externe incluant l’élément uap10:AllowExternalContent dans le manifeste. Lors du processus d’installation de votre application ou lors de sa première exécution, vous pouvez installer le package avec un emplacement externe et déclarer C:\Program Files\MyDesktopApp\ comme emplacement externe utilisé par votre application.

Créer un manifeste de package pour le package avec un emplacement externe

Avant de pouvoir créer un package avec un emplacement externe, vous devez d’abord créer un manifeste de package (un fichier nommé AppxManifest.xml) qui déclare les métadonnées d’identité de package pour votre application de bureau ainsi que d’autres informations nécessaires. Pour créer un manifeste de package pour le package avec un emplacement externe, le plus simple est d’utiliser l’exemple ci-dessous et de le personnaliser pour votre application en utilisant la référence de schéma.

Le manifeste de package doit comprendre les éléments suivants :

  • Un élément Identity décrivant les attributs d’identité de votre application de bureau.
  • Un élément uap10:AllowExternalContent sous l’élément Properties. La valeur true doit être affectée à cet élément pour permettre au manifeste de votre package de référencer du contenu en dehors du package, à un emplacement spécifique sur le disque. Dans une étape ultérieure, vous allez spécifier le chemin de cet emplacement externe quand vous inscrivez votre package avec un emplacement externe à partir du code exécuté dans votre programme d’installation ou votre application. Tout contenu référencé dans le manifeste et absent du package doit être installé à l’emplacement externe.
  • L’attribut MinVersion de l’élément TargetDeviceFamily doit être défini avec 10.0.19000.0 ou version ultérieure.
  • Les attributs TrustLevel=mediumIL et RuntimeBehavior = Win32App de l’élément Application déclarent que l’application de bureau associée au package avec un emplacement externe s’exécutera de la même façon qu’une application de bureau non empaquetée standard, sans virtualisation du registre et du système de fichiers, et d’autres modifications de l’exécution.

L’exemple suivant montre le contenu complet d’un manifeste de package avec un emplacement externe (AppxManifest.xml). Ce manifeste comprend une extension windows.sharetarget, nécessitant une identité de package.

<?xml version="1.0" encoding="utf-8"?>
<Package 
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:uap2="http://schemas.microsoft.com/appx/manifest/uap/windows10/2"
  xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
  xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
  xmlns:uap10="http://schemas.microsoft.com/appx/manifest/uap/windows10/10"
  IgnorableNamespaces="uap uap2 uap3 rescap desktop uap10">
  <Identity Name="ContosoPhotoStore" ProcessorArchitecture="x64" Publisher="CN=Contoso" Version="1.0.0.0" />
  <Properties>
    <DisplayName>ContosoPhotoStore</DisplayName>
    <PublisherDisplayName>Contoso</PublisherDisplayName>
    <Logo>Assets\storelogo.png</Logo>
    <uap10:AllowExternalContent>true</uap10:AllowExternalContent>
  </Properties>
  <Resources>
    <Resource Language="en-us" />
  </Resources>
  <Dependencies>
    <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.19000.0" MaxVersionTested="10.0.19000.0" />
  </Dependencies>
  <Capabilities>
    <rescap:Capability Name="runFullTrust" />
    <rescap:Capability Name="unvirtualizedResources"/>
  </Capabilities>
  <Applications>
    <Application Id="ContosoPhotoStore" Executable="ContosoPhotoStore.exe" uap10:TrustLevel="mediumIL" uap10:RuntimeBehavior="win32App"> 
      <uap:VisualElements AppListEntry="none" DisplayName="Contoso PhotoStore" Description="Demonstrate photo app" BackgroundColor="transparent" Square150x150Logo="Assets\Square150x150Logo.png" Square44x44Logo="Assets\Square44x44Logo.png">
        <uap:DefaultTile Wide310x150Logo="Assets\Wide310x150Logo.png" Square310x310Logo="Assets\LargeTile.png" Square71x71Logo="Assets\SmallTile.png"></uap:DefaultTile>
        <uap:SplashScreen Image="Assets\SplashScreen.png" />
      </uap:VisualElements>
      <Extensions>
        <uap:Extension Category="windows.shareTarget">
          <uap:ShareTarget Description="Send to ContosoPhotoStore">
            <uap:SupportedFileTypes>
              <uap:FileType>.jpg</uap:FileType>
              <uap:FileType>.png</uap:FileType>
              <uap:FileType>.gif</uap:FileType>
            </uap:SupportedFileTypes>
            <uap:DataFormat>StorageItems</uap:DataFormat>
            <uap:DataFormat>Bitmap</uap:DataFormat>
          </uap:ShareTarget>
        </uap:Extension>
      </Extensions>
    </Application>
  </Applications>
</Package>

Créer et signer le package avec un emplacement externe

Une fois le manifeste de votre package créé, générez le package avec un emplacement externe en utilisant l’outil MakeAppx.exe du SDK Windows. Le package avec un emplacement externe ne contenant pas les fichiers référencés dans le manifeste, vous devez spécifier l’option /nv, qui ignore la validation sémantique pour le package.

L’exemple suivant montre comment créer un package avec un emplacement externe à partir de la ligne de commande.

MakeAppx.exe pack /d <path to directory that contains manifest> /p <output path>\MyPackage.msix /nv

Pour installer votre package avec un emplacement externe sur un ordinateur cible, vous devez le signer en utilisant un certificat approuvé sur l’ordinateur cible. Vous pouvez créer un certificat auto-signé à des fins de développement et signer votre package avec un emplacement externe en utilisant SignTool, qui est disponible dans le SDK Windows.

L’exemple suivant montre comment signer un package avec un emplacement externe à partir de la ligne de commande.

SignTool.exe sign /fd SHA256 /a /f <path to certificate>\MyCertificate.pfx /p <certificate password> <path to package with external location>\MyPackage.msix

Ajouter les métadonnées d’identité du package au manifeste de votre application de bureau

Vous devez aussi inclure un manifeste de l’application avec votre application de bureau. Consultez les manifestes d’application (il s’agit du fichier qui déclare des éléments tels que la prise en charge du DPI et qui est incorporé dans le .exe de votre application pendant la compilation). Dans ce fichier, incluez un élément msix avec des attributs qui déclarent les attributs d’identité de votre application. Les valeurs de ces attributs sont utilisées par le système d’exploitation pour déterminer l’identité de votre application lors du lancement du fichier exécutable.

L’exemple suivant montre un manifeste d’application côte à côte avec un élément msix.

<?xml version="1.0" encoding="utf-8"?>
<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
  <assemblyIdentity version="1.0.0.0" name="Contoso.PhotoStoreApp"/>
  <msix xmlns="urn:schemas-microsoft-com:msix.v1"
          publisher="CN=Contoso"
          packageName="ContosoPhotoStore"
          applicationId="ContosoPhotoStore"
        />
</assembly>

Les attributs de l’élément msix doivent correspondre à ces valeurs dans le manifeste de package de votre package avec un emplacement externe :

  • Les attributs packageName et publisher doivent correspondre aux attributs Name et Publisher de l’élément Identity du manifeste de votre package.
  • L’attribut applicationId doit correspondre à l’attribut Id de l’élément Application du manifeste de votre application.

Inscrire votre package avec un emplacement externe au moment de l’exécution

Pour accorder une identité de package à votre application de bureau, celle-ci doit inscrire le package avec un emplacement externe en utilisant la méthode AddPackageByUriAsync de la classe PackageManager. Cette méthode est disponible à partir de Windows 10, version 2004. Vous pouvez ajouter du code à votre application pour inscrire le package avec un emplacement externe lors de la première exécution de votre application. Vous pouvez également exécuter du code afin d’inscrire le package lors de l’installation de votre application de bureau (par exemple, si vous utilisez MSI pour installer votre application de bureau, vous pouvez exécuter ce code à partir une action personnalisée).

L’exemple suivant montre comment inscrire un package avec un emplacement externe. Ce code crée un objet AddPackageOptions contenant le chemin de l’emplacement externe où le manifeste de votre package peut référencer du contenu en dehors du package. Ensuite, le code passe cet objet à la méthode AddPackageByUriAsync pour inscrire le package avec un emplacement externe. Cette méthode reçoit également l’emplacement de votre package avec un emplacement externe signé sous forme d’URI. Pour obtenir un exemple plus complet, consultez le fichier de code StartUp.cs dans l’exemple d’application associé (voir la section Exemple d’application de cette rubrique).

private static bool registerPackageWithExternalLocation(string externalLocation, string pkgPath)
{
    bool registration = false;
    try
    {
        Uri externalUri = new Uri(externalLocation);
        Uri packageUri = new Uri(pkgPath);

        Console.WriteLine("exe Location {0}", externalLocation);
        Console.WriteLine("msix Address {0}", pkgPath);

        Console.WriteLine("  exe Uri {0}", externalUri);
        Console.WriteLine("  msix Uri {0}", packageUri);

        PackageManager packageManager = new PackageManager();

        // Declare use of an external location
        var options = new AddPackageOptions();
        options.ExternalLocationUri = externalUri;

        Windows.Foundation.IAsyncOperationWithProgress<DeploymentResult, DeploymentProgress> deploymentOperation = packageManager.AddPackageByUriAsync(packageUri, options);

        // Other progress and error-handling code omitted for brevity...
    }
}

Exemple d’application

Pour obtenir un exemple d’application entièrement fonctionnel montrant comment accorder une identité de package à une application de bureau en utilisant un package avec un emplacement externe, consultez l’exemple SparsePackages. Pour plus d’informations sur la création et l’exécution de l’exemple, consultez le billet de blog Identité, inscription et activation des applications Win32 non empaquetées.

Cet exemple inclut ce qui suit :

  • Le code source d’une application WPF nommée PhotoStoreDemo. Au démarrage, l’application vérifie si elle s’exécute avec l’identité. Si ce n’est pas le cas, elle inscrit le package avec un emplacement externe, puis redémarre. Consultez StartUp.cs pour obtenir le code qui effectue ces étapes.
  • Un manifeste d’application côte à côte nommé PhotoStoreDemo.exe.manifest.
  • Un manifeste du package nommé AppxManifest.xml.