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

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

• Visual Studio 2012

• Visual Studio Express 2012 для Web

• с Visual Studio 2010Устройств Visual Studio публиковать обновление

• с Visual Web Developer 2010, экспресс-выпускУстройств Visual Studio публиковать обновление

Файл преобразования представляет собой 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.

Преобразования применены во время развертывания, однако можно выполнить предварительный просмотр изменений в Visual Studio. В Обозреватель решений, щелкнув правой кнопкой мыши файл преобразования (например, Web.Release.config) и выберите Предварительный просмотр выполняется преобразование. Visual Studio отображается исходный файл web.config, а преобразованное файл 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/add[@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)"

Пример

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

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

Синтаксис

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 заменяются содержимым из файла преобразования.

См. также

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

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

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

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