使用應用程式擴充功能的自訂屬性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.xml 檔案中宣告。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.xml 來定義屬性。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. 相反地,我們建立了一些屬性,其中版本可以是許多自訂屬性的其中一個,因此您可以對其採用任何想要的方式和格式,以及根據想要的方式進行處理。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();
    }
}