Utilisation de propriétés personnalisées pour les extensions d’applicationUsing custom properties for app extensions

Les propriétés d’extensions d’application sont un champ de métadonnées personnalisé fourni par le développeur de l’extension d’application dans son manifeste d’application.App extension properties are a custom metadata field provided by the app extension developer in their app manifest. Les hôtes d’extensions d’application peuvent lire ces métadonnées lors de l’examen des extensions d’application sans avoir à charger de contenu à partir de l’extension d’application.App extension hosts can read this metadata when examining app extensions without having to load any content from the app extension.

Les propriétés sont une fonctionnalité facultative mais très utile.Properties are an optional but very useful feature. Vous pouvez avoir besoin d’un large éventail de métadonnées quand vous créez une plateforme hôte d’extension d’application, telles que la version, les fonctionnalités, les listes de types de fichiers pris en charge ou d’autres données utiles avant de charger une extension d’application.There are a wide range of possible metadata that you may require when creating an app extension host platform, such as version, capabilities, lists of supported file types or other data that is helpful to know prior to loading an app extension. Ces informations peuvent même déterminer la manière dont vous chargez une extension d’application.Such information may even determine how you load an app extension. Au lieu d’essayer de prédire tous les champs dont vous pouvez avoir besoin, les propriétés d’extensions d’application fournissent un canevas vierge pour définir exactement ce dont vous avez besoin, de la manière la mieux adaptée à votre application.Rather than trying to predict all of the fields you might need, app extension properties provide an open canvas to define exactly what you need in however manner best suited for your app.

Avantages des propriétés d’extensions d’applicationAdvantages of app extension properties

Il existe deux raisons importantes pour lesquelles vous devez tirer parti des propriétés d’extensions d’application :There two important reasons why you should take advantage of app extension properties:

  • C’est un moyen simple et sécurisé de stocker des métadonnées de base ou importantes concernant votre plateforme d’extensions d’application sans avoir à placer ces informations dans des fichiers.It's an easy way and safe way to store basic or important metadata about your app extension platform without having to put that information into files. Vous pouvez les utiliser pour des concepts importants tels que la gestion de versions, les autorisations et la mise en application.You can use it for important concepts like versioning, permissions, and as enforcement. Par exemple, votre application peut insister sur le fait qu’un champ version soit défini et présent dans les propriétés, et avoir un comportement de chargement différent en fonction de cette valeur.For example, your app could insist that a version field is defined and present in the properties, and have different loading behavior based on that value.

  • Les informations étant stockées dans le manifeste de l’application, elles peuvent être indexées et mises à disposition par le biais d’une API à l’avenir.Because the information is stored in the app manifest, it can be indexed and made available via an API in the future. Cela signifie que vous pouvez les présenter à l’écran pour l’utilisateur, ou disposer d’une extension d’application plus affinée pour rechercher des propriétés spécifiques sans avoir à déployer et charger l’extension au préalable.That means you can bubble it up for display to the user, or have more refined app extension searches for specific properties without having to deploy and load the extension first.

Comment déclarer des propriétés ?How to declare properties

Les propriétés sont déclarées dans le fichier Package.appxmanifest de votre package.Properties are declared in the Package.appxmanifest file in your package. Elles peuvent être lues au moment de l’exécution par l’hôte d’extension en tant que jeu de propriétés.They can be read at runtime by the extension host as a property set. Comme c’est l’hôte qui définit la plateforme, il lui incombe d’indiquer aux développeurs d’extensions quelles propriétés sont disponibles et doivent être placées dans la déclaration AppExtension.Because the host defines the platform, it is up to the host to communicate to the extension developers about which properties are available and should be put into the AppExtension declaration.

Notes

Le concepteur de manifeste dans Visual Studio ne prend pas en charge la définition de propriétés.The manifest designer in Visual Studio does not support the ability to define properties. Vous devez modifier directement le fichier Package.appxmanifest pour définir les propriétés.You must edit the Package.appxmanifest directly to define properties.

Pour déclarer des propriétés, placez-les dans l’élément <uap3:Properties/> sous votre déclaration <uap3:AppExtension>.To declare properties, put them in the <uap3:Properties/> element under your <uap3:AppExtension> declaration. Voici un exemple de déclaration <uap3:AppExtension> pour Microsoft Edge qui utilise des propriétés prises en charge par Edge.Here is a sample <uap3:AppExtension> declaration for Microsoft Edge that uses properties supported by Edge.

<uap3:AppExtension Name="com.microsoft.edge.extension" Id="FirstExtension" PublicFolder="Extension" DisplayName="MyExtension">
  <uap3:Properties>
    <Capabilities>
      <Capability Name="websiteContent" />
      <Capability Name="websiteInfo" />
      <Capability Name="browserWebRequest" />
      <Capability Name="browserStorage" />
    </Capabilities>
  </uap3:Properties>
</uap3:AppExtension>

Edge a défini une valeur de propriété connue Capabilities avec une liste de fonctionnalités d’extension déclarées.Edge has defined a known property value of Capabilities with a list of extension capabilities declared. En tant qu’hôte, vous pouvez prendre en charge les propriétés de votre choix dans vos extensions d’application.As a host, you can support whatever properties you want in your app extensions. Étant donné qu’il s’agit d’un jeu de propriétés, vous pouvez également avoir des propriétés imbriquées.Since these are a property set, you can also have nested properties. Il est judicieux de disposer d’une propriété de version racine que vous pouvez utiliser si vous changez les formats de vos extensions à l’avenir.Its a good idea to have a root version property that you can use in case you change formats of your extensions in the future. Nous avons fait exprès de ne pas mettre Version comme attribut des extensions d’application, afin que vous ne soyez pas limiter artificiellement à l’utilisation de notre sémantique de gestion de versions.We intentionally did not put Version as an attribute of app extensions so you would not be artificially confined to using our versioning semantics. Au lieu de cela, nous avons créé des propriétés dans lesquelles la version peut être l’un des nombreux attributs définis personnalisés, de la façon, au format et avec le traitement que vous souhaitez.Instead, we created properties where version could be one of many custom-defined attributes, in whatever way and format you want, and processed however you want.

Comment utiliser les propriétés ?How to use properties

Supposez que vous disposez d’une propriété simple dans une extension d’application qui décrit une version, telle que la suivante.Suppose you have a simple property in an app extensions that describes a version, such as the following.

<uap3:Properties>
    <Version>1.0.0.0</Version>
</uap3:Properties>

Pour obtenir ces données au moment de l’exécution, il vous suffit d’appeler GetExtensionPropertiesAsync() sur les extensions d’application.To get this data at runtime, just call GetExtensionPropertiesAsync() on the app extensions.

string extensionVersion = "Unknown";
var properties = await ext.GetExtensionPropertiesAsync() as PropertySet;
if (properties != null)
{
    if (properties.ContainsKey("Version"))
    {
        PropertySet versionProperty = properties["Version"] as PropertySet;
        extensionVersion = versionProperty["#text"].ToString();
    }
}