Using Custom Properties for AppExtensions


Properties are an optional but very useful feature of AppExtensions. There a wide range of possible metadata that you may require when creating an AppExtension Host platform, such as version, capabilities, lists of supported filetypes or other data that is helpful to know prior to loading an AppExtension and also highly specific to your app. Such information may even determine how you load an AppExtenion. Rather than trying to predict all of the fields you might need, we gave you an open canvas to define exactly what you need in however manner best suited for your app. AppExtension properties are a custom metadata field provided by the AppExtension developer in their AppxManifest. AppExtension Hosts can read this metadata when examining AppExtensions without having to load any content from the AppExtension.

There two important reasons why you should take advantage of AppExtension properties:

  1. 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. 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.
  2. The information is stored in the app manifest. This means that it is something that can be indexed and made available via a Store Services 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

Properties are declared in the Package.appxmanifest file in your UWP package. They can be read at runtime by the Extension Host as a PropertySet. Since the host defines the platform, it is up to the host to communicate to the extension developers about which properties, if any are available and should be put into the AppExtension declaration.  In order to define Properties, you must edit the Package.appxmanifest directly. The ability to specify Properties is not in the Manifest Designer.

 

To declare properties, put them in the <uap3:Properties/> element under AppExtension declaration. Here is a sample Microsoft Edge AppExtension declaration 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>
        </uap3:Extension>

 

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 AppExtensions. Since these are a PropertySet, 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. We intentionally did not put "version" as an attribute of AppExtensions 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 AppExtension that describes a version, such as the following:

            <uap3:Properties>
              <Version>1.0.0.0</Version>
            </uap3:Properties>

 

To get this data at runtime, just call GetExtensionPropertiesAsync() on the AppExtension.

        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();
            }
        }

 

Note: In the Windows 10 Anniversary Update, there is an issue where GetExtensionPropertiesAsync() can return null instead of an empty PropertySet if there are no Properties element defined in the extension's app manifest. This will throw an exception in the above example.  If you are using an extension platform that is intended to target the Windows 10 Anniversary Update, be sure to check for this and treat the exception as an empty PropertySet. This issue is corrected in the Windows 10 Creators Update.

 

Properties can be a very useful way to manage the metadata in your app. As always we value your feedback; let us know if you have questions or problems!

 

- David Bennett, Program Manager, Windows Developer Platform


Comments (0)

Skip to main content