Синтаксис преобразования файла Web.config для развертывания проектов веб-приложений
В файлах Web.config обычно содержатся параметры, которые должны иметь различные значения в зависимости от среды, в которой выполняется приложение. Например, может потребоваться изменить строку подключения базы данных или отключить отладку при развертывании файла Web.config. Для проектов веб-приложений в ASP.NET имеются инструменты, автоматизирующие процесс изменения (преобразования) файлов Web.config при их развертывании. Для каждой среды, в которую требуется выполнить развертывание, необходимо создать файл преобразования, где будут указаны только отличия исходного файла Web.config от развертываемого файла Web.config для этой среды.
Файл преобразования представляет собой XML-файл, где указаны изменения, которые требуется внести в файл Web.config при развертывании. Действия преобразования указываются атрибутами XML, определенными в пространстве имен XML-Document-Transform, сопоставляемом префиксу xdt. Пространство имен XML-Document-Transform определяет два атрибута: атрибут Locator и атрибут Transform. Атрибут Locator указывает элемент или набор элементов файла Web.config, которые требуется изменить. Атрибут Transform указывает, какие действия требуется произвести над элементами, найденными атрибутом Locator.
В следующем примере показано содержимое файла преобразования, который изменяет строку подключения и заменяет элемент customErrors.
<?xml version="1.0"?>
<configuration xmlns:xdt="https://schemas.microsoft.com/XML-Document-Transform">
<connectionStrings>
<add name="MyDB"
connectionString="value for the deployed Web.config file"
xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>
</connectionStrings>
<system.web>
<customErrors defaultRedirect="GenericError.htm"
mode="RemoteOnly" xdt:Transform="Replace">
<error statusCode="500" redirect="InternalError.htm"/>
</customErrors>
</system.web>
</configuration>
Корневой элемент файла преобразования должен указывать пространство имен XML-Document-Transform в открывающем теге, как это показано в предыдущем примере. Сами элементы Locator и Transform не воспроизводятся в развертываемом файле Web.config.
В следующих разделах содержится справочная информация о синтаксисе, который следует использовать в файлах преобразования.
Синтаксис атрибута Locator
В каждом из следующих разделов рассматривается синтаксис для одного атрибута Locator.
Атрибут Condition
Задает выражение XPath, которое присоединяется к выражению XPath текущего элемента. Выделяются элементы, соответствующие суммарному значению XPath.
Синтаксис
Locator="Condition(XPath expression)"
Пример
В следующем примере показано, как выделить элементы строк подключения, для которых атрибут name имеет значение oldname или атрибут providerName имеет значение oldprovider. В развертываемом файле Web.config выделенные элементы заменяются элементом, указанном в файле преобразования.
<configuration xmlns:xdt="...">
<connectionStrings>
<add name="AWLT" connectionString="newstring"
providerName="newprovider"
xdt:Transform="Replace"
xdt:Locator="Condition(@name='oldname'
or @providerName='oldprovider')" />
</connectionStrings>
</configuration>
Фактическое выражение XPath, которое применяется к файлу разработки Web.config file в результате использования указанного выражения Condition, выглядит следующим образом:
configuration/connectionStrings[@name='AWLT' or @providerName='System.Data.SqlClient']
Это выражение является сочетанием неявного условия XPath для текущего элемента (configuration/connectionStrings) с явно задаваемым выражением.
Атрибут Match
Выделяет элемент или элементы, имеющие соответствующее значение для указанного атрибута или атрибутов. При указании нескольких имен атрибутов выделяются только элементы, соответствующие всем указанным атрибутам.
Синтаксис
Locator="Match(comma-delimited list of one or more attribute names)"
Пример
В следующем примере показано, как выделить строку подключения элемента add, содержащего выражение AWLT в атрибуте name, в файле разработки Web.config. В развертываемом файле Web.config выделенный элемент заменяется элементом add, указанным в файле преобразования.
<configuration xmlns:xdt="...">
<connectionStrings>
<add name="AWLT" connectionString="newstring"
providerName="newprovider"
xdt:Transform="Replace"
xdt:Locator="Match(name)" />
</connectionStrings>
</configuration>
Атрибут XPath
Задает абсолютное выражение XPath, применяемое к файлу разработки Web.config. (В отличие от атрибута Condition задаваемое выражение не присоединяется к неявному выражению XPath, соответствующему текущему элементу.)
Синтаксис
Locator="XPath(XPath expression)"
Пример
В следующем примере показано, как выделить элементы, выделенные в предыдущем примере для ключевого слова Condition.
<configuration xmlns:xdt="...">
<connectionStrings>
<add name="AWLT" connectionString="newstring"
providerName="newprovider"
xdt:Transform="Replace"
xdt:Locator="XPath(configuration/connectionStrings[@name='AWLT'
or @providerName='System.Data.SqlClient'])" />
</connectionStrings>
</configuration>
Синтаксис атрибута Transform
В каждом из следующих разделов рассматривается синтаксис для одного атрибута Transform.
Атрибут Replace
Заменяет выделенный элемент указанным в файле преобразования элементом. Если выделено более одного элемента, заменяется только первый элемент. Пример использования ключевого слова Replace см. в примерах использования атрибутов Locator.
Синтаксис
Transform="Replace"
Атрибут Insert
Добавляет элемент, указанный в файле преобразования, как элемент того же уровня, что и выбранный элемент или элементы. Новый элемент добавляется в конец любой коллекции.
Синтаксис
Transform="Insert"
Пример
В следующем примере показано, как выделить все строки подключения в файле разработки Web.config. В развертываемом файле Web.config указанная строка подключения добавляется в конец коллекции.
<configuration xmlns:xdt="...">
<connectionStrings>
<add name="AWLT" connectionString="newstring"
providerName="newprovider"
xdt:Transform="Insert" />
</connectionStrings>
</configuration>
Атрибут InsertBefore
Вставляет элемент, заданный в XML преобразования, непосредственно перед элементом, выделенным с помощью указанного выражения XPath. Выражение XPath должно быть абсолютным выражением, поскольку оно применяется к файлу разработки Web.config в целом; это выражение присоединяется не только к неявному выражению XPath текущего элемента.
Синтаксис
Transform="InsertBefore(XPath expression)"
Пример
В следующем примере показано, как выделить элемент deny, который запрещает доступ всем пользователям, а затем вставляет перед собой элемент allow, предоставляющий доступ администраторам.
<configuration xmlns:xdt="...">
<authorization>
<allow roles="Admins"
xdt:Transform="InsertBefore(/configuration/system.web/authorization/deny[@users='*'])" />
</authorization>
</configuration>
Атрибут InsertAfter
Вставляет элемент, заданный в XML преобразования, непосредственно после элемента, выделенного с помощью указанного выражения XPath. Выражение XPath должно быть абсолютным выражением, поскольку оно применяется к файлу разработки Web.config в целом; это выражение не присоединяется к неявному выражению XPath текущего элемента.
Синтаксис
Transform="InsertAfter(XPath expression)"
Пример
В следующем примере показано, как выделить элемент allow, который предоставляет доступ администраторам и вставляет после себя элемент deny, запрещающий доступ указанному пользователю.
<configuration xmlns:xdt="...">
<authorization>
<deny users="UserName"
xdt:Transform="InsertAfter
(/configuration/system.web/authorization/allow[@roles='Admins'])" />
</authorization>
</configuration>
Удалить
Удаляет выбранный элемент. При выборе нескольких элементов удаляется первый элемент.
Синтаксис
Transform="Remove"
Пример
В следующем примере показано, как выделить все элементы add строки подключения в файле разработки Web.config. В развертываемом файле Web.config удаляется только первый элемент строки подключения.
<configuration xmlns:xdt="...">
<connectionStrings>
<add xdt:Transform="Remove" />
</connectionStrings>
</configuration>
Атрибут RemoveAll
Удаляет выбранный элемент или элементы.
Синтаксис
Transform="RemoveAll"
Пример
В следующем примере показано, как выделить все строки подключения в файле разработки Web.config. В развертываемом файле Web.config удаляются все элементы.
<configuration xmlns:xdt="...">
<connectionStrings>
<add xdt:Transform="RemoveAll" />
</connectionStrings>
</configuration>
Атрибут RemoveAttributes
Удаляет указанные атрибуты из выбранных элементов.
Синтаксис
Transform="RemoveAttributes(comma-delimited list of one or more attribute names)"
Пример
В следующем примере показано, как выделить все элементы compilation в файле разработки Web.config. (Поскольку в файле конфигурации может существовать только один элемент compilation, атрибут Locator задавать не требуется.) В развертываемом файле Web.config атрибуты debug и batch удаляются из элемента compilation.
<configuration xmlns:xdt="...">
<compilation
xdt:Transform="RemoveAttributes(debug,batch)">
</compilation>
</configuration>
Атрибут SetAttributes
Задает атрибутам выбранных элементов указанные значения. Атрибут преобразования Replace заменяет весь элемент, включая все его атрибуты. В отличие от него атрибут SetAttributes позволяет изменить выбранные атрибуты элемента.
Синтаксис
Transform="SetAttributes(comma-delimited list of one or more attribute names)"
Пример
В следующем примере показано, как выделить все элементы compilation в файле разработки Web.config. (Поскольку в файле конфигурации может существовать только один элемент compilation, атрибут Locator задавать не требуется.) В развертываемом файле Web.config file для элемента compilation атрибуту batch присваивается значение false.
<configuration xmlns:xdt="...">
<compilation
batch="false"
xdt:Transform="SetAttributes(batch)">
</compilation>
</configuration>
Пропуск атрибутов для атрибута Locator
Атрибуты Locator являются необязательными. Если атрибут Locator не задан, элемент, который требуется изменить, задается неявно посредством элемента, для которого задан атрибут Transform. В следующем примере показано, что заменяется весь элемент system.web, поскольку никаким атрибутом Locator не предписывается других действий.
<?xml version="1.0"?>
<configuration xmlns:xdt="https://schemas.microsoft.com/XML-Document-Transform">
<system.web xdt:Transform="Replace">
<customErrors defaultRedirect="GenericError.htm"
mode="RemoteOnly">
<error statusCode="500" redirect="InternalError.htm"/>
</customErrors>
</system.web>
</configuration>
Использование атрибутов Transform и Locator для отдельных элементов
Атрибут Transform не требуется задавать в том же элементе, в котором задан атрибут Locator. Элемент Locator можно задать в родительском элементе, чтобы выбрать элементы, с дочерними элементами которых требуется работать. Затем можно задать атрибут Transform в дочернем элементе, чтобы применить изменения для дочерних элементов.
В следующем примере показано, как использовать атрибут Locator, чтобы выбрать элементы location для указанного пути. Однако преобразование выполняется только для элементов, являющихся дочерними элементами выбранного элемента location.
<configuration xmlns:xdt="...">
<location path="C:\MySite\Admin" xdt:Locator="Match(path)">
<system.web>
<pages viewStateEncryptionMode="Always"
xdt:Transform="SetAttributes(viewStateEncryptionMode)" />
</system.web>
</location>
</configuration>
Если атрибут Locator задан, а атрибут Transform не задан в том же или дочернем элементе, изменения не производятся.
Примечание
Заданный в родительском элементе атрибут Transform может влиять на дочерние элементы, даже если для них атрибут Transform не задан.Например, если атрибут xdt:Transform="Replace" задан в элементе system.web, все дочерние элементы этого элемента system.web заменяются содержимым из файла преобразования.
См. также
Основные понятия
Общие сведения о развертывании проектов веб-приложений ASP.NET
Журнал изменений
Дата |
Журнал |
Причина |
|---|---|---|
|
Май 2011 |
Исправлено пояснение о работе преобразования Replace. |
Обратная связь от клиента. |