Uso di proprietà personalizzate per le estensioni dell'app

Le proprietà dell'estensione dell'app sono un campo di metadati personalizzato fornito dallo sviluppatore dell'estensione dell'app nel manifesto dell'app. Gli host delle estensioni dell'app possono leggere questi metadati quando esaminano le estensioni dell'app senza dover caricare contenuto dall'estensione dell'app.

Le proprietà sono una funzionalità facoltativa ma molto utile. Quando si crea una piattaforma host dell'estensione dell'app, ad esempio versione, funzionalità, elenchi di tipi di file supportati o altri dati che è utile conoscere prima del caricamento di un'estensione dell'app, può essere necessaria una vasta gamma di metadati. Tali informazioni possono anche determinare come si carica un'estensione dell'app. Invece di provare a stimare tutti i campi che potrebbero essere necessari, le proprietà dell'estensione dell'app offrono un'area di disegno aperta per definire esattamente ciò che serve, ma nel modo più adatto per l'app.

Vantaggi delle proprietà di estensione dell'app

Esistono due motivi importanti per cui è consigliabile sfruttare le proprietà dell'estensione dell'app:

  • È un modo semplice e sicuro per archiviare metadati di base o importanti sulla piattaforma di estensione dell'app senza dover inserire le informazioni nei file. È possibile usarlo per concetti importanti come il controllo delle versioni, le autorizzazioni e l'imposizione. Ad esempio, l'app potrebbe ingente che un campo sia definito e presente nelle proprietà e abbia un comportamento di caricamento version diverso in base a tale valore.

  • Poiché le informazioni vengono archiviate nel manifesto dell'app, possono essere indicizzate e rese disponibili tramite un'API in futuro. Ciò significa che è possibile visualizzarlo a bolle per la visualizzazione all'utente o fare in modo che l'estensione dell'app sia più perfezionata per cercare proprietà specifiche senza dover prima distribuire e caricare l'estensione.

Come dichiarare le proprietà

Le proprietà vengono dichiarate nel file Package.appxmanifest nel pacchetto. Possono essere letti in fase di esecuzione dall'host di estensione come set di proprietà. Poiché l'host definisce la piattaforma, è l'host a comunicare agli sviluppatori di estensioni quali proprietà sono disponibili e devono essere inserite nella AppExtension dichiarazione.

Nota

La finestra di progettazione del manifesto Visual Studio non supporta la possibilità di definire proprietà. È necessario modificare direttamente Package.appxmanifest per definire le proprietà.

Per dichiarare le proprietà, inserire le proprietà <uap3:Properties/> nell'elemento sotto la <uap3:AppExtension> dichiarazione. Ecco una dichiarazione di <uap3:AppExtension> esempio per Microsoft Edge che usa le proprietà supportate da 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 ha definito un valore di proprietà noto di Capabilities con un elenco di funzionalità di estensione dichiarate. Gli host possono supportare qualsiasi proprietà desiderata nelle estensioni dell'app. Poiché si tratta di un set di proprietà, è anche possibile avere proprietà annidate. È buona idea avere una proprietà della versione radice che è possibile usare nel caso in cui si cambino i formati delle estensioni in futuro. Intenzionalmente non è stato inserito come attributo delle estensioni dell'app, quindi non si sarebbe artificialmente limitati all'uso Version della semantica di controllo delle versioni. Sono state invece create proprietà in cui la versione può essere uno dei numerosi attributi definiti dall'utente, nel modo e nel formato desiderati, ed elaborata nel modo desiderato.

Come usare le proprietà

Si supponga di avere una proprietà semplice in un'estensione dell'app che descrive una versione, ad esempio la seguente.

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

Per ottenere questi dati in fase di esecuzione, è sufficiente chiamare GetExtensionPropertiesAsync() sulle estensioni dell'app.

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