Utilizzo delle classi di configurazione
Aggiornamento: novembre 2007
La maggior parte delle operazioni di configurazione viene eseguita con la classe Configuration, che rappresenta le configurazioni di computer, applicazioni client .NET, applicazioni ASP.NET, directory Web e risorse memorizzate nelle directory Web.
In ASP.NET versione 2.0 è possibile avere accesso a un'istanza della classe Configuration utilizzando i metodi dell'oggetto WebConfigurationManager per ottenere una sezione di configurazione. Nelle applicazioni client .NET Framework è possibile utilizzare l'analogo oggetto ConfigurationManager. A ogni sezione di configurazione corrisponde un tipo di oggetto, elencato come gestore di sezione nella tabella relativa alle informazioni sugli elementi negli argomenti di riferimento in Impostazioni di configurazione di ASP.NET. Per un esempio, vedere Procedura: accedere alle impostazioni di configurazione ASP.NET a livello di codice.
Nelle seguenti sezioni viene descritto come utilizzare le classi di configurazione in scenari diversi. Per un riepilogo delle classi di configurazione, vedere Cenni preliminari sulle API di configurazione di ASP.NET.
In tutti gli esempi riportati di seguito vengono utilizzati i metodi non statici Configuration.GetSection e Configuration.GetSectionGroup creando prima un'istanza della classe System.Configuration.Configuration. In questo modo è possibile ottenere le informazioni sulla configurazione da qualsiasi applicazione. Se si desidera ottenere informazioni sulla configurazione dall'applicazione in cui si trova il codice, è preferibile utilizzare i metodi statici GetSection che presentano tempi di elaborazione ridotti. Per ulteriori informazioni, vedere la sezione "Utilizzo di impostazioni di configurazione locali e remote" in Cenni preliminari sulle API di configurazione di ASP.NET.
Apertura di un oggetto di configurazione mappato alle impostazioni di configurazione globale
Per aprire un file di configurazione per la configurazione globale, l'applicazione chiama il metodo statico OpenMachineConfiguration della classe WebConfigurationManager. Nell'esempio di codice riportato di seguito il metodo OpenMachineConfiguration apre e restituisce l'oggetto di configurazione corrispondente al file Machine.config di .NET Framework 2.0. Altre versioni del metodo di overload consentono di specificare una posizione, un server remoto o le informazioni utente.
' Obtains the machine configuration settings on the local machine.
Dim machineConfig As System.Configuration.Configuration
machineConfig = _
System.Web.Configuration.WebConfigurationManager.OpenMachineConfiguration()
machineConfig.SaveAs("c:\machineConfig.xml")
// Obtains the machine configuration settings on the local machine.
System.Configuration.Configuration machineConfig =
System.Web.Configuration.WebConfigurationManager.OpenMachineConfiguration();
machineConfig.SaveAs("c:\\machineConfig.xml");
L'API di configurazione è specifica della versione. Pertanto, non è possibile aprire il file Machine.config di una versione di .NET Framework utilizzando i metodi inclusi in un'altra versione di .NET Framework.
Privilegi necessari
Per aprire il file di configurazione del computer, è necessario che l'applicazione disponga dell'autorizzazione di lettura per il file Machine.config fisico. Per modificare la configurazione del computer, è necessario che l'applicazione disponga dell'autorizzazione di scrittura per il file e dei privilegi di creazione per la directory di configurazione di .NET Framework.
Apertura di un oggetto di configurazione mappato alle impostazioni di configurazione dell'applicazione Web
Per aprire il file di configurazione di un'applicazione Web, l'applicazione chiama il metodo statico OpenWebConfiguration della classe WebConfigurationManager, passando il percorso relativo della directory virtuale di Internet Information Services (IIS) da aprire.
È possibile ottenere i valori del parametro di percorso dal percorso nella metabase di IIS della directory contenente la configurazione necessaria. Se, ad esempio, il percorso nella metabase di IIS è W3SVC/1/Root/Temp, il percorso è /Temp perché il sito predefinito è 1.
Nell'esempio di codice riportato di seguito il metodo OpenWebConfiguration apre e restituisce l'oggetto di configurazione corrispondente all'applicazione Web Temp nel sito Web predefinito. L'oggetto di configurazione include le impostazioni di configurazione specificate localmente in un file Web.config e tutte le impostazioni ereditate dai file di configurazione padre, fino a risalire al file Machine.config. Altre versioni del metodo di overload consentono di specificare un sito Web, una posizione, un server remoto e le informazioni utente.
' Obtains the configuration settings for a Web application.
Dim webConfig As System.Configuration.Configuration
webConfig = _
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp")
webConfig.SaveAs("c:\\webConfig.xml")
// Obtains the configuration settings for a Web application.
System.Configuration.Configuration webConfig =
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp");
webConfig.SaveAs("c:\\webConfig.xml");
È possibile aprire un oggetto System.Configuration.Configuration anche quando non esiste un file Web.config fisico. In questo caso, la configurazione restituita è costituita esclusivamente da impostazioni ereditate dalla gerarchia di file di configurazione. Per ulteriori informazioni, vedere Scenari di configurazione ASP.NET.
Privilegi necessari
Per aprire un file di configurazione Web, è necessario che l'applicazione disponga dell'autorizzazione di lettura per il file Web.config fisico e per tutti i file padre nella gerarchia.
Apertura di un oggetto di configurazione mappato a una sezione di un file di configurazione
Per ottenere le informazioni sulla configurazione da una sezione, l'applicazione chiama il metodo non statico GetSectionGroup della classe Configuration, passando il nome della sezione. Per le sezioni contenute in gruppi di sezioni, è possibile utilizzare un XPath alla sezione (system.web/anonymousIdentification) o ottenere un oggetto di configurazione già mappato al gruppo di sezioni. Per un elenco di nomi di sezione, vedere Impostazioni di configurazione di ASP.NET.
Nell'esempio di codice riportato di seguito il metodo OpenWebConfiguration apre e restituisce l'oggetto di configurazione corrispondente all'applicazione Web Temp nel sito Web predefinito, quindi utilizza tale oggetto per ottenere un riferimento al gruppo di sezioni system.web, che viene quindi utilizzato per ottenere un riferimento alla sezione anonymousIdentification.
' Obtains the configuration settings for the <anonymousIdentification> section.
Dim config As System.Configuration.Configuration
config = _
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp")
Dim systemWeb As System.Web.Configuration.SystemWebSectionGroup
systemWeb = config.GetSectionGroup("system.web")
Dim sectionConfig As System.Web.Configuration.AnonymousIdentificationSection
sectionConfig = systemWeb.AnonymousIdentification
Dim sb As New StringBuilder
sb.AppendLine("<anonymousIdentification> attributes:")
Dim props As System.Configuration.PropertyInformationCollection
props = sectionConfig.ElementInformation.Properties
For Each prop As System.Configuration.PropertyInformation In props
sb.Append(prop.Name.ToString())
sb.Append(" = ")
sb.AppendLine(prop.Value.ToString())
Next
Console.WriteLine(sb.ToString())
// Obtains the configuration settings for the <anonymousIdentification> section.
System.Configuration.Configuration config =
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp");
System.Web.Configuration.SystemWebSectionGroup systemWeb =
config.GetSectionGroup("system.web")
as System.Web.Configuration.SystemWebSectionGroup;
System.Web.Configuration.AnonymousIdentificationSection sectionConfig =
systemWeb.AnonymousIdentification;
if (null != sectionConfig)
{
StringBuilder sb = new StringBuilder();
sb.Append("<anonymousIdentification> attributes:\r\n");
System.Configuration.PropertyInformationCollection props =
sectionConfig.ElementInformation.Properties;
foreach (System.Configuration.PropertyInformation prop in props)
{
sb.AppendFormat("{0} = {1}\r\n", prop.Name.ToString(), prop.Value.ToString());
}
Console.WriteLine(sb.ToString());
}
È possibile aprire un oggetto System.Configuration.Configuration anche quando non esiste un file Web.config fisico. In questo caso, la configurazione restituita è costituita esclusivamente da impostazioni ereditate dalla gerarchia di file di configurazione. Per ulteriori informazioni, vedere Scenari di configurazione ASP.NET.
Privilegi necessari
Per aprire una sezione in un file di configurazione Web, è necessario che l'applicazione disponga dell'autorizzazione di lettura per il file Web.config fisico e per tutti i file padre nella gerarchia. Le applicazioni con codice gestito devono disporre dell'autorizzazione per leggere le sezioni di sistema. Le applicazioni con attendibilità totale e con attendibilità elevata dispongono di queste autorizzazioni per impostazione predefinita, vale a dire che, per impostazione predefinita, le applicazioni con attendibilità media e inferiore non saranno in grado di leggere le sezioni di configurazione.
Apertura di un oggetto di configurazione mappato alle impostazioni di configurazione remota
È possibile utilizzare l'API di configurazione per aprire la configurazione di un computer remoto. L'API consente di aprire il file di configurazione di un altro computer o il file di configurazione di qualsiasi applicazione IIS o delle relative directory figlio.
Per aprire il file di configurazione di un altro computer, l'applicazione chiama il metodo statico OpenMachineConfiguration, passando il nome del server.
Per aprire un file Web.config su un altro computer, l'applicazione chiama il metodo statico OpenWebConfiguration, passando il percorso relativo al sito all'oggetto di configurazione, all'identificatore del sito e al nome del server. L'oggetto di configurazione restituito include le impostazioni di configurazione specificate localmente in un file Web.config e tutte le impostazioni ereditate dai file di configurazione padre, fino a risalire al file Machine.config.
I nomi di server sono nomi validi di computer di rete Windows. Questi nomi non sono gestiti in modo speciale da ASP.NET, ma vengono passati direttamente al sistema operativo.
Nell'esempio di codice seguente viene illustrata l'apertura di una configurazione di computer, della configurazione principale in un sito predefinito e di una configurazione Web in una directory di applicazione.
Dim userToken As IntPtr
userToken = System.Security.Principal.WindowsIdentity.GetCurrent().Token
' Obtains the machine configuration settings on a remote machine.
Dim remoteMachineConfig As System.Configuration.Configuration
remoteMachineConfig = _
System.Web.Configuration.WebConfigurationManager.OpenMachineConfiguration( _
Nothing, "JanetFi2", userToken)
remoteMachineConfig.SaveAs("c:\remoteMachineConfig.xml")
' Obtains the root Web configuration settings on a remote machine.
Dim remoteRootConfig As System.Configuration.Configuration
remoteRootConfig = _
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration( _
Nothing, Nothing, Nothing, "JanetFi2", userToken)
remoteRootConfig.SaveAs("c:\remoteRootConfig.xml")
' Obtains the configuration settings for the
' W3SVC/1/Root/Temp application on a remote machine.
Dim remoteWebConfig As System.Configuration.Configuration
remoteWebConfig = _
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration( _
"/Temp", "1", Nothing, "JanetFi2", userToken)
remoteWebConfig.SaveAs("c:\\remoteWebConfig.xml")
IntPtr userToken = System.Security.Principal.WindowsIdentity.GetCurrent().Token;
// Obtains the machine configuration settings on a remote machine.
System.Configuration.Configuration remoteMachineConfig =
System.Web.Configuration.WebConfigurationManager.OpenMachineConfiguration
(null, "ServerName", userToken);
remoteMachineConfig.SaveAs("c:\\remoteMachineConfig.xml");
// Obtains the root Web configuration settings on a remote machine.
System.Configuration.Configuration remoteRootConfig =
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration
(null, null, null, "ServerName", userToken);
remoteRootConfig.SaveAs("c:\\remoteRootConfig.xml");
// Obtains the configuration settings for the
// W3SVC/1/Root/Temp application on a remote machine.
System.Configuration.Configuration remoteWebConfig =
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration
("/Temp", "1", null, "ServerName", userToken);
remoteWebConfig.SaveAs("c:\\remoteWebConfig.xml");
Privilegi necessari
Per aprire un file di configurazione in un computer remoto, è necessario che l'applicazione disponga di autorizzazioni amministrative sul computer remoto. Questo requisito comporta restrizioni maggiori di quello per l'utilizzo locale. Per i file di configurazione locali, è sufficiente che l'applicazione disponga dell'autorizzazione di lettura per i file di configurazione nella gerarchia e per la metabase IIS, per risolvere i percorsi IIS.
Eseguire lo strumento Aspnet_regiis.exe con il parametro "-config+" sul computer remoto prima di configurarlo. Per ulteriori informazioni, vedere Strumento di ASP.NET per la registrazione di IIS (Aspnet_regiis.exe).
Aggiornamento delle impostazioni di configurazione
Per aggiornare un oggetto di configurazione aperto, l'applicazione chiama i metodi Save o SaveAs dell'oggetto di configurazione. Questi metodi scrivono le modifiche apportate alle impostazioni di configurazione di tale oggetto. Se in corrispondenza della posizione non esiste alcun file di configurazione, ne viene creato uno nuovo.
Nel seguente codice di esempio l'attributo debug della sezione compilation è impostato su true.
' Updates the configuration settings for a Web application.
Dim updateWebConfig As System.Configuration.Configuration
updateWebConfig = _
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp")
Dim compilation As System.Web.Configuration.CompilationSection
compilation = _
updateWebConfig.GetSection("system.web/compilation")
Console.WriteLine("Current <compilation> debug = {0}", compilation.Debug)
compilation.Debug = True
If Not compilation.SectionInformation.IsLocked Then
updateWebConfig.Save()
Console.WriteLine("New <compilation> debug = {0}", compilation.Debug)
Else
Console.WriteLine("Could not save configuration.")
End If
// Updates the configuration settings for a Web application.
System.Configuration.Configuration updateWebConfig =
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp");
System.Web.Configuration.CompilationSection compilation =
updateWebConfig.GetSection("system.web/compilation")
as System.Web.Configuration.CompilationSection;
Console.WriteLine("Current <compilation> debug = {0}", compilation.Debug);
compilation.Debug = true;
if (!compilation.SectionInformation.IsLocked)
{
updateWebConfig.Save();
Console.WriteLine("New <compilation> debug = {0}", compilation.Debug);
}
else
{
Console.WriteLine("Could not save configuration.");
}
Attualmente, non è disponibile alcuna funzionalità per bloccare i dati di configurazione durante l'aggiornamento. Pertanto, l'API di configurazione utilizza un modello di concorrenza ottimistica per la modifica della configurazione. Nel modello di concorrenza ottimistica, se due applicazioni aprono contemporaneamente la stessa configurazione, otterranno copie univoche dell'oggetto di configurazione. Se un'applicazione tenta di modificare la configurazione chiamando i metodi Save o SaveAs e il file di configurazione sottostante è stato modificato dopo che l'applicazione ha ottenuto l'oggetto di configurazione, il metodo genererà un'eccezione. È possibile che il file sottostante sia stato modificato da un'altra applicazione durante l'aggiornamento della configurazione o da altre modifiche apportate al file indipendentemente dall'API di configurazione.
Privilegi necessari
Per modificare una configurazione Web, è necessario che l'applicazione disponga dell'autorizzazione di scrittura per il file e dei privilegi di creazione per la directory che contiene il file.
Vedere anche
Concetti
Cenni preliminari sulle API di configurazione di ASP.NET