- Настройка приложений с использованием файлов конфигурации Configuring Apps by using Configuration Files
- Формат файлов конфигурации Configuration File Format
- Файлы конфигурации компьютеров Machine Configuration Files
- Файлы конфигурации приложений Application Configuration Files
- Файлы конфигурации безопасности Security Configuration Files
- в этом разделе In This Section
- Файл web.config web.config file
- Расположение файла web.config web.config file location
- Настройка модуля ASP.NET Core с помощью web.config Configuration of ASP.NET Core Module with web.config
- Атрибуты элемента aspNetCore Attributes of the aspNetCore element
- Настройка переменных среды Set environment variables
- Настройка служб IIS с помощью web.config Configuration of IIS with web.config
Настройка приложений с использованием файлов конфигурации Configuring Apps by using Configuration Files
Среда .NET Framework предоставляет разработчикам и администраторам возможность управления и гибкой настройки способа выполнения приложений с помощью файлов конфигурации. The .NET Framework, through configuration files, gives developers and administrators control and flexibility over the way applications run. Файлы конфигурации имеют формат XML, и при необходимости их можно изменять. Configuration files are XML files that can be changed as needed. Администратор может контролировать, к каким из защищенных ресурсов может осуществлять доступ приложение, какие оно будет использовать версии сборок и где расположены удаленные объекты и приложения. An administrator can control which protected resources an application can access, which versions of assemblies an application will use, and where remote applications and objects are located. Разработчики могут задавать параметры в файлах конфигурации, устраняя необходимость в перекомпиляции приложения при каждом изменении той или иной установки. Developers can put settings in configuration files, eliminating the need to recompile an application every time a setting changes. В этом разделе рассказывается, какие параметры могут быть настроены и для чего может потребоваться настройка приложения. This section describes what can be configured and why configuring an application might be useful.
С помощью классов из пространства имен System.Configuration управляемый код может считывать установки из конфигурационных файлов, но не записывать их в эти файлы. Managed code can use the classes in the System.Configuration namespace to read settings from the configuration files, but not to write settings to those files.
В этом разделе описан синтаксис файлов конфигурации и приведены сведения о трех типах таких файлов: конфигурации компьютера, приложения и безопасности. This topic describes the syntax of configuration files and provides information about the three types of configuration files: machine, application, and security.
Формат файлов конфигурации Configuration File Format
Файлы конфигурации состоят из элементов, которые являются логическими структурами данных, задающими сведения о конфигурации. Configuration files contain elements, which are logical data structures that set configuration information. Начало и конец каждого элемента в файле конфигурации отмечены специальными тегами. Within a configuration file, you use tags to mark the beginning and end of an element. Например, элемент состоит из дочерних элементов . For example, the element consists of child elements . Пустой элемент будет записан как или . An empty element would be written as or .
Как и во всех XML-файлах, в файлах конфигурации учитывается регистр. As with all XML files, the syntax in configuration files is case-sensitive.
Параметры конфигурации задаются с помощью предварительно определенных атрибутов (пар имя-значение) в открывающем теге элемента. You specify configuration settings using predefined attributes, which are name/value pairs inside an element’s start tag. В следующем примере заданы два атрибута ( version и href ) элемента , определяющие для среды выполнения расположение сборок (дополнительные сведения см. в разделе Указание расположения сборки). The following example specifies two attributes ( version and href ) for the element, which specifies where the runtime can locate an assembly (for more information, see Specifying an Assembly’s Location).
Файлы конфигурации компьютеров Machine Configuration Files
В файле конфигурации компьютера, Machine.config, задаются параметры, влияющие на работу компьютера в целом. The machine configuration file, Machine.config, contains settings that apply to an entire computer. Этот файл находится в каталоге %путь установки среды выполнения%\Config. This file is located in the %runtime install path%\Config directory. В файле Machine.config задаются параметры конфигурации для привязки сборок компьютера, встроенных каналов удаленного взаимодействия и ASP.NET. Machine.config contains configuration settings for machine-wide assembly binding, built-in remoting channels, and ASP.NET.
Система конфигурации сначала просматривает файл конфигурации компьютера для элемента и других разделов конфигурации, которые может определить разработчик. The configuration system first looks in the machine configuration file for the element and other configuration sections that a developer might define. Затем поиск выполняется в файле конфигурации приложения. It then looks in the application configuration file. Для облегчения управления файлом конфигурации компьютера рекомендуется переместить эти параметры в файл конфигурации приложения. To keep the machine configuration file manageable, it is best to put these settings in the application configuration file. Однако размещение параметров в файле конфигурации компьютера упрощает управление системой. However, putting the settings in the machine configuration file can make your system more maintainable. Например, при наличии компонентов сторонних производителей, используемых сервером и клиентами, рекомендуется разместить параметры этих компонентов в одном файле. For example, if you have a third-party component that both your client and server application uses, it is easier to put the settings for that component in one place. В этом случае следует задавать параметры в файле конфигурации компьютера, чтобы не дублировать параметры в разных файлах. In this case, the machine configuration file is the appropriate place for the settings, so you don’t have the same settings in two different files.
При развертывании приложения с помощью команды XCOPY файл конфигурации компьютера не копируется. Deploying an application using XCOPY will not copy the settings in the machine configuration file.
Дополнительные сведения об использовании файла конфигурации компьютера средой CLR для привязки сборок см. в разделе Обнаружение сборок в среде выполнения. For more information about how the common language runtime uses the machine configuration file for assembly binding, see How the Runtime Locates Assemblies.
Файлы конфигурации приложений Application Configuration Files
В файле конфигурации приложения находятся параметры приложения. An application configuration file contains settings that are specific to an app. В этом файле содержатся параметры конфигурации, считываемые средой CLR (например, политика привязки сборок, удаленные объекты и т. д.) и приложением. This file includes configuration settings that the common language runtime reads (such as assembly binding policy, remoting objects, and so on), and settings that the app can read.
Имя и расположение файла конфигурации приложения зависят от места размещения приложения, которым может быть одно из указанных ниже. The name and location of the application configuration file depend on the app’s host, which can be one of the following:
Приложение, размещенное в исполняемом файле. Executable–hosted app.
Такие приложения имеют два файла конфигурации: исходный файл конфигурации, который изменяется разработчиком во время разработки, и выходной файл, распространяемый с приложением. These apps have two configuration files: a source configuration file, which is modified by the developer during development, and an output file that is distributed with the app.
При разработке в Visual Studio разместите исходный файл конфигурации приложения в каталоге проекта и установите для его свойства Копировать в выходной каталог значение Всегда копировать или Копировать, если новее. When you develop in Visual Studio, place the source configuration file for your app in the project directory and set its Copy To Output Directory property to Copy always or Copy if newer. Имя файла конфигурации — это имя приложения с расширением CONFIG. The name of the configuration file is the name of the app with a .config extension. Например, исходный файл конфигурации приложения myApp.exe должен называться myApp.exe.config. For example, an app called myApp.exe should have a source configuration file called myApp.exe.config.
Visual Studio автоматически копирует исходный файл конфигурации в каталог, где находится скомпилированная сборка, чтобы создать выходной файл конфигурации, развертываемый вместе с приложением. Visual Studio automatically copies the source configuration file to the directory where the compiled assembly is placed to create the output configuration file, which is deployed with the app. В некоторых случаях Visual Studio может изменить выходной файл конфигурации; дополнительные сведения см. в разделе Перенаправление версий сборки на уровне приложения статьи Перенаправление версий сборки. In some cases, Visual Studio may modify the output configuration file; for more information, see the Redirecting assembly versions at the app level section of the Redirecting Assembly Versions article.
Приложение, размещенное в ASP.NET. ASP.NET-hosted app.
Дополнительные сведения о файлах конфигурации ASP.NET см. в разделе Параметры конфигурации ASP.NET. For more information about ASP.NET configuration files, see ASP.NET Configuration Settings.
Приложение, размещенное в Internet Explorer. Internet Explorer-hosted app.
Если для приложения, размещенного в Internet Explorer, определен файл конфигурации, его расположение задается в теге
В этом теге location — это URL-адрес файла конфигурации. In this tag, location is a URL to the configuration file. Таким образом задается базовая папка приложения. This sets the app base. Файл конфигурации должен находиться на том же веб-сайте, что и приложение. The configuration file must be located on the same website as the app.
Файлы конфигурации безопасности Security Configuration Files
В файлах конфигурации безопасности содержатся сведения об иерархии групп кода и наборах разрешений, связанных с уровнем политики. Security configuration files contain information about the code group hierarchy and permission sets associated with a policy level. Для изменения политики безопасности настоятельно рекомендуется использовать средство политики безопасности доступа кода (Caspol.exe), что гарантирует целостность файлов конфигурации безопасности. We strongly recommend that you use the Code Access Security Policy tool (Caspol.exe) to modify security policy to ensure that policy changes do not corrupt the security configuration files.
Начиная с .NET Framework 4, файлы конфигурации безопасности существуют только в том случае, если изменилась политика безопасности. Starting with the .NET Framework 4, the security configuration files are present only if security policy has been changed.
Ниже приведено расположение файлов конфигурации безопасности. The security configuration files are in the following locations:
Файл конфигурации политики предприятия: %путь-установки-среды-выполнения%\Config\Enterprisesec.config Enterprise policy configuration file: %runtime-install-path%\Config\Enterprisesec.config
Файл конфигурации политики компьютера: %путь-установки-среды-выполнения%\Config\Security.config Machine policy configuration file: %runtime-install-path%\Config\Security.config
Файл конфигурации политики пользователя: %USERPROFILE%\Application data\Microsoft\CLR security config\vxx.xx\Security.config User policy configuration file: %USERPROFILE%\Application data\Microsoft\CLR security config\vxx.xx\Security.config
в этом разделе In This Section
Практическое руководство. Поиск сборок с помощью DEVPATH How to: Locate Assemblies by Using DEVPATH
Описание процесса настройки среды выполнения для использования переменной среды DEVPATH при поиске сборок. Describes how to direct the runtime to use the DEVPATH environment variable when searching for assemblies.
Перенаправление версий сборки Redirecting Assembly Versions
Инструкции по указанию местоположения и версии сборки, которая должна использоваться приложением. Describes how to specify the location of an assembly and which version of an assembly to use.
Указание расположения сборки Specifying an Assembly’s Location
Сведения о том, как указать среде выполнения, где она должна осуществлять поиск сборки. Describes how to specify where the runtime should search for an assembly.
Настройка криптографических классов Configuring Cryptography Classes
Описание процесса сопоставления имени алгоритма криптографическому классу и идентификатора объекта в криптографическому алгоритму. Describes how to map an algorithm name to a cryptography class and an object identifier to a cryptography algorithm.
Практическое руководство. Создание политики издателя How to: Create a Publisher Policy
Сведения о том, куда и каким образом нужно добавить файл политики издателя, чтобы задать перенаправление сборки и параметры базового каталога кода. Describes when and how you should add a publisher policy file to specify assembly redirection and code base settings.
Схема файла конфигурации Configuration File Schema
Описывается иерархия схемы для запуска, среды выполнения, сети и других типов параметров конфигурации. Describes the schema hierarchy for startup, runtime, network, and other types of configuration settings.
Файл web.config web.config file
web.config — это файл, который считывается службами IIS и модулем ASP.NET Core для настройки приложения, размещенного в службах IIS. The web.config is a file that is read by IIS and the ASP.NET Core Module to configure an app hosted with IIS.
Расположение файла web.config web.config file location
Для корректной настройки модуля ASP.NET Core необходимо наличие файла web.config в корневой папке содержимого развертываемого приложения (как правило, это основной путь приложения). In order to set up the ASP.NET Core Module correctly, the web.config file must be present at the content root path (typically the app base path) of the deployed app. Это расположение соответствует физическому пути веб-сайта, указанному в службах IIS. This is the same location as the website physical path provided to IIS. Файл web.config требуется в корне приложения, чтобы разрешить публикацию нескольких приложений с помощью веб-развертывания. The web.config file is required at the root of the app to enable the publishing of multiple apps using Web Deploy.
По физическому пути приложения находятся файлы с конфиденциальной информацией, например,
Файл web.config должен постоянно находиться в развертывании, у этого файла должно быть правильное имя, и файл должен быть в состоянии настроить нормальный запуск сайта. Никогда не удаляйте файл web.config из развертывания в рабочей среде. The web.config file must be present in the deployment at all times, correctly named, and able to configure the site for normal start up. Never remove the web.config file from a production deployment.
Если в проекте нет файла web.config , он создается с соответствующими аргументами processPath и arguments для настройки модуля ASP.NET Core и переносится в опубликованные выходные данные. If a web.config file isn’t present in the project, the file is created with the correct processPath and arguments to configure the ASP.NET Core Module and moved to published output.
Если в проекте есть файл web.config , он преобразуется с соответствующими аргументами processPath и arguments для настройки модуля ASP.NET Core и переносится в опубликованные выходные данные. If a web.config file is present in the project, the file is transformed with the correct processPath and arguments to configure the ASP.NET Core Module and moved to published output. Преобразование не изменяет параметры конфигурации служб IIS, включенные в файл. The transformation doesn’t modify IIS configuration settings in the file.
Файл web.config может содержать дополнительные параметры конфигурации IIS, управляющие активными модулями IIS. The web.config file may provide additional IIS configuration settings that control active IIS modules. Сведения о модулях IIS, которые могут обрабатывать запросы к приложениям ASP.NET Core, см. в статье Модули IIS. For information on IIS modules that are capable of processing requests with ASP.NET Core apps, see the IIS modules topic.
Создание, преобразование и публикация файла web.config обрабатываются целевым объектом MSBuild ( _TransformWebConfig ) при публикации проекта. Creating, transforming, and publishing the web.config file is handled by an MSBuild target ( _TransformWebConfig ) when the project is published. Этот целевой объект присутствует в целевых веб-пакетах SDK ( Microsoft.NET.Sdk.Web ). This target is present in the Web SDK targets ( Microsoft.NET.Sdk.Web ). Пакет SDK задается в начале файла проекта: The SDK is set at the top of the project file:
Чтобы веб-пакет SDK не преобразовывал файл web.config , используйте свойство в файле проекта: To prevent the Web SDK from transforming the web.config file, use the property in the project file:
Если пакет SDK не преобразует файл, аргументы processPath и arguments нужно задать вручную. When disabling the Web SDK from transforming the file, the processPath and arguments should be manually set by the developer. Для получения дополнительной информации см. Модуль ASP.NET Core. For more information, see Модуль ASP.NET Core.
Настройка модуля ASP.NET Core с помощью web.config Configuration of ASP.NET Core Module with web.config
Модуль ASP.NET Core настроен с помощью раздела aspNetCore узла system.webServer файла web.config на веб-сайте. The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site’s web.config file.
Следующий файл web.config публикуется для зависимого от платформы развертывания и настраивает модуль ASP.NET Core для обработки запросов к веб-сайту. The following web.config file is published for a framework-dependent deployment and configures the ASP.NET Core Module to handle site requests:
Следующий файл web.config опубликован для автономного развертывания. The following web.config is published for a self-contained deployment:
Значение false свойства InheritInChildApplications указывает, что параметры, заданные в элементе , не наследуются приложениями, которые находятся во вложенном каталоге приложения. The InheritInChildApplications property is set to false to indicate that the settings specified within the element aren’t inherited by apps that reside in a subdirectory of the app.
Когда приложение развернуто в службе приложений Azure, путь stdoutLogFile задан как \\?\%home%\LogFiles\stdout . When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout . Путь сохраняет журналы stdout в папке LogFiles , расположение которой автоматически создается службой. The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.
Сведения о конфигурации дочерних приложений IIS см. здесь: Размещение ASP.NET Core в Windows со службами IIS. For information on IIS sub-application configuration, see Размещение ASP.NET Core в Windows со службами IIS.
Атрибуты элемента aspNetCore Attributes of the aspNetCore element
| attribute Attribute | Описание Description | Значение по умолчанию Default |
|---|---|---|
| arguments | false | |
| forwardWindowsAuthToken | InProcess inprocess | |
| processesPerApplication | По умолчанию: 1 Default: 1 Минимум: 1 Min: 1 Максимум: 100 † Max: 100 † | |
| processPath | По умолчанию: 10 Default: 10 Минимум: 0 Min: 0 Максимум: 100 Max: 100 | |
| requestTimeout | По умолчанию: 00:02:00 Default: 00:02:00 Минимум: 00:00:00 Min: 00:00:00 Максимум: 360:00:00 Max: 360:00:00 | |
| shutdownTimeLimit | По умолчанию: 10 Default: 10 Минимум: 0 Min: 0 Максимум: 600 Max: 600 | |
| startupTimeLimit | По умолчанию: 120 Default: 120 Минимум: 0 Min: 0 Максимум: 3600 Max: 3600 | |
| stdoutLogEnabled | aspnetcore-stdout |
Настройка переменных среды Set environment variables
Переменные среды для процесса можно указать в атрибуте processPath . Environment variables can be specified for the process in the processPath attribute. Укажите переменную среды с дочерним элементом элемента коллекции . Specify an environment variable with the child element of an collection element. Переменные среды, установленные в этом разделе, имеют приоритет над переменными системной среды. Environment variables set in this section take precedence over system environment variables.
В приведенном ниже примере устанавливаются две переменные среды в web.config . The following example sets two environment variables in web.config . ASPNETCORE_ENVIRONMENT настраивает среду приложения для Development . ASPNETCORE_ENVIRONMENT configures the app’s environment to Development . Разработчик может временно задать это значение в файле web.config , чтобы принудительно загрузить Страницу исключений для разработчиков при отладке исключения приложения. A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. CONFIG_DIR — пример пользовательской переменной среды, где разработчик написал код, который считывает значение при запуске, чтобы сформировать путь для загрузки файла конфигурации приложения. CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app’s configuration file.
Вместо установки среды напрямую в web.config можно включить свойство в профиль публикации ( .pubxml ) или файл проекта. An alternative to setting the environment directly in web.config is to include the property in the publish profile ( .pubxml ) or project file. При этом подходе во время публикации проекта среда задается в файле web.config : This approach sets the environment in web.config when the project is published:
Установите только переменную среды ASPNETCORE_ENVIRONMENT для Development на серверах промежуточных процессов и тестирования, которые недоступны для ненадежных сетей, таких как Интернет. Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren’t accessible to untrusted networks, such as the Internet.
Настройка служб IIS с помощью web.config Configuration of IIS with web.config
Конфигурация IIS зависит от раздела web.config для сценариев IIS, предназначенных для работы приложений ASP.NET Core с помощью модуля ASP.NET Core. IIS configuration is influenced by the section of web.config for IIS scenarios that are functional for ASP.NET Core apps with the ASP.NET Core Module. Например, конфигурация IIS работает для динамического сжатия. For example, IIS configuration is functional for dynamic compression. Если в службах IIS на уровне сервера настроено динамическое сжатие, элемент в файле web.config приложения может отключить это сжатие для приложения ASP.NET Core. If IIS is configured at the server level to use dynamic compression, the element in the app’s web.config file can disable it for an ASP.NET Core app.
Дополнительные сведения см. в следующих разделах: For more information, see the following topics:
