Синтаксис преобразования файла Web.config для развертывания проектов веб-приложений с помощью Visual Studio

В этом разделе содержатся справочные сведения о синтаксисе xdt:Transform и атрибутов xdt:Locator, используемые в файлах преобразования 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="http://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.

Преобразования применены во время развертывания, однако можно выполнить предварительный просмотр изменений в Visual Studio. В Обозреватель решений, щелкнув правой кнопкой мыши файл преобразования (например, Web.Release.config) и выберите Предварительный просмотр выполняется преобразование. Visual Studio отображается исходный файл web.config, а преобразованное файл web.config параллельные.

Синтаксис атрибута Locator

В каждом из следующих разделов рассматривается синтаксис для одного атрибута Locator.

Dd465326.collapse_all(ru-ru,VS.110).gifАтрибут Condition

Задает выражение XPath, которое присоединяется к выражению XPath текущего элемента. Выделяются элементы, соответствующие суммарному значению XPath.

Dd465326.collapse_all(ru-ru,VS.110).gifСинтаксис

Locator="Condition(XPath expression)"

Dd465326.collapse_all(ru-ru,VS.110).gifПример

В следующем примере показано, как выделить элементы строк подключения, для которых атрибут 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/add[@name='AWLT' or @providerName='System.Data.SqlClient']

Это выражение является сочетанием неявного условия XPath для текущего элемента (configuration/connectionStrings) с явно задаваемым выражением.

Dd465326.collapse_all(ru-ru,VS.110).gifАтрибут Match

Выделяет элемент или элементы, имеющие соответствующее значение для указанного атрибута или атрибутов. При указании нескольких имен атрибутов выделяются только элементы, соответствующие всем указанным атрибутам.

Dd465326.collapse_all(ru-ru,VS.110).gifСинтаксис

Locator="Match(comma-delimited list of one or more attribute names)"

Dd465326.collapse_all(ru-ru,VS.110).gifПример

В следующем примере показано, как выделить строку подключения элемента 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>

Dd465326.collapse_all(ru-ru,VS.110).gifАтрибут XPath

Задает абсолютное выражение XPath, применяемое к файлу разработки Web.config. (В отличие от атрибута Condition задаваемое выражение не присоединяется к неявному выражению XPath, соответствующему текущему элементу.)

Dd465326.collapse_all(ru-ru,VS.110).gifСинтаксис

Locator="XPath(XPath expression)"

Dd465326.collapse_all(ru-ru,VS.110).gifПример

В следующем примере показано, как выделить элементы, выделенные в предыдущем примере для ключевого слова 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.

Dd465326.collapse_all(ru-ru,VS.110).gifАтрибут Replace

Заменяет выделенный элемент указанным в файле преобразования элементом. Если выделено более одного элемента, заменяется только первый элемент. Пример использования ключевого слова Replace см. в примерах использования атрибутов Locator.

Dd465326.collapse_all(ru-ru,VS.110).gifСинтаксис

Transform="Replace"

Dd465326.collapse_all(ru-ru,VS.110).gifАтрибут Insert

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

Dd465326.collapse_all(ru-ru,VS.110).gifСинтаксис

Transform="Insert"

Dd465326.collapse_all(ru-ru,VS.110).gifПример

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

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add name="AWLT" connectionString="newstring"
       providerName="newprovider"
       xdt:Transform="Insert" />
  </connectionStrings>
</configuration>

Dd465326.collapse_all(ru-ru,VS.110).gifАтрибут InsertBefore

Вставляет элемент, заданный в XML преобразования, непосредственно перед элементом, выделенным с помощью указанного выражения XPath. Выражение XPath должно быть абсолютным выражением, поскольку оно применяется к файлу разработки Web.config в целом; это выражение присоединяется не только к неявному выражению XPath текущего элемента.

Dd465326.collapse_all(ru-ru,VS.110).gifСинтаксис

Transform="InsertBefore(XPath expression)"

Dd465326.collapse_all(ru-ru,VS.110).gifПример

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

<configuration xmlns:xdt="...">
  <authorization>
    <allow roles="Admins"
      xdt:Transform="InsertBefore(/configuration/system.web/authorization/deny[@users='*'])" />
  </authorization>
</configuration>

Dd465326.collapse_all(ru-ru,VS.110).gifАтрибут InsertAfter

Вставляет элемент, заданный в XML преобразования, непосредственно после элемента, выделенного с помощью указанного выражения XPath. Выражение XPath должно быть абсолютным выражением, поскольку оно применяется к файлу разработки Web.config в целом; это выражение не присоединяется к неявному выражению XPath текущего элемента.

Dd465326.collapse_all(ru-ru,VS.110).gifСинтаксис

Transform="InsertAfter(XPath expression)"

Dd465326.collapse_all(ru-ru,VS.110).gifПример

В следующем примере показано, как выделить элемент allow, который предоставляет доступ администраторам и вставляет после себя элемент deny, запрещающий доступ указанному пользователю.

<configuration xmlns:xdt="...">
  <authorization>
    <deny users="UserName"
      xdt:Transform="InsertAfter
        (/configuration/system.web/authorization/allow[@roles='Admins'])" />
  </authorization>
</configuration>

Dd465326.collapse_all(ru-ru,VS.110).gifУдалить

Удаляет выбранный элемент. При выборе нескольких элементов удаляется первый элемент.

Dd465326.collapse_all(ru-ru,VS.110).gifСинтаксис

Transform="Remove"

Dd465326.collapse_all(ru-ru,VS.110).gifПример

В следующем примере показано, как выделить все элементы add строки подключения в файле разработки Web.config. В развертываемом файле Web.config удаляется только первый элемент строки подключения.

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add xdt:Transform="Remove" />
  </connectionStrings>
</configuration>

Dd465326.collapse_all(ru-ru,VS.110).gifАтрибут RemoveAll

Удаляет выбранный элемент или элементы.

Dd465326.collapse_all(ru-ru,VS.110).gifСинтаксис

Transform="RemoveAll"

Dd465326.collapse_all(ru-ru,VS.110).gifПример

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

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add xdt:Transform="RemoveAll" />
  </connectionStrings>
</configuration>

Dd465326.collapse_all(ru-ru,VS.110).gifАтрибут RemoveAttributes

Удаляет указанные атрибуты из выбранных элементов.

Dd465326.collapse_all(ru-ru,VS.110).gifСинтаксис

Transform="RemoveAttributes(comma-delimited list of one or more attribute names)"

Dd465326.collapse_all(ru-ru,VS.110).gifПример

В следующем примере показано, как выделить все элементы compilation в файле разработки Web.config. (Поскольку в файле конфигурации может существовать только один элемент compilation, атрибут Locator задавать не требуется.) В развертываемом файле Web.config атрибуты debug и batch удаляются из элемента compilation.

<configuration xmlns:xdt="...">
  <compilation 
    xdt:Transform="RemoveAttributes(debug,batch)">
  </compilation>
</configuration>

Dd465326.collapse_all(ru-ru,VS.110).gifАтрибут SetAttributes

Задает атрибутам выбранных элементов указанные значения. Атрибут преобразования Replace заменяет весь элемент, включая все его атрибуты. В отличие от него атрибут SetAttributes позволяет изменить выбранные атрибуты элемента. Если не указать, какие атрибуты для изменения, то все атрибуты, присутствующие в элементе в файле преобразования изменены.

SetAttributes преобразует аффекты все выбранные элементы. Эта функциональности отличается от Replace преобразует атрибут, который влияет только на первый выбранный элемент если несколько элементов выделены.

Dd465326.collapse_all(ru-ru,VS.110).gifСинтаксис

Transform="SetAttributes(comma-delimited list of one or more attribute names)"

Dd465326.collapse_all(ru-ru,VS.110).gifПример

В следующем примере показано, как выделить все элементы 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="http://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 заменяются содержимым из файла преобразования.

См. также

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

Карта содержимого веб-развертывания для Visual Studio b ASP.NET

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

Преобразования файла web.config (учебник на сайте ASP.NET)