Uso di proprietà personalizzate per le estensioni di app

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

Le proprietà sono una funzionalità facoltativa ma molto utile. Quando crei una piattaforma host per un'estensione di app, puoi richiedere una vasta gamma di metadati, come la versione, le funzionalità, gli elenchi dei tipi di file supportati o altri dati che è utile conoscere prima del caricamento di un'estensione di app. Queste informazioni possono anche determinare il modo in cui viene caricata un'estensione di app. Invece di cercare di prevedere tutti i campi che potrebbero essere necessari, puoi usare le proprietà dell'estensione di un'app per definire esattamente ciò ritieni necessario nel modo più appropriato per l'app.

Vantaggi delle proprietà delle estensioni di app

Esistono due motivi importanti per cui è opportuno sfruttare le proprietà delle estensioni di app:

• Si tratta di una soluzione semplice e sicura per archiviare metadati standard o importanti relativi alla piattaforma dell'estensione di app senza dover inserire tali informazioni nei file. Puoi usarla per concetti importanti quali il controllo delle versioni e le autorizzazioni e anche come imposizione. La tua app, ad esempio, potrebbe richiedere che un campo version 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 in futuro tramite un'API. Ciò significa che puoi propagarle per consentire all'utente di visualizzarle o che puoi eseguire ricerche più dettagliate di proprietà specifiche in un'estensione di app senza dover prima distribuire e caricare l'estensione.

Come dichiarare le proprietà

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

Nota

Progettazione manifesto in Visual Studio non consente la definizione di proprietà. Per eseguire questa operazione, devi modificare direttamente il file Package.appxmanifest.

Per dichiarare le proprietà, inseriscile nell'elemento <uap3:Properties/> sotto la dichiarazione <uap3:AppExtension>. Di seguito è riportato un esempio di dichiarazione <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>

Per Edge è definito un valore di proprietà Capabilities noto con un elenco di capacità dell'estensione dichiarate. Come host, puoi supportare qualsiasi proprietà che ritieni opportuna nelle estensioni di app. Poiché le proprietà sono definite come set, puoi anche avere proprietà nidificate. Può essere utile definire una proprietà della versione radice da usare nel caso in cui modifichi i formati delle estensioni in futuro. Non abbiamo intenzionalmente inserito Version come attributo delle estensioni di app per evitare di costringerti artificialmente a usare la nostra semantica di controllo delle versioni. Abbiamo però creato proprietà in cui la versione può essere uno dei numerosi attributi personalizzati, definiti nel modo e nel formato che preferisci ed elaborati nel modo che ritieni più opportuno.

Come usare le proprietà

Supponi di avere nelle estensioni di un'app una proprietà semplice che descrive una versione, come la seguente.

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

Per ottenere questi dati in fase di esecuzione, devi semplicemente chiamare GetExtensionPropertiesAsync() nelle 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();
    }
}