Usar propriedades personalizadas para extensões de aplicativoUsing custom properties for app extensions

As propriedades de extensão de aplicativo são um campo de metadados personalizados fornecido pelo desenvolvedor da extensão do aplicativo no manifesto do aplicativo.App extension properties are a custom metadata field provided by the app extension developer in their app manifest. Os hosts de extensão do aplicativo podem ler esses metadados ao examinar extensões de aplicativo sem precisar carregar o conteúdo da extensão do aplicativo.App extension hosts can read this metadata when examining app extensions without having to load any content from the app extension.

As propriedades são um recurso opcional, mas bastante útil.Properties are an optional but very useful feature. Há uma ampla variedade de metadados possíveis que você pode precisar ao criar uma plataforma de host de extensão de aplicativo, como versão, recursos, listas de tipos de arquivo compatíveis ou outros dados úteis que você deve saber antes de carregar uma extensão de aplicativo.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. Essas informações podem até mesmo determinar como você carrega uma extensão de aplicativo.Such information may even determine how you load an app extension. Em vez de tentar prever todos os campos de que você pode precisar, as propriedades de extensão do aplicativo oferecem uma tela em branco para definir exatamente o que você precisa da forma mais adequada para seu aplicativo.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.

Vantagens das propriedades de extensão do aplicativoAdvantages of app extension properties

Há dois motivos importantes pelos quais você deve aproveitar as propriedades de extensão do aplicativo:There two important reasons why you should take advantage of app extension properties:

  • É uma forma fácil e segura de armazenar metadados importantes ou básicos sobre a plataforma de extensão do aplicativo sem precisar colocar as informações nos arquivos.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. Você pode usá-los para conceitos importantes como controle de versão, permissões e como imposição.You can use it for important concepts like versioning, permissions, and as enforcement. Por exemplo, o aplicativo pode insistir que um campo version seja definido e esteja presente nas propriedades, além de ter comportamentos de carregamento diferentes com base no valor.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.

  • Como as informações são armazenadas no manifesto do aplicativo, elas podem ser indexadas e disponibilizadas por uma API no futuro.Because the information is stored in the app manifest, it can be indexed and made available via an API in the future. Isso significa que você pode mostrá-las para o usuário na forma de balões, ou ter pesquisas de extensão de aplicativo mais refinadas por propriedades específicas sem precisar implantar e carregar a extensão primeiro.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.

Como declarar as propriedadesHow to declare properties

As propriedades são declaradas no arquivo Package.appxmanifest do pacote.Properties are declared in the Package.appxmanifest file in your package. Eles podem ser lidos no tempo de execução pelo host da extensão como um conjunto de propriedades.They can be read at runtime by the extension host as a property set. Como o host define a plataforma, fica a cargo do host comunicar aos desenvolvedores da extensão sobre quais propriedades estão disponíveis e devem ser colocadas na declaração 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.

Observação

O designer do manifesto no Visual Studio não é compatível com a capacidade de definir propriedades.The manifest designer in Visual Studio does not support the ability to define properties. Você deve editar o Package.appxmanifest diretamente para definir as propriedades.You must edit the Package.appxmanifest directly to define properties.

Para declarar as propriedades, coloque-as no elemento <uap3:Properties/> na declaração <uap3:AppExtension>.To declare properties, put them in the <uap3:Properties/> element under your <uap3:AppExtension> declaration. Este é um exemplo de declaração <uap3:AppExtension> do Microsoft Edge que usa propriedades compatíveis com o 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>

O Edge definiu um valor de propriedade conhecido de Capabilities com uma lista declarada de recursos de extensão.Edge has defined a known property value of Capabilities with a list of extension capabilities declared. Enquanto host, é possível oferecer suporte às propriedades desejadas nas extensões do aplicativo.As a host, you can support whatever properties you want in your app extensions. Como elas são um conjunto de propriedades, também é possível ter propriedades aninhadas.Since these are a property set, you can also have nested properties. É útil ter uma propriedade de versão raiz que possa ser usada caso você altere os formatos das extensões no futuro.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. Não colocamos Version intencionalmente como um atributo de extensões de aplicativo para que você não fique restrito artificialmente ao uso da semântica de controle de versão.We intentionally did not put Version as an attribute of app extensions so you would not be artificially confined to using our versioning semantics. Em vez disso, criamos propriedades nas quais a versão pode ser um dos muitos atributos personalizados, na forma e formato que você quiser, e processados à seu critério.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.

Como usar propriedadesHow to use properties

Suponha que você tenha uma propriedade simples em uma extensão de aplicativo que descreva a versão, como a seguir.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>

Para obter esses dados no tempo de execução, basta chamar GetExtensionPropertiesAsync() nas extensões de aplicativo.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();
    }
}