Использование настраиваемых свойств для расширений приложенийUsing custom properties for app extensions

Свойства расширения приложения — это настраиваемое поле метаданных, предоставляемое разработчиком расширения в манифесте приложения.App extension properties are a custom metadata field provided by the app extension developer in their app manifest. Узлы расширения приложения могут считывать эти метаданные при проверке расширений приложения, не загружая его содержимое.App extension hosts can read this metadata when examining app extensions without having to load any content from the app extension.

Свойства являются необязательной, но очень полезной функцией.Properties are an optional but very useful feature. Существует широкий спектр возможных метаданных, которые могут потребоваться при создании платформы узла расширения приложения, такие как версия, возможности, списки поддерживаемых типов файлов или другие данные, которые полезно знать до загрузки расширения приложения.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. Эти данные могут определить способ загрузки расширения приложения.Such information may even determine how you load an app extension. Вместо прогнозирования всех полей, которые могут потребоваться, свойства расширения приложения предоставляют открытый холст для определения того, что вам нужно, и что лучше всего подходит для вашего приложения.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.

Преимущества свойств расширения приложенияAdvantages of app extension properties

Есть две важные причины, почему вы должны воспользоваться свойствами расширения приложений.There two important reasons why you should take advantage of app extension properties:

  • Это простой и безопасный способ хранения основных или важных метаданных о платформе расширения вашего приложения, исключающий необходимость в сохранении этих сведений в файлы.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. Вы можете использовать его для таких важных концепций, как управление версиями, разрешения и принудительное исполнение.You can use it for important concepts like versioning, permissions, and as enforcement. Например, ваше приложение может требовать, чтобы поле version было определено в свойствах и присутствовало в них, а также имело различное поведение при загрузке в зависимости от этого значения.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.

  • Так как информация хранится в манифесте приложения, ее можно проиндексировать и сделать в будущем доступной через API.Because the information is stored in the app manifest, it can be indexed and made available via an API in the future. Это означает, что вы можете передать его вверх по иерархии для отображения пользователю, или иметь более точное средство расширений приложений для поиска конкретных свойств, не нуждаясь сначала в развертывании и загрузке расширения.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.

Объявление свойствHow to declare properties

Свойства объявлены в файле Package.appxmanifest вашего пакета.Properties are declared in the Package.appxmanifest file in your package. Узел расширения может считывать их во время выполнения как набор свойств.They can be read at runtime by the extension host as a property set. Поскольку узел определяет платформу, то именно он должен сообщать разработчикам расширений о том, какие свойства доступны и должны быть помещены в объявление 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.

Примечание

Конструктор манифестов в Visual Studio не поддерживает возможность определения свойств.The manifest designer in Visual Studio does not support the ability to define properties. Для определения свойств Package.appxmanifest необходимо отредактировать напрямую.You must edit the Package.appxmanifest directly to define properties.

Чтобы объявить свойства, поместите их в элемент <uap3:Properties/> под вашим объявлением <uap3:AppExtension>.To declare properties, put them in the <uap3:Properties/> element under your <uap3:AppExtension> declaration. Вот пример объявления <uap3:AppExtension> для Microsoft Edge, которое использует свойства, поддерживаемые 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 определила известное значение свойства Capabilities со списком объявленных возможностей расширения.Edge has defined a known property value of Capabilities with a list of extension capabilities declared. Будучи основным элементом, вы можете поддерживать любые свойства, необходимые для ваших расширений приложения.As a host, you can support whatever properties you want in your app extensions. Поскольку это набор свойств, вы также можете иметь вложенные свойства.Since these are a property set, you can also have nested properties. Это хорошая идея иметь свойство версии корня, которое вы можете использовать, если измените форматы ваших расширений.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. Мы намеренно не ставили Version в качестве атрибута расширений приложения, чтобы не ограничивать вас использованием нашей семантики управления версиями.We intentionally did not put Version as an attribute of app extensions so you would not be artificially confined to using our versioning semantics. Вместо этого мы создали свойства, где версией может быть один из многих пользовательских атрибутов в любом виде и формате, который можно обрабатывать на свое усмотрение.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.

Использование свойствHow to use properties

Предположим, у вас есть простое свойство в расширениях приложения, которое описывает версию, например, следующее.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>

Чтобы получить эти данные во время выполнения, в расширениях приложения достаточно вызвать GetExtensionPropertiesAsync().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();
    }
}