Uso di proprietà personalizzate per le estensioni di appUsing custom properties for app extensions

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.App extension properties are a custom metadata field provided by the app extension developer in their app manifest. Gli host delle estensioni di app possono leggere questi metadati quando esaminano le estensioni senza dover caricare alcun contenuto.App extension hosts can read this metadata when examining app extensions without having to load any content from the app extension.

Le proprietà sono una funzionalità facoltativa ma molto utile.Properties are an optional but very useful feature. 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.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. Queste informazioni possono anche determinare il modo in cui viene caricata un'estensione di app.Such information may even determine how you load an app extension. 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.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.

Vantaggi delle proprietà delle estensioni di appAdvantages of app extension properties

Esistono due motivi importanti per cui è opportuno sfruttare le proprietà delle estensioni di app:There two important reasons why you should take advantage of app extension properties:

  • 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.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. Puoi usarla per concetti importanti quali il controllo delle versioni e le autorizzazioni e anche come imposizione.You can use it for important concepts like versioning, permissions, and as enforcement. 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.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.

  • Poiché le informazioni vengono archiviate nel manifesto dell'app, possono essere indicizzate e rese disponibili in futuro tramite un'API.Because the information is stored in the app manifest, it can be indexed and made available via an API in the future. 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.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.

Come dichiarare le proprietàHow to declare properties

Le proprietà vengono dichiarate nel file Package.appxmanifest del tuo pacchetto.Properties are declared in the Package.appxmanifest file in your package. Possono essere lette in fase di esecuzione dall'host dell'estensione come set di proprietà.They can be read at runtime by the extension host as a property set. Poiché l'host definisce la piattaforma, è suo compito comunicare agli sviluppatori dell'estensione quali proprietà sono disponibili e devono essere inserite nella dichiarazione 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.

Nota

Progettazione manifesto in Visual Studio non consente la definizione di proprietà.The manifest designer in Visual Studio does not support the ability to define properties. Per eseguire questa operazione, devi modificare direttamente il file Package.appxmanifest.You must edit the Package.appxmanifest directly to define properties.

Per dichiarare le proprietà, inseriscile nell'elemento <uap3:Properties/> sotto la dichiarazione <uap3:AppExtension>.To declare properties, put them in the <uap3:Properties/> element under your <uap3:AppExtension> declaration. Di seguito è riportato un esempio di dichiarazione <uap3:AppExtension> per Microsoft Edge che usa le proprietà supportate da 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>

Per Edge è definito un valore di proprietà Capabilities noto con un elenco di capacità dell'estensione dichiarate.Edge has defined a known property value of Capabilities with a list of extension capabilities declared. Come host, puoi supportare qualsiasi proprietà che ritieni opportuna nelle estensioni di app.As a host, you can support whatever properties you want in your app extensions. Poiché le proprietà sono definite come set, puoi anche avere proprietà nidificate.Since these are a property set, you can also have nested properties. Può essere utile definire una proprietà della versione radice da usare nel caso in cui modifichi i formati delle estensioni in futuro.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. 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.We intentionally did not put Version as an attribute of app extensions so you would not be artificially confined to using our versioning semantics. 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.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.

Come usare le proprietàHow to use properties

Supponi di avere nelle estensioni di un'app una proprietà semplice che descrive una versione, come la seguente.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>

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