Verwenden benutzerdefinierter Eigenschaften für App-ErweiterungenUsing custom properties for app extensions

Die Eigenschaften der App-Erweiterung sind ein benutzerdefiniertes Metadatenfeld, das vom Entwickler der App-Erweiterung in seinem App-Manifest bereitgestellt wird.App extension properties are a custom metadata field provided by the app extension developer in their app manifest. Hosts von App-Erweiterungen können diese Metadaten bei der Untersuchung von App-Erweiterungen lesen, ohne dass Inhalte von der App-Erweiterung geladen werden müssen.App extension hosts can read this metadata when examining app extensions without having to load any content from the app extension.

Eigenschaften sind eine optionale, aber sehr nützliche Funktion.Properties are an optional but very useful feature. Es gibt eine breite Palette möglicher Metadaten, die du bei der Erstellung einer Hostplattform für eine Anwendungserweiterung benötigen, z. B. Version, Funktionen, Listen unterstützter Dateitypen oder andere Daten, die du vor dem Laden einer App-Erweiterung kennen solltest.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. Solche Informationen können sogar bestimmen, wie du eine App-Erweiterung lädst.Such information may even determine how you load an app extension. Anstatt zu versuchen, alle erforderlichen Felder vorherzusagen, bieten die Eigenschaften der App-Erweiterung einen offenen Zeichenbereich, in dem du genau definieren kannst, was du in der für deine App am besten geeigneten Methode benötigst.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.

Vorteile von App-ErweiterungseigenschaftenAdvantages of app extension properties

Es gibt zwei wichtige Gründe, warum du die Vorteile der App-Erweiterungseigenschaften nutzen solltest:There two important reasons why you should take advantage of app extension properties:

  • Es ist eine einfache und sichere Möglichkeit, grundlegende oder wichtige Metadaten über deine App-Erweiterungsplattform zu speichern, ohne diese Informationen in Dateien ablegen zu müssen.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. Du kannst es für wichtige Konzepte wie Versionsverwaltung, Berechtigungen und zur Durchsetzung verwenden.You can use it for important concepts like versioning, permissions, and as enforcement. Deine App könnte z. B. darauf bestehen, dass ein version-Feld definiert und in den Eigenschaften vorhanden ist, und basierend auf diesem Wert ein anderes Ladeverhalten aufweisen.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.

  • Da die Informationen im App-Manifest gespeichert werden, können sie in Zukunft indiziert und über eine API zur Verfügung gestellt werden.Because the information is stored in the app manifest, it can be indexed and made available via an API in the future. Das bedeutet, dass du sie zur Anzeige für den Benutzer übergeben oder eine verfeinerte Suche nach bestimmten Eigenschaften der App-Erweiterung durchführen kannst, ohne dass du die Erweiterung zuerst bereitstellen und laden musst.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.

Deklarieren von EigenschaftenHow to declare properties

Eigenschaften werden in der Datei „Package.appxmanifest“ in deinem Paket deklariert.Properties are declared in the Package.appxmanifest file in your package. Sie können zur Laufzeit vom Erweiterungshost als Eigenschaftensatz gelesen werden.They can be read at runtime by the extension host as a property set. Da der Host die Plattform definiert, ist es seine Aufgabe, den Entwicklern der Erweiterung mitzuteilen, welche Eigenschaften verfügbar sind und in die AppExtension-Deklaration aufgenommen werden sollten.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.

Hinweis

Der Manifest-Designer in Visual Studio unterstützt nicht die Möglichkeit, Eigenschaften zu definieren.The manifest designer in Visual Studio does not support the ability to define properties. Du musst „Package.appxmanifest“ direkt bearbeiten, um Eigenschaften zu definieren.You must edit the Package.appxmanifest directly to define properties.

Um Eigenschaften zu deklarieren, füge sie in das <uap3:Properties/>-Element unter deiner <uap3:AppExtension>-Deklaration ein.To declare properties, put them in the <uap3:Properties/> element under your <uap3:AppExtension> declaration. Hier folgt ein Beispiel für eine <uap3:AppExtension>-Deklaration für Microsoft Edge, die von Edge unterstützte Eigenschaften verwendet.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>

Microsoft Edge hat einen bekannten Eigenschaftswert von Capabilities mit einer Liste der deklarierten Erweiterungsmöglichkeiten definiert.Edge has defined a known property value of Capabilities with a list of extension capabilities declared. Als Host kannst du beliebige Eigenschaften in deinen App-Erweiterungen unterstützen.As a host, you can support whatever properties you want in your app extensions. Da es sich um einen Eigenschaftensatz handelt, kannst du auch geschachtelte Eigenschaften verwenden.Since these are a property set, you can also have nested properties. Es ist eine gute Idee, eine Stammversionseigenschaft zu haben, die du verwenden kannst, falls du in Zukunft das Format deiner Erweiterungen änderst.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. Wir haben Version absichtlich nicht als Attribut von App-Erweiterungen festgelegt, damit du nicht künstlich auf die Verwendung unserer Semantik der Versionsverwaltung beschränkt bist.We intentionally did not put Version as an attribute of app extensions so you would not be artificially confined to using our versioning semantics. Stattdessen haben wir Eigenschaften erstellt, bei denen die Version eines von vielen benutzerdefinierten Attributen in der von dir gewünschten Art und Weise und im gewünschten Format vorliegen kann.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.

Verwenden von EigenschaftenHow to use properties

Angenommen, du verfügst über eine einfache Eigenschaft in einer App-Erweiterung, die eine Version wie die folgende beschreibt.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>

Um diese Daten zur Laufzeit zu abzurufen, rufst du einfach GetExtensionPropertiesAsync() für die App-Erweiterungen auf.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();
    }
}