Utilisation des classes de configuration
Mise à jour : novembre 2007
La configuration est principalement prise en charge par la classe Configuration. Cette classe représente des configurations d'ordinateurs, des applications clientes .NET, des applications ASP.NET, des répertoires Web et des ressources stockés dans les répertoires Web.
Dans ASP.NET version 2.0, vous pouvez accéder à une instance de la classe Configuration à l'aide des méthodes de l'objet WebConfigurationManager pour obtenir une section de configuration (dans les applications clientes .NET Framework, vous pouvez utiliser l'objet ConfigurationManager similaire). Chaque section de configuration possède son propre type d'objet qui est répertorié en tant que gestionnaire de section dans le tableau « Informations sur les éléments » dans les rubriques de référence de Schéma des paramètres ASP.NET. Pour obtenir un exemple, consultez Comment : accéder par programme aux paramètres de configuration ASP.NET.
Les sections suivantes décrivent comment utiliser les classes de configuration dans différents scénarios. Pour obtenir un résumé des classes de configuration, consultez Vue d'ensemble de l'API de configuration ASP.NET.
Les exemples suivants utilisent les méthodes Configuration.GetSection et Configuration.GetSectionGroup non statiques en créant d'abord une instance de la classe System.Configuration.Configuration. Cela vous permet d'obtenir des informations de configuration d'une application quelconque. Si vous souhaitez obtenir des informations de configuration de l'application dans laquelle votre code réside, utilisez les méthodes GetSection statiques, plus rapides en termes de traitement. Pour plus d'informations, consultez la section « Manipulation des paramètres de configuration locaux et distants » dans Vue d'ensemble de l'API de configuration ASP.NET.
Ouverture d'un objet de configuration mappé à des paramètres de configuration globale
Pour ouvrir un fichier de configuration pour une configuration globale, votre application appelle la méthode statique OpenMachineConfiguration de la classe WebConfigurationManager. Dans l'exemple de code suivant, la méthode OpenMachineConfiguration ouvre et retourne l'objet de configuration qui correspond au fichier Machine.config du .NET Framework 2.0. Les autres versions de cette méthode surchargée vous permettent de spécifier un emplacement, un serveur distant ou des informations utilisateur.
' 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 de configuration est spécifique à la version. Par conséquent, il n'est pas possible d'ouvrir le fichier Machine.config pour une version du .NET Framework à l'aide des méthodes d'une autre version du .NET Framework.
Privilèges requis
Pour ouvrir le fichier de configuration machine, l'application requiert des droits d'accès en lecture sur le fichier Machine.config physique. Pour modifier la configuration machine, l'application requiert des autorisations en écriture sur le fichier et des privilèges de création sur le répertoire de configuration .NET Framework.
Ouverture d'un objet de configuration mappé aux paramètres de configuration de l'application Web
Pour ouvrir le fichier de configuration d'une application Web, votre application appelle la méthode statique OpenWebConfiguration de la classe WebConfigurationManager, en passant le chemin d'accès relatif du répertoire virtuel IIS (Internet Information Services) à ouvrir.
Les valeurs du paramètre de chemin d'accès peuvent être obtenues à partir du chemin d'accès à la métabase IIS du répertoire qui contient la configuration requise. Par exemple, si le chemin d'accès à la métabase IIS est W3SVC/1/Root/Temp, le chemin est /Temp parce que le site par défaut est 1.
Dans l'exemple de code suivant, la méthode OpenWebConfiguration ouvre et retourne l'objet de configuration qui correspond à l'application Web Temp du site Web par défaut. L'objet de configuration inclut des paramètres de configuration qui sont spécifiés localement dans un fichier Web.config et tous les paramètres hérités des fichiers de configuration parents, jusqu'au fichier Machine.config. Les autres versions de cette méthode surchargée vous permettent de spécifier le site Web, un emplacement, un serveur distant et des informations utilisateur.
' 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");
Il est possible d'ouvrir un objet System.Configuration.Configuration même en l'absence de fichier Web.config physique. Dans ce cas, la configuration retournée se compose essentiellement des paramètres qui sont hérités de la hiérarchie des fichiers de configuration. Pour plus d'informations, consultez Scénarios de configuration ASP.NET.
Privilèges requis
Pour ouvrir un fichier de configuration Web, l'application requiert les autorisations en lecture sur le fichier Web.config physique et sur tous les fichiers parents respectifs de la hiérarchie.
Ouverture d'un objet de configuration mappé à une section dans un fichier de configuration
Pour obtenir des informations de configuration d'une section, votre application appelle la méthode non statique GetSectionGroup de la classe Configuration, en passant le nom de section. Pour les sections contenues dans des groupes de sections, vous pouvez utiliser un XPath vers la section (system.web/anonymousIdentification) ou obtenir un objet de configuration d'abord mappé au groupe de sections. Pour obtenir la liste des noms de sections, consultez Paramètres de configuration ASP.NET.
Dans l'exemple de code suivant, la méthode OpenWebConfiguration ouvre et retourne l'objet de configuration qui correspond à l'application Web Temp du site Web par défaut, puis utilise cet objet pour obtenir une référence au groupe de sections system.web qui est utilisé ensuite pour obtenir une référence à la section 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());
}
Il est possible d'ouvrir un objet System.Configuration.Configuration même en l'absence de fichier Web.config physique. Dans ce cas, la configuration retournée se compose essentiellement des paramètres qui sont hérités de la hiérarchie des fichiers de configuration. Pour plus d'informations, consultez Scénarios de configuration ASP.NET.
Privilèges requis
Pour ouvrir une section dans un fichier de configuration Web, l'application requiert les autorisations en lecture sur le fichier Web.config physique et sur tous les fichiers parents respectifs de la hiérarchie. Les applications de code gérées doivent disposer de l'autorisation en lecture sur les sections système. Les applications de confiance totale et élevée disposent de ces autorisations par défaut. En d'autres termes, les applications disposant de niveaux de confiance moyens et inférieurs ne pourront pas lire les sections de configuration.
Ouverture d'un objet de configuration mappé à des paramètres de configuration distants
Vous pouvez utiliser l'API de configuration pour ouvrir la configuration d'un ordinateur distant. L'API peut ouvrir le fichier de configuration machine d'un autre ordinateur ou le fichier de configuration de l'application pour toute application IIS ou ses répertoires enfants.
Pour ouvrir un fichier de configuration machine sur un autre ordinateur, l'application appelle la méthode statique OpenMachineConfiguration, en passant le nom du serveur.
Pour ouvrir un fichier Web.config sur un autre ordinateur, l'application appelle la méthode statique OpenWebConfiguration, en passant le chemin d'accès relatif au site à l'objet de configuration, l'identificateur de site et le nom du serveur. L'objet de configuration retourné inclut des paramètres de configuration qui sont spécifiés localement dans un fichier Web.config et tous les paramètres hérités des fichiers de configuration parents, jusqu'au fichier Machine.config.
Les noms de serveurs sont des noms d'ordinateurs réseau Windows valides. Ces noms ne sont pas contrôlés spécialement par ASP.net, mais passés directement au système d'exploitation.
Les exemples de code suivants indiquent comment ouvrir une configuration machine, la configuration racine sur un site par défaut et une configuration Web dans un répertoire application.
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");
Privilèges requis
Pour ouvrir un fichier de configuration sur un ordinateur distant, l'application doit disposer d'autorisations administratives sur l'ordinateur distant. Ce prérequis est plus restrictif que celui d'une utilisation locale. Pour les fichiers de configuration locale, l'application requiert uniquement des autorisations en lecture sur les fichiers de configuration dans la hiérarchie et pour la métabase IIS (pour résoudre les chemins d'accès IIS).
Exécutez l'outil Aspnet_regiis.exe avec le paramètre "-config+" sur l'ordinateur distant avant d'essayer de le configurer. Pour plus d'informations, consultez ASP.NET IIS Registration, outil (Aspnet_regiis.exe).
Mise à jour des paramètres de configuration
Pour mettre à jour un objet de configuration ouvert, l'application appelle les méthodes Save ou SaveAs de l'objet de configuration. Ces méthodes écrivent les modifications apportées aux paramètres de configuration pour cet objet. Un fichier de configuration est créé si aucun fichier n'est défini à l'emplacement voulu.
L'exemple de code suivant affecte la valeur true à l'attribut debug de la section compilation.
' 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.");
}
Il n'existe actuellement aucune fonctionnalité disponible pour verrouiller des données de configuration lors de leur mise à jour. L'API de configuration utilise donc un modèle d'accès concurrentiel optimiste pour modifier la configuration. Dans le modèle d'accès concurrentiel optimiste, si deux applications ouvrent la même configuration simultanément, elles obtiendront des copies uniques de l'objet de configuration. Si une application tente de modifier la configuration en appelant les méthodes Save ou SaveAs alors que le fichier de configuration sous-jacent a été modifié depuis que l'application a obtenu l'objet de configuration, la méthode lèvera une exception. Le fichier sous-jacent a pu être modifié par une autre application mettant à jour la configuration ou par une autre modification apportée au fichier indépendant de l'API de configuration.
Privilèges requis
Pour modifier une configuration Web, l'application requiert des autorisations d'écriture sur le fichier et des privilèges de création sur le répertoire qui contient le fichier.
Voir aussi
Concepts
Vue d'ensemble de l'API de configuration ASP.NET