Architettura Impostazioni applicazioneApplication Settings Architecture

Questo argomento descrive il funzionamento dell'architettura Impostazioni applicazione e ne analizza le funzionalità avanzate, come i raggruppamenti e le chiavi delle impostazioni.This topic describes how the Application Settings architecture works, and explores advanced features of the architecture, such as grouped settings and settings keys.

L'architettura di Impostazioni applicazione supporta la definizione delle impostazioni fortemente tipizzate con ambito di applicazione o utente e la persistenza delle impostazioni tra sessioni dell'applicazione.The application settings architecture supports defining strongly typed settings with either application or user scope, and persisting the settings between application sessions. L'architettura fornisce un motore di persistenza predefinito per salvare le impostazioni e caricarle dal file system locale.The architecture provides a default persistence engine for saving settings to and loading them from the local file system. L'architettura definisce inoltre le interfacce per offrire un motore di persistenza personalizzato.The architecture also defines interfaces for supplying a custom persistence engine.

Si tratta di interfacce che consentono ai componenti personalizzati di mantenere le proprie impostazioni quando sono ospitati in un'applicazione.Interfaces are provided that enable custom components to persist their own settings when they are hosted in an application. Usando le chiavi delle impostazioni, i componenti possono mantenere le impostazioni per più istanze del componente separato.By using settings keys, components can keep settings for multiple instances of the component separate.

Definizione delle impostazioniDefining Settings

L'architettura delle impostazioni applicazione viene usata sia in ASP.NETASP.NET che in Windows Form e contiene un numero di classi di base condivise in entrambi gli ambienti.The application settings architecture is used within both ASP.NETASP.NET and Windows Forms, and it contains a number of base classes that are shared across both environments. La più importante è SettingsBase, che fornisce accesso alle impostazioni di una raccolta e fornisce metodi di basso livello per il caricamento e salvataggio delle impostazioni.The most important is SettingsBase, which provides access to settings through a collection, and provides low-level methods for loading and saving settings. Ogni ambiente implementa propria classe derivata da SettingsBase per fornire funzionalità di impostazioni aggiuntive per tale ambiente.Each environment implements its own class derived from SettingsBase to provide additional settings functionality for that environment. In un'applicazione basata su Windows Form, tutte le impostazioni dell'applicazione devono essere definite in una classe derivata dal ApplicationSettingsBase (classe), che aggiunge le funzionalità seguenti alla classe di base:In a Windows Forms-based application, all application settings must be defined on a class derived from the ApplicationSettingsBase class, which adds the following functionality to the base class:

  • Caricamento e salvataggio delle operazioni di livello superioreHigher-level loading and saving operations

  • Supporto per le impostazioni con ambito utenteSupport for user-scoped settings

  • Ripristino delle impostazioni dell'utente alle impostazioni predefiniteReverting a user's settings to the predefined defaults

  • Aggiornamento delle impostazioni da una versione precedente dell'applicazioneUpgrading settings from a previous application version

  • Convalida delle impostazioni, prima che vengano modificate o prima che vengano salvateValidating settings, either before they are changed or before they are saved

Le impostazioni possono essere descritte con un numero di attributi definiti all'interno di System.Configuration spazio dei nomi, descritti attributi delle impostazioni dell'applicazione.The settings can be described using a number of attributes defined within the System.Configuration namespace; these are described in Application Settings Attributes. Quando si definisce un'impostazione, è necessario applicare con ApplicationScopedSettingAttribute o UserScopedSettingAttribute, che descrive se l'impostazione si applica all'intera applicazione o solo per l'utente corrente.When you define a setting, you must apply it with either ApplicationScopedSettingAttribute or UserScopedSettingAttribute, which describes whether the setting applies to the entire application or just to the current user.

L'esempio di codice seguente definisce una classe di impostazioni personalizzate con una singola impostazione, BackgroundColor.The following code example defines a custom settings class with a single setting, BackgroundColor.

using System;
using System.Configuration;
using System.Drawing;

public class MyUserSettings : ApplicationSettingsBase
{
    [UserScopedSetting()]
    [DefaultSettingValue("white")]
    public Color BackgroundColor
    {
        get
        {
            return ((Color)this["BackgroundColor"]);
        }
        set
        {
            this["BackgroundColor"] = (Color)value;
        }
    }
}
Imports System.Configuration

Public Class MyUserSettings
    Inherits ApplicationSettingsBase
    <UserScopedSetting()> _
    <DefaultSettingValue("white")> _
    Public Property BackgroundColor() As Color
        Get
            BackgroundColor = Me("BackgroundColor")
        End Get

        Set(ByVal value As Color)
            Me("BackgroundColor") = value
        End Set
    End Property
End Class

Persistenza delle impostazioniSettings Persistence

Il ApplicationSettingsBase classe non vengono mantenute o caricare le impostazioni; tale operazione è effettuata al provider di impostazioni, una classe che deriva da SettingsProvider.The ApplicationSettingsBase class does not itself persist or load settings; this job falls to the settings provider, a class that derives from SettingsProvider. Se una classe derivata di ApplicationSettingsBase non specifica un provider di impostazioni mediante il SettingsProviderAttribute, il provider predefinito, quindi LocalFileSettingsProvider, viene utilizzato.If a derived class of ApplicationSettingsBase does not specify a settings provider through the SettingsProviderAttribute, then the default provider, LocalFileSettingsProvider, is used.

Il sistema di configurazione che è stato rilasciato originariamente con .NET Framework.NET Framework supporta l'offerta di dati di configurazione dell'applicazione statici tramite file machine.config del computer locale o in un file app..exe.config da distribuire con l'applicazione.The configuration system that was originally released with the .NET Framework.NET Framework supports providing static application configuration data through either the local computer's machine.config file or within an app.exe.config file that you deploy with your application. La LocalFileSettingsProvider classe espande il supporto nativo nei modi seguenti:The LocalFileSettingsProvider class expands this native support in the following ways:

  • Le impostazioni con ambito applicazione possono essere archiviate in entrambi i file machine.config o app.exe.config.Application-scoped settings can be stored in either the machine.config or app.exe.config files. Il file machine.config è sempre di sola lettura, mentre app.exe.config è limitato dalle considerazioni sulla sicurezza alla sola lettura per la maggior parte delle applicazioni.Machine.config is always read-only, while app.exe.config is restricted by security considerations to read-only for most applications.

  • Le impostazioni con ambito di utente possono essere archiviate in app.exe.config, in questo caso vengono considerate come valori predefiniti statici.User-scoped settings can be stored in app.exe.config files, in which case they are treated as static defaults.

  • Le impostazioni con ambito di utente non predefinite sono archiviate in un nuovo file utente.config, dove user è il nome dell'utente che esegue l'applicazione in quel momento.Non-default user-scoped settings are stored in a new file, user.config, where user is the user name of the person currently executing the application. È possibile specificare un valore predefinito per un'impostazione con ambito di utente con DefaultSettingValueAttribute.You can specify a default for a user-scoped setting with DefaultSettingValueAttribute. Poiché le impostazioni con ambito utente spesso cambiano durante l'esecuzione dell'applicazione, user.config è sempre di lettura o scrittura.Because user-scoped settings often change during application execution, user.config is always read/write.

I tre file di configurazione archiviano le impostazioni in formato XML.All three configuration files store settings in XML format. L'elemento XML di livello superiore per le impostazioni con ambito di applicazione è <appSettings>, mentre <userSettings> viene usato per le impostazioni con ambito di utente.The top-level XML element for application-scoped settings is <appSettings>, while <userSettings> is used for user-scoped settings. Un file app.exe.config che contiene sia le impostazioni con ambito di applicazione che quelle predefinite per le impostazioni con ambito utente si presenta come segue:An app.exe.config file which contains both application-scoped settings and defaults for user-scoped settings would look like this:

<?xml version="1.0" encoding="utf-8" ?>  
<configuration>  
    <configSections>  
        <sectionGroup name="applicationSettings" type="System.Configuration.ApplicationSettingsGroup, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" >  
            <section name="WindowsApplication1.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />  
        </sectionGroup>  
        <sectionGroup name="userSettings" type="System.Configuration.UserSettingsGroup, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" >  
            <section name="WindowsApplication1.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" allowExeDefinition="MachineToLocalUser" />  
        </sectionGroup>  
    </configSections>  
    <applicationSettings>  
        <WindowsApplication1.Properties.Settings>  
            <setting name="Cursor" serializeAs="String">  
                <value>Default</value>  
            </setting>  
            <setting name="DoubleBuffering" serializeAs="String">  
                <value>False</value>  
            </setting>  
        </WindowsApplication1.Properties.Settings>  
    </applicationSettings>  
    <userSettings>  
        <WindowsApplication1.Properties.Settings>  
            <setting name="FormTitle" serializeAs="String">  
                <value>Form1</value>  
            </setting>  
            <setting name="FormSize" serializeAs="String">  
                <value>595, 536</value>  
            </setting>  
        </WindowsApplication1.Properties.Settings>  
    </userSettings>  
</configuration>  

Per una definizione degli elementi all'interno della sezione di impostazioni applicazione di un file di configurazione, vedere Application Settings Schema (Schema di impostazioni applicazione).For a definition of the elements within the application settings section of a configuration file, see Application Settings Schema.

Associazioni delle impostazioniSettings Bindings

Le impostazioni applicazione usano l'architettura di associazione dati di Windows Form per consentire la comunicazione bidirezionale degli aggiornamenti delle impostazioni tra i componenti e l'oggetto impostazioni.Application settings uses the Windows Forms data binding architecture to provide two-way communication of settings updates between the settings object and components. Se si usa Visual Studio per creare le impostazioni dell'applicazione e assegnarle alle proprietà del componente, queste associazioni vengono generate automaticamente.If you use Visual Studio to create application settings and assign them to component properties, these bindings are generated automatically.

È possibile associare solo un'impostazione dell'applicazione per un componente che supporta il IBindableComponent interfaccia.You can only bind an application setting to a component that supports the IBindableComponent interface. Inoltre, il componente deve implementare un evento di modifica per una specifica proprietà associata o notificare le impostazioni dell'applicazione che è stata modificata la proprietà tramite il INotifyPropertyChanged interfaccia.Also, the component must implement a change event for a specific bound property, or notify application settings that the property has changed through the INotifyPropertyChanged interface. Se il componente non implementa IBindableComponent e si vuole associare tramite Visual Studio, le proprietà associate verranno impostate la prima volta, ma non verranno aggiornate.If the component does not implement IBindableComponent and you are binding through Visual Studio, the bound properties will be set the first time, but will not update. Se il componente implementa IBindableComponent ma le notifiche di modifica non proprietà di supporto, l'associazione non verrà aggiornata nel file di impostazioni quando la proprietà viene modificata.If the component implements IBindableComponent but does not support property change notifications, the binding will not update in the settings file when the property is changed.

Alcuni componenti di Windows Form, ad esempio ToolStripItem, non supportano le associazioni delle impostazioni.Some Windows Forms components, such as ToolStripItem, do not support settings bindings.

Serializzazione delle impostazioniSettings Serialization

Quando LocalFileSettingsProvider deve salvare le impostazioni su disco, esegue le azioni seguenti:When LocalFileSettingsProvider must save settings to disk, it performs the following actions:

  1. Utilizza la reflection per esaminare tutte le proprietà definite per il ApplicationSettingsBase trovando quelle applicate con la classe derivata ApplicationScopedSettingAttribute o UserScopedSettingAttribute.Uses reflection to examine all of the properties defined on your ApplicationSettingsBase derived class, finding those that are applied with either ApplicationScopedSettingAttribute or UserScopedSettingAttribute.

  2. Serializza la proprietà su disco.Serializes the property to disk. Primo tentativo di chiamare il ConvertToString o ConvertFromString su associata al tipo TypeConverter.It first attempts to call the ConvertToString or ConvertFromString on the type's associated TypeConverter. Se il tentativo non riesce, usa la serializzazione XML.If this does not succeed, it uses XML serialization instead.

  3. Determina quali impostazioni vanno inserite in ciascun file, in base all'attributo dell'impostazione.Determines which settings go in which files, based on the setting's attribute.

Se si implementa la classe di impostazioni, è possibile utilizzare il SettingsSerializeAsAttribute per contrassegnare un'impostazione per la serializzazione binaria o personalizzata usando il SettingsSerializeAs enumerazione.If you implement your own settings class, you can use the SettingsSerializeAsAttribute to mark a setting for either binary or custom serialization using the SettingsSerializeAs enumeration. Per altre informazioni sulla creazione della propria classe di impostazioni nel codice, vedere How to: Create Application Settings (Procedura: creare impostazioni applicazioni).For more information on creating your own settings class in code, see How to: Create Application Settings.

Percorsi dei file delle impostazioniSettings File Locations

Il percorso dei file app.exe.config e user.config variano in base alle modalità di installazione dell'applicazione.The location of the app.exe.config and user.config files will differ based on how the application is installed. Per un'applicazione basata su Windows Form copiata nel computer locale, app. exe. config si trova nella stessa directory come directory di base del file eseguibile principale dell'applicazione, e utente. config cui risiederà il percorso specificato per il Application.LocalUserAppDataPath proprietà.For a Windows Forms-based application copied onto the local computer, app.exe.config will reside in the same directory as the base directory of the application's main executable file, and user.config will reside in the location specified by the Application.LocalUserAppDataPath property. Per un'applicazione installata tramite ClickOnceClickOnce, entrambi questi file si troveranno nella Directory dati ClickOnceClickOnce %InstallRoot%\Documents e Impostazioni\nome utente\Impostazioni locali.For an application installed by means of ClickOnceClickOnce, both of these files will reside in the ClickOnceClickOnce Data Directory underneath %InstallRoot%\Documents and Settings\username\Local Settings.

Il percorso di archiviazione di questi file è leggermente diverso se un utente ha abilitato i profili di roaming, che consentono all'utente di definire diverse impostazioni di Windows e dell'applicazione quando usa altri computer all'interno di un dominio.The storage location of these files is slightly different if a user has enabled roaming profiles, which enables a user to define different Windows and application settings when he or she is using other computers within a domain. In tal caso, sia le applicazioni ClickOnceClickOnce che quelle diverse da ClickOnceClickOnce dispongono dei propri file app.exe.config e user.config archiviati in %InstallRoot%\Documenti e Impostazioni\nome utente\Application Data.In that case, both ClickOnceClickOnce applications and non-ClickOnceClickOnce applications will have their app.exe.config and user.config files stored under %InstallRoot%\Documents and Settings\username\Application Data.

Per altre informazioni sul funzionamento delle funzioni di Impostazioni applicazione con la nuova tecnologia di distribuzione, vedere Impostazioni dell'applicazione e ClickOnce.For more information about how the Application Settings feature works with the new deployment technology, see ClickOnce and Application Settings. Per altre informazioni sulla directory dei dati ClickOnceClickOnce, vedere Accesso a dati locali e remoti in applicazioni ClickOnce.For more information about the ClickOnceClickOnce Data Directory, see Accessing Local and Remote Data in ClickOnce Applications.

Impostazioni e sicurezza dell'applicazioneApplication Settings and Security

Le impostazioni dell'applicazione sono progettate per funzionare in attendibilità parziale, un ambiente con restrizioni predefinito per le applicazioni di Windows Form ospitate in Internet o intranet.Application settings are designed to work in partial trust, a restricted environment that is the default for Windows Forms applications hosted over the Internet or an intranet. Non sono necessarie autorizzazioni speciali oltre all'attendibilità parziale per usare le impostazioni dell'applicazione con il provider di impostazioni predefinito.No special permissions beyond partial trust are needed to use application settings with the default settings provider.

Quando si usano le impostazioni dell'applicazione in un'applicazione ClickOnceClickOnce, il file user.config è archiviato nella directory dei dati di ClickOnceClickOnce.When application settings are used in a ClickOnceClickOnce application, the user.config file is stored in the ClickOnceClickOnce data directory. Le dimensioni del file user.config dell'applicazione non possono superare la quota della directory dei dati impostata da ClickOnceClickOnce.The size of the application's user.config file cannot exceed the data directory quota set by ClickOnceClickOnce. Per altre informazioni, vedere Impostazioni dell'applicazione e ClickOnce.For more information, see ClickOnce and Application Settings.

Provider di impostazioni personalizzateCustom Settings Providers

Nell'architettura Impostazioni applicazione, è disponibile un accoppiamento libero tra le impostazioni di applicazioni wrapper classe, derivata da ApplicationSettingsBase, e il provider di impostazioni associati, derivati dalla classe SettingsProvider.In the Application Settings architecture, there is a loose coupling between the applications settings wrapper class, derived from ApplicationSettingsBase, and the associated settings provider or providers, derived from SettingsProvider. Questa associazione viene definita solo per il SettingsProviderAttribute applicato alla classe wrapper o alle singole proprietà.This association is defined only by the SettingsProviderAttribute applied to the wrapper class or its individual properties. Se le impostazioni di un provider non è in modo esplicito specificato, il provider predefinito, LocalFileSettingsProvider, viene utilizzato.If a settings provider is not explicitly specified, the default provider, LocalFileSettingsProvider, is used. Di conseguenza, questa architettura supporta la creazione e l'uso di provider di impostazioni personalizzate.As a result, this architecture supports creating and using custom settings providers.

Si supponga, ad esempio, di voler sviluppare e usare SqlSettingsProvider, un provider che archivierà tutti i dati delle impostazioni in un database Microsoft SQL Server.For example, suppose that you want to develop and use SqlSettingsProvider, a provider that will store all settings data in a Microsoft SQL Server database. Il SettingsProvider-classe derivata riceverebbe queste informazioni nella relativa Initialize metodo come un parametro di tipo System.Collections.Specialized.NameValueCollection.Your SettingsProvider-derived class would receive this information in its Initialize method as a parameter of type System.Collections.Specialized.NameValueCollection. È quindi necessario implementare la GetPropertyValues metodo per recuperare le impostazioni dall'archivio dati, e SetPropertyValues salvarle.You would then implement the GetPropertyValues method to retrieve your settings from the data store, and SetPropertyValues to save them. Il provider è possibile utilizzare il SettingsPropertyCollection fornito a GetPropertyValues per determinare la proprietà nome tipo e ambito, nonché eventuali altre impostazioni degli attributi definiti per tale proprietà.Your provider can use the SettingsPropertyCollection supplied to GetPropertyValues to determine the property's name, type, and scope, as well as any other settings attributes defined for that property.

Il provider dovrà implementare una proprietà e un metodo le cui implementazioni possono non essere evidenti.Your provider will need to implement one property and one method whose implementations may not be obvious. Il ApplicationName è una proprietà astratta di SettingsProvider; programmarla per restituire le operazioni seguenti:The ApplicationName property is an abstract property of SettingsProvider; you should program it to return the following:

public override string ApplicationName
{
    get
    {
        return (System.Reflection.Assembly.GetExecutingAssembly().GetName().Name);
    }
    set
    {
        // Do nothing.
    }
}
Public Overrides Property ApplicationName() As String
    Get
        ApplicationName = System.Reflection.Assembly.GetExecutingAssembly().GetName().Name
    End Get
    Set(ByVal value As String)
        ' Do nothing.
    End Set
End Property

La classe derivata deve implementare anche un metodo Initialize che non accetta argomenti e non restituisce alcun valore.Your derived class must also implement an Initialize method that takes no arguments and returns no value. Questo metodo non è definito da SettingsProvider.This method is not defined by SettingsProvider.

Infine, implementano IApplicationSettingsProvider per il provider per fornire supporto per l'aggiornamento delle impostazioni di ripristino dei valori predefiniti e l'aggiornamento dalla versione di un'applicazione a un altro.Finally, you implement IApplicationSettingsProvider on your provider to provide support for refreshing settings, reverting settings to their defaults, and upgrading settings from one application version to another.

Dopo aver implementato e compilato il provider, è necessario istruire una classe di impostazioni affinché usi questo provider invece di quello predefinito.Once you have implemented and compiled your provider, you need to instruct your settings class to use this provider instead of the default. Eseguire tale operazione mediante la SettingsProviderAttribute.You accomplish this through the SettingsProviderAttribute. Se applicato a un'intera classe di impostazioni, viene utilizzato il provider per ogni impostazione che definisce la classe; Se applicato a singole impostazioni, architettura Impostazioni applicazione utilizza il provider per le impostazioni specificate e Usa LocalFileSettingsProvider per il resto.If applied to an entire settings class, the provider is used for each setting that the class defines; if applied to individual settings, Application Settings architecture uses that provider for those settings only, and uses LocalFileSettingsProvider for the rest. L'esempio di codice seguente illustra come indicare alla classe di impostazioni l'uso del provider personalizzato.The following code example shows how to instruct the settings class to use your custom provider.

using System;
using System.Collections.Generic;
using System.Text;
using System.Configuration;

namespace ApplicationSettingsArchitectureCS
{
    [SettingsProvider("SqlSettingsProvider")]
    class CustomSettings : ApplicationSettingsBase
    {
        // Implementation goes here.
    }
}
Imports System.Configuration

<SettingsProvider("SqlSettingsProvider")> _
Public Class CustomSettings
    Inherits ApplicationSettingsBase

    ' Implementation goes here.
End Class

Un provider può essere chiamato da più thread contemporaneamente, ma scriverà sempre nello stesso percorso di archiviazione; pertanto l'architettura di Impostazioni applicazione creerà sempre una sola istanza della classe del provider.A provider may be called from multiple threads simultaneously, but it will always write to the same storage location; therefore, the Application Settings architecture will only ever instantiate a single instance of your provider class.

Importante

È necessario assicurarsi che il provider sia thread-safe e che consenta solo a un thread alla volta di scrivere i file di configurazione.You should ensure that your provider is thread-safe, and only allows one thread at a time to write to the configuration files.

Il provider non è necessario supportare tutte le impostazioni di attributi definiti nel System.Configuration dello spazio dei nomi, ma deve un supporto minimo ApplicationScopedSettingAttribute e UserScopedSettingAttributee deve inoltre supportare DefaultSettingValueAttribute.Your provider does not need to support all of the settings attributes defined in the System.Configuration namespace, though it must at a minimum support ApplicationScopedSettingAttribute and UserScopedSettingAttribute, and should also support DefaultSettingValueAttribute. Per gli attributi che non supporta, il provider deve semplicemente dare esito negativo senza notifica e non deve generare un'eccezione.For those attributes that it does not support, your provider should just fail without notification; it should not throw an exception. Se la classe di impostazioni utilizza una combinazione valida di attributi, tuttavia, ad esempio l'applicazione ApplicationScopedSettingAttribute e UserScopedSettingAttribute alla stessa impostazione, il provider deve generare un'eccezione e annullare l'operazione.If the settings class uses an invalid combination of attributes, however — such as applying ApplicationScopedSettingAttribute and UserScopedSettingAttribute to the same setting — your provider should throw an exception and cease operation.

Vedere ancheSee Also

ApplicationSettingsBase
SettingsProvider
LocalFileSettingsProvider
Cenni preliminari sulle impostazioni delle applicazioniApplication Settings Overview
Application Settings for Custom Controls (Impostazioni delle applicazioni per i controlli personalizzati)Application Settings for Custom Controls
Impostazioni dell'applicazione e ClickOnceClickOnce and Application Settings
Schema Application SettingsApplication Settings Schema