Использование классов конфигурации

Обновлен: Ноябрь 2007

Большая часть работы по конфигурации производится при помощи класса Configuration. Данный класс представляет конфигурации компьютеров, клиентских приложений, приложений ASP.NET, веб-каталогов и ресурсов, которые хранятся в веб-каталогах.

В ASP.NET версии 2.0 доступ к экземпляру класса Configuration для получения раздела конфигурации можно получить при помощи методов объекта WebConfigurationManager (в клиентских приложениях на платформе .NET Framework можно использовать аналогичный объект ConfigurationManager). Каждый раздел конфигурации имеет собственный объектный тип, который указан в качестве обработчика раздела в таблице «Информация об элементах» в справочных подразделах раздела Параметры конфигурации ASP.NET. Пример см. в разделе Практическое руководство. Доступ к параметрам конфигурации ASP.NET программными средствами.

В следующих разделах приводятся сведения по использованию классов конфигурации в различных сценариях. Сводные сведения о классах конфигурации см. в разделе Общие сведения о конфигурационном API ASP.NET.

Все приведенные ниже примеры используют нестатические методы Configuration.GetSection и Configuration.GetSectionGroup, вначале создавая экземпляр класса System.Configuration.Configuration. Это позволяет получать сведения о конфигурации из любого приложения. Для получения сведений о конфигурации из приложения, в котором располагается код, лучше использовать статические методы GetSection, которые работают быстрее. Дополнительные сведения см. в разделе «Работа с локальными и удаленными параметрами конфигурации» в разделе Общие сведения о конфигурационном API ASP.NET.

Открытие объекта конфигурации, сопоставленного с глобальными параметрами конфигурации

Для открытия файла конфигурации для глобальной конфигурации приложение вызывает статический метод OpenMachineConfiguration классаWebConfigurationManager. В следующем примере кода метод OpenMachineConfiguration открывает и возвращает объект конфигурации, который соответствует файлу Machine.config платформы .NET Framework 2.0. Другие перегруженные версии этого метода позволяют указывать местоположение, удаленный сервер или сведения о пользователе.

' 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");

Конфигурационный интерфейс API зависит от версии. Соответственно, файл Machine.config для одной версии платформы .NET Framework нельзя будет открыть при помощи методов, используемых в другой версии .NET Framework.

Необходимые привилегии

Для открытия конфигурационного файла компьютера приложению необходимо разрешение на чтение физического файла Machine.config. Для изменения конфигурации компьютера приложению необходимо иметь разрешение на запись в файл и права на создание в каталоге конфигурации платформы .NET Framework.

Открытие объекта конфигурации, сопоставленного с параметрами конфигурации веб-приложения

Для открытия файла конфигурации веб-приложения приложение вызывает статический метод OpenWebConfiguration класса WebConfigurationManager, передавая относительный путь виртуального каталога IIS, используемый при открытии файла.

Значение параметра пути может быть получено из пути метабазы IIS каталога, который содержит требуемую конфигурацию. Например, если путь метабазы IIS — это «W3SVC/1/Root/Temp», то путем будет просто «/Temp», так как узел по умолчанию — это узел 1.

В следующем примере кода метод OpenWebConfiguration открывает и возвращает объект конфигурации, который относится к веб-приложению Temp на веб-узле по умолчанию. Объект конфигурации содержит параметры конфигурации, которые задаются локально в файле Web.config, и все наследуемые параметры из родительских файлов конфигурации вплоть до файла Machine.config. Другие перегруженные версии этого метода позволяют указывать веб-узел, местоположение, удаленный сервер и сведения о пользователе.

' 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");

Объект System.Configuration.Configuration можно открыть даже в том случае, если физический файл Web.config отсутствует. В таком случае возвращаемая конфигурация целиком состоит из параметров, которые наследуются из иерархии файлов конфигурации. Дополнительные сведения см. в разделе Сценарии конфигурации ASP.NET.

Необходимые привилегии

Для открытия файла веб-конфигурации приложению необходимо иметь права на чтение физического файла Web.config и всех его родительских файлов в иерархии.

Открытие объекта конфигурации, сопоставленного с разделом файла конфигурации

Для получения данных конфигурации из раздела приложение вызывает нестатический метод GetSectionGroup класса Configuration, передавая имя раздела. Для разделов, которые содержатся в группах разделов, можно либо использовать выражение XPath, указывающее на раздел (system.web/anonymousIdentification), либо сначала получить объект конфигурации, который сопоставлен с группой раздела. Список имен разделов см. в разделе Параметры конфигурации ASP.NET.

В следующем примере кода метод OpenWebConfiguration открывает и возвращает объект конфигурации, который соответствует веб-приложению Temp на веб-узле по умолчанию, а затем использует этот объект для получения ссылки на группу разделов system.web, которая затем используется для получения ссылки на раздел 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());
            }

Объект System.Configuration.Configuration можно открыть даже в том случае, если физический файл Web.config отсутствует. В таком случае возвращаемая конфигурация целиком состоит из параметров, которые наследуются из иерархии файлов конфигурации. Дополнительные сведения см. в разделе Сценарии конфигурации ASP.NET.

Необходимые привилегии

Для открытия раздела файла веб-конфигурации приложению необходимо иметь права на чтение физического файла Web.config и всех его родительских файлов в иерархии. Приложениям с управляемым кодом требуются разрешения на чтение системных разделов. Приложения с высоким и полным уровнем доверия имеют эти разрешения по умолчанию. Другими словами, по умолчанию приложения со средним и низким уровнем доверия не смогут читать разделы конфигурации.

Открытие объекта конфигурации, сопоставленного с удаленными параметрами конфигурации

Конфигурационный интерфейс API также можно использовать для открытия конфигурации удаленного компьютера. Интерфейс API может открыть файл конфигурации компьютера другого компьютера или файл конфигурации приложения для любого приложения IIS или его дочерних каталогов.

Для открытия файла конфигурации компьютера на другом компьютере приложение вызывает статический метод OpenMachineConfiguration, передавая имя сервера.

Для открытия файла Web.config на другом компьютере приложение вызывает статический метод OpenWebConfiguration, передавая объекту конфигурации относительный путь узла, идентификатор узла и имя сервера. Возвращаемый объект конфигурации содержит параметры конфигурации, которые указываются локально в файле Web.config, и все параметры, унаследованные из родительских файлов конфигурации вплоть до файла Machine.config.

Имена серверов — это действующие сетевые имена компьютеров Windows. Эти имена специально не обрабатываются в ASP.NET, а передаются непосредственно в операционную систему.

В следующем примере кода показан способ открытия конфигурации компьютера, корневой конфигурации на узле по умолчанию и веб-конфигурации в каталоге приложения.

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");

Необходимые привилегии

Для открытия файла конфигурации на удаленном компьютере приложение должно иметь права администратора на удаленном компьютере. Это требование носит более строгий характер, чем требование для локального использования. Для локальных файлов конфигурации приложению требуются только разрешения на чтение файлов конфигурации в иерархии и метабазы IIS (для разрешения путей IIS).

Запустите средство Aspnet_regiis.exe с параметром «-config+» на удаленном компьютере перед началом его конфигурирования. Дополнительные сведения см. в разделе Программа регистрации IIS для ASP.NET (Aspnet_regiis.exe).

Обновление параметров конфигурации

Для обновления открытого объекта конфигурации приложение вызывает метод Save или SaveAs объекта конфигурации. Эти методы записывают любые изменения параметров конфигурации для этого объекта. Если файл конфигурации не существует в указанном месте, то создается новый файл конфигурации.

В следующем примере кода атрибуту debug в разделе compilation присваивается значение 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.");
            }

На данный момент функциональных возможностей для блокирования данных конфигурации во время их обновления не существует. Таким образом, конфигурационный интерфейс API использует модель оптимистической блокировки для изменения конфигурации. В рамках модели оптимистической блокировки два приложения, одновременно открывающие одну и ту же конфигурацию, получают уникальные копии объекта конфигурации. Если одно из приложений пытается изменить конфигурацию, вызвав метод Save или SaveAs, но базовый файл конфигурации уже был изменен с тех пор, как приложение получило объект конфигурации, то метод создаст исключение. Базовый файл мог быть изменен другим приложением, обновлявшим конфигурацию, или же каким-либо другим изменением файла, независимым от конфигурационного интерфейса API.

Необходимые привилегии

Для изменения веб-конфигурации приложению необходимо иметь разрешение на запись в файл и права на создание в каталоге, в котором он находится.

См. также

Основные понятия

Общие сведения о конфигурационном API ASP.NET

Другие ресурсы

Параметры конфигурации ASP.NET