Uso di proprietà personalizzate per le estensioni dell'app

Le proprietà dell'estensione dell'app sono un campo di metadati personalizzato fornito dallo sviluppatore di estensioni 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 di estensione dell'app, ad esempio versione, funzionalità, elenchi di tipi di file supportati o altri dati, è possibile che siano necessari diversi metadati, ad esempio versione, funzionalità, elenchi di tipi di file supportati o altri dati utili prima del caricamento di un'estensione dell'app. 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 forniscono un canvas aperto per definire esattamente ciò che è necessario nel modo più appropriato per l'app.

Vantaggi delle proprietà delle estensioni 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 queste informazioni nei file. È possibile usarlo per concetti importanti come il controllo delle versioni, le autorizzazioni e l'imposizione. Ad esempio, l'app potrebbe insistono version sul fatto che un campo sia definito e presente nelle proprietà e abbia un comportamento di caricamento 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 visualizzare l'estensione per l'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 lette 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 le proprietà. È necessario modificare direttamente Package.appxmanifest per definire le proprietà.

Per dichiarare le proprietà, inserire le proprietà nell'elemento <uap3:Properties/> sotto la <uap3:AppExtension> dichiarazione. Ecco una dichiarazione di esempio <uap3:AppExtension> 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 con Capabilities un elenco di funzionalità di estensione dichiarate. Come host, è possibile supportare le proprietà desiderate 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. Poiché intenzionalmente non è stato inserito Version come attributo delle estensioni dell'app, non si sarebbe quindi limitati artificialmente all'uso della semantica di controllo delle versioni. Sono state invece create proprietà in cui la versione può essere uno dei molti 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();
    }
}