Salvare e caricare le impostazioni in un'app UWPSave and load settings in a UWP app

Questo argomento illustra i concetti necessari per iniziare a caricare e salvare le impostazioni in un'app della piattaforma UWP (Universal Windows Platform).This topic covers what you need to know to get started loading, and saving, settings in a Universal Windows Platform (UWP) app. Introduce le API principali e fornisce i collegamenti per altre informazioni.The main APIs are introduced, and links are provided to help you learn more.

Usare le impostazioni per memorizzare gli aspetti dell'app personalizzabili dall'utente.Use settings to remember the user-customizable aspects of your app. Ad esempio, un'app lettore di news potrebbe usare le impostazioni per salvare le nuove fonti da visualizzare e i tipi di carattere da usare per la lettura degli articoli.For example, a news reader could use app settings to save which news sources to display and what font to use for reading articles.

Verrà esaminato il codice per salvare e caricare le impostazioni dell'app, incluse le impostazioni locali e di roaming.We’ll look at code to save and load app settings, including local and roaming settings.

Cosa sapereWhat do you need to know

Usare le impostazioni dell'app per archiviare i dati di configurazione, ad esempio le preferenze dell'utente e lo stato dell'app.Use app settings to store configuration data such as user preferences and app state. Le impostazioni specifiche del dispositivo vengono archiviate in locale.Settings that are specific to the device are stored locally. Le impostazioni che si applicano a qualsiasi dispositivo in cui è installata l'app vengono archiviate nell'archivio dei dati di roaming.Settings that apply on whichever device your app is installed on are stored in the roaming data store. Le impostazioni vengono sottoposte al roaming tra i dispositivi a cui l'utente è connesso con lo stesso account Microsoft e con la stessa versione dell'app installata.Settings are roamed between devices on which the user is signed in with the same Microsoft Account and have the same version of the app installed.

Con le impostazioni possono essere usati i seguenti tipi di dati: integer, double, float, char, string, Point, DateTime e altri.The following data types can be used with settings: integers, doubles, floats, chars, strings, Points, DateTimes, and more. È anche possibile archiviare le istanze della classe ApplicationDataCompositeValue che è utile quando sono presenti più impostazioni che devono essere trattate come un'unità.You can also store instances of the ApplicationDataCompositeValue class which is useful when there are multiple settings that should be treated as a unit. Ad esempio, la dimensione dei punti e il nome del tipo di carattere per visualizzare il testo nel riquadro di lettura dell'app devono essere salvati/ripristinati come singola unità.For example, a font name and point size for displaying text in the reading pane of your app should be saved/restored as a single unit. In tal modo si evita che un'impostazione non sia sincronizzata con l'altra a causa di ritardi del roaming di un'impostazione rispetto all'altra.This prevents one setting from getting out of sync with the other due to delays in roaming one setting before the other.

Ecco le principali API da conoscere per salvare o caricare le impostazioni dell'app:Here are the main APIs you need to know about to save or load app settings:

Salvare le impostazioni dell'appSave app settings

Per questa introduzione, l'articolo include due scenari semplici: salvare e caricare un'impostazione dell'app in locale ed eseguire il roaming di un'impostazione composita dimensione del tipo di carattere/tipo di carattere tra i dispositivi.For this introduction, we will focus on two simple scenarios: saving and loading an app setting locally, and roaming a composite font/font size setting between devices.

// Save a setting locally on the device
ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;
localSettings.Values["test setting"] = "a device specific setting";

// Save a composite setting that will be roamed between devices
ApplicationDataContainer roamingSettings = Windows.Storage.ApplicationData.Current.RoamingSettings;
Windows.Storage.ApplicationDataCompositeValue composite = new Windows.Storage.ApplicationDataCompositeValue();
composite["Font"] = "Calibri";
composite["FontSize"] = 11;
roamingSettings.Values["RoamingFontInfo"] = composite;

Salvare un'impostazione nel dispositivo locale ottenendo prima ApplicationDataContainer per l'archivio dei dati delle impostazioni locali con Windows.Storage.ApplicationData.Current.LocalSettings.Save a setting to the local device, by first getting an ApplicationDataContainer for the local settings data store with Windows.Storage.ApplicationData.Current.LocalSettings. Le coppie chiave/valore del dizionario assegnate a questa istanza vengono salvate nell'archivio dei dati delle impostazioni locali del dispositivo.Key/value dictionary pairs that you assign to this instance are saved in the local device setting data store.

Salvare un'impostazione di roaming usando un modello simile.Save a roaming setting using a similar pattern. Prima di tutto ottenere ApplicationDataContainer per l'archivio dei dati delle impostazioni di roaming con Windows.Storage.ApplicationData.Current.RoamingSettings.First get an ApplicationDataContainer for the roaming settings data store with Windows.Storage.ApplicationData.Current.RoamingSettings. Quindi assegnare le coppie chiave/valore a questa istanza.Then assign key/value pairs to this instance. Le coppie chiave/valore verranno automaticamente sottoposte al roaming tra i dispositivi.Those key/value pairs will automatically roam between devices.

Nel frammento di codice precedente, ApplicationDataCompositeValue archiviare più coppie chiave/valore.In the code snippet above, a ApplicationDataCompositeValue stores multiple key/value pairs. I valori compositi sono utili quando si hanno più impostazioni che devono essere sincronizzate tra loro.Composite values are useful when you have multiple settings that shouldn't get out of sync with each other. Quando ApplicationDataCompositeValue viene salvato, i valori vengono salvati e caricati come un'unità o in modo atomico.When you save a ApplicationDataCompositeValue, the values are saved and loaded as a unit, or atomically. In questo modo le impostazioni correlate tra loro non perderanno mai la sincronizzazione in quanto vengono sottoposte al roaming come unità anziché singolarmente.This way settings that are related won't get out of sync because they are roamed as a unit instead of individually.

Caricare le impostazioni dell'appLoad app settings

// load a setting that is local to the device
ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;
String localValue = localSettings.Values["test setting"] as string;

// load a composite setting that roams between devices
ApplicationDataContainer roamingSettings = Windows.Storage.ApplicationData.Current.RoamingSettings;
Windows.Storage.ApplicationDataCompositeValue composite = (ApplicationDataCompositeValue)roamingSettings.Values["RoamingFontInfo"];
if (composite != null)
{
    String fontName = composite["Font"] as string;
    int fontSize = (int)composite["FontSize"];
}

Caricare un'impostazione dal dispositivo locale ottenendo prima un'istanza di ApplicationDataContainer per l'archivio dei dati delle impostazioni locali con Windows.Storage.ApplicationData.Current.LocalSettings.Load a setting from the local device, by first getting an ApplicationDataContainer instance for the local settings data store with Windows.Storage.ApplicationData.Current.LocalSettings. Quindi usarla per recuperare le coppie chiave/valore.Then use it to retrieve key/value pairs.

Caricare un'impostazione di roaming seguendo un modello simile.Load a roaming setting by following a similar pattern. Prima di tutto ottenere un'istanza di ApplicationDataContainer dall'archivio dei dati delle impostazioni di roaming con Windows.Storage.ApplicationData.Current.RoamingSettings.First get an ApplicationDataContainer instance from the roaming settings data store with Windows.Storage.ApplicationData.Current.RoamingSettings. Accedere alle coppie chiave/valore da tale istanza.Access key/value pairs from that instance. Se i dati non sono stati ancora sottoposti al roaming nel dispositivo da cui si esegue l'accesso alle impostazioni, verrà restituita un'istanza di ApplicationDataContainer null.If the data hasn't roamed yet to the device that you are accessing the settings from, you'll get a null ApplicationDataContainer. Ecco perché è presente un controllo if (composite != null) nel codice di esempio precedente.That's why there is a if (composite != null) check in the example code above.

API e documentazione utiliUseful APIs and docs

Ecco un breve riepilogo delle API e altra documentazione utili per iniziare a salvare e caricare le impostazioni dell'app.Here is a quick summary of APIs, and other useful documentation, to help get you started saving and loading app settings.

API utiliUseful APIs

APIAPI DescriptionDescription
ApplicationData.LocalSettingsApplicationData.LocalSettings Ottiene il contenitore delle impostazioni dell'applicazione dall'archivio dei dati locali dell'app.Gets the application settings container from the local app data store.
ApplicationData.RoamingSettingsApplicationData.RoamingSettings Ottiene il contenitore delle impostazioni dell'applicazione dall'archivio dei dati di roaming dell'app.Gets the application settings container from the roaming app data store.
ApplicationDataContainerApplicationDataContainer Contenitore per le impostazioni dell'app che supporta la creazione, l'eliminazione, l'enumerazione e l'attraversamento della gerarchia di contenitori.A container for app settings that supports creating, deleting, enumerating, and traversing the container hierarchy.
Windows.UI.ApplicationSettings NamespaceWindows.UI.ApplicationSettings Namespace Fornisce le classi che veranno usate per definire le impostazioni dell'app che vengono visualizzate nel riquadro delle impostazioni della shell di Windows.Provides classes that you'll use to define the app settings that appear in the settings pane of the Windows shell.

Documentazione utileUseful docs

ArgomentoTopic DescriptionDescription
Linee guida per le impostazioni dell'appGuidelines for app settings Descrive le procedure consigliate per la creazione e la visualizzazione delle impostazioni di un'app.Describes best practices for creating and displaying app settings.
Archiviare e recuperare le impostazioni e altri dati dell'appStore and retrieve settings and other app data Procedura dettagliata per salvare e recuperare le impostazioni, incluse le impostazioni di roaming.Walk-through for saving and retrieving settings, including roaming settings.

Esempi utili di codiceUseful code samples

Esempio di codiceCode sample DescriptionDescription
Esempio di dati applicazioneApplication data sample 2-4 scenari relativi alle impostazioniScenarios 2-4 focus on settings