アプリの拡張機能のカスタム プロパティを使用する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

アプリの拡張機能のプロパティを利用するべき重要な 2 つの理由を、以下に示します。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:AppExtension> 宣言の下の <uap3:Properties/> 要素に追加します。To declare properties, put them in the <uap3:Properties/> element under your <uap3:AppExtension> declaration. Microsoft Edge 用の <uap3:AppExtension> 宣言の例を次に示します。ここでは 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. 代わりに、多数のカスタム定義属性の 1 つとしてバージョンを設定できる、プロパティが用意されています。そこでは好みの方法と形式を使い、好きなように処理することができます。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();
    }
}