Syntax der Web.config-Transformation für die Bereitstellung von Webanwendungsprojekten mit Visual Studio

Dieses Thema enthält Referenzinformationen zur Syntax von xdt:Transform und xdt:Locator-Attribute, die Sie in Web.config verwenden, Transformationsdateien in den folgenden Produkten:

• Visual Studio 2012

• Visual Studio Express 2012 for Web

• Visual Studio 2010 mit Visual Studio-Internet veröffentlichen Update

• Visual Web Developer 2010 Express mit Visual Studio-Internet veröffentlichen Update

Eine Transformationsdatei ist eine XML-Datei, die angibt, wie die Web.config-Datei bei der Bereitstellung geändert werden soll. Transformationsaktionen werden mit XML-Attributen angegeben, die im XML-Document-Transform-Namespace definiert werden. Dieser Namespace ist dem xdt-Präfix zugeordnet ist. Der XML-Document-Transform-Namespace definiert zwei Attribute: Locator und Transform. Das Locator-Attribut gibt das Web.config-Element oder den Satz von Elementen an, das bzw. den Sie ändern möchten. Das Transform-Attribut gibt an, welche Änderungen an den vom Locator-Attribut gefundenen Elementen vorgenommen werden sollen.

Das folgende Beispiel zeigt den Inhalt einer Transformationsdatei, durch die eine Verbindungszeichenfolge geändert und das customErrors-Element ersetzt wird:

<?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>

Das Stammelement einer Transformationsdatei muss wie im vorangehenden Beispiel gezeigt den XML-Document-Transform-Namespace im Starttag angeben. Die Locator- und Transform-Elemente selbst werden nicht in der bereitgestellten Web.config-Datei reproduziert.

Transformationen werden während der Bereitstellung angewendet, jedoch können Sie eine Vorschau der Änderungen in Visual Studio anzeigen. In Projektmappen-Explorer klicken Sie auf die Transformationsdatei (beispielsweise, Web.Release.config) mit der rechten Maustaste und wählen Sie Transformationsvorschau aus. Visual Studio wird die Datei Web.config der Vorlage und die Transformation Web.config-Datei nebeneinander an.

Syntax des Locator-Attributs

In den folgenden Abschnitten wird die Syntax der einzelnen Locator-Attribute erläutert.

Bedingung

Gibt einen XPath-Ausdruck an, der an den XPath-Ausdruck des aktuellen Elements angefügt wird. Elemente, die dem kombinierten XPath-Ausdruck entsprechen, werden ausgewählt.

Syntax

Locator="Condition(XPath expression)"

Beispiel

Im folgenden Beispiel wird gezeigt, wie Verbindungszeichenfolgenelemente ausgewählt werden, deren name-Attributwert oldname oder providerName-Attributwert oldprovider lautet. In der bereitgestellten Web.config-Datei werden die ausgewählten Elemente durch das in der Transformationsdatei angegebene Element ersetzt.

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add name="AWLT" connectionString="newstring"
       providerName="newprovider"
       xdt:Transform="Replace" 
       xdt:Locator="Condition(@name='oldname'
         or @providerName='oldprovider')" />
  </connectionStrings>
</configuration>

Der effektive XPath-Ausdruck, der aufgrund des angegebenen Condition-Ausdrucks auf die Web.config-Entwicklungsdatei angewendet wird, lautet wie folgt:

configuration/connectionStrings/add[@name='AWLT' or @providerName='System.Data.SqlClient']

Dieser Ausdruck entsteht durch die Kombination der impliziten XPath-Bedingung für das aktuelle Element (configuration/connectionStrings) mit dem explizit angegebenen Ausdruck.

Match

Wählt die Elemente aus, die über einen entsprechenden Wert für die angegebenen Attribute verfügen. Wenn mehrere Attributnamen angegeben werden, werden nur mit allen angegebenen Attributen übereinstimmende Elemente ausgewählt.

Syntax

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

Beispiel

Im folgenden Beispiel wird gezeigt, wie das add-Verbindungszeichenfolgenelement ausgewählt wird, für das in der Web.config-Entwicklungsdatei AWLT im name-Attribut angegeben ist. In der bereitgestellten Web.config-Datei wird das ausgewählte Element durch das in der Transformationsdatei angegebene add-Element ersetzt.

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add name="AWLT" connectionString="newstring"
       providerName="newprovider"
       xdt:Transform="Replace" 
       xdt:Locator="Match(name)" />
  </connectionStrings>
</configuration>

XPath

Gibt einen absoluten XPath-Ausdruck an, der auf die Web.config-Entwicklungsdatei angewendet wird. (Anders als Condition wird der von Ihnen angegebene Ausdruck nicht an den impliziten XPath-Ausdruck angefügt, der dem aktuellen Element entspricht.)

Syntax

Locator="XPath(XPath expression)"

Beispiel

Im folgenden Beispiel wird gezeigt, wie die gleichen Elemente ausgewählt werden wie im vorangehenden Beispiel für das Condition-Schlüsselwort.

<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>

Syntax des Transform-Attributs

In den folgenden Abschnitten wird die Syntax der einzelnen Transform-Attribute erläutert.

Ersetzen

Ersetzt das ausgewählte Element durch das in der Transformationsdatei angegebene Element. Wenn mehrere Elemente ausgewählt sind, wird nur das erste ausgewählte Element ersetzt. Ein Beispiel zur Verwendung des Replace-Schlüsselworts finden Sie in den Beispielen für die Locator-Attribute.

Syntax

Transform="Replace"

Insert

Fügt das Element hinzu, das in der Transformationsdatei als gleichgeordnetes Element für die ausgewählten Elemente definiert ist. Das neue Element wird am Ende der Auflistungen hinzugefügt.

Syntax

Transform="Insert"

Beispiel

Im folgenden Beispiel wird gezeigt, wie alle Verbindungszeichenfolgen in der Web.config-Entwicklungsdatei ausgewählt werden. In der bereitgestellten Web.config-Datei wird die angegebene Verbindungszeichenfolge am Ende der Auflistung hinzugefügt.

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

InsertBefore

Fügt das in der Transformations-XML definierte Element direkt vor dem Element ein, das vom angegebenen XPath-Ausdruck ausgewählt wird. Der XPath-Ausdruck muss ein absoluter Ausdruck sein, da er als Ganzes auf die Web.config-Entwicklungsdatei angewendet wird. Er wird nicht nur an den impliziten XPath-Ausdruck des aktuellen Elements angefügt.

Syntax

Transform="InsertBefore(XPath expression)"

Beispiel

Das folgende Beispiel zeigt, wie das deny-Element auswählt, das allen Benutzern verweigert. Es fügt dann ein allow-Element vor dem deny-Element, um Zugriff auf Administratoren zu gewähren.

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

InsertAfter

Fügt das in der Transformations-XML definierte Element direkt nach dem Element ein, das vom angegebenen XPath-Ausdruck ausgewählt wird. Der XPath-Ausdruck muss ein absoluter Ausdruck sein, da er als Ganzes auf die Web.config-Entwicklungsdatei angewendet wird. Er wird nicht an den impliziten XPath-Ausdruck des aktuellen Elements angefügt.

Syntax

Transform="InsertAfter(XPath expression)"

Beispiel

Im folgenden Beispiel wird gezeigt, wie das allow-Element ausgewählt wird, das Administratoren den Zugriff gewährt und danach ein deny-Element einfügt, das einem bestimmten Benutzer den Zugriff verweigert.

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

Entfernen

Entfernt das ausgewählten Element. Bei Auswahl mehrerer Elemente wird das erste Element entfernt.

Syntax

Transform="Remove"

Beispiel

Im folgenden Beispiel wird gezeigt, wie alle add-Verbindungszeichenfolgenelemente in der Web.config-Entwicklungsdatei ausgewählt werden. In der bereitgestellten Web.config-Datei wird nur das erste Verbindungszeichenfolgenelement entfernt.

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

RemoveAll

Entfernt die ausgewählten Elemente.

Syntax

Transform="RemoveAll"

Beispiel

Im folgenden Beispiel wird gezeigt, wie alle Verbindungszeichenfolgen in der Web.config-Entwicklungsdatei ausgewählt werden. In der bereitgestellten Web.config-Datei werden alle Elemente entfernt.

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

RemoveAttributes

Entfernt angegebene Attribute aus den ausgewählten Elementen.

Syntax

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

Beispiel

Im folgenden Beispiel wird gezeigt, wie alle compilation-Elemente in der Web.config-Entwicklungsdatei ausgewählt werden. (Da die Konfigurationsdatei nur ein compilation-Element enthalten kann, müssen Sie kein Locator-Attribut angeben.) In der bereitgestellten Web.config-Datei werden die debug- und batch-Attribute aus dem compilation-Element entfernt.

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

SetAttributes

Legt Attribute für ausgewählte Elemente auf die angegebenen Werte fest. Das Replace-Transformationsattribut ersetzt ein ganzes Element einschließlich aller Attribute. Das SetAttributes-Attribut ermöglicht es Ihnen dagegen, das Element unverändert zu lassen und nur ausgewählte Attribute zu ändern. Wenn Sie nicht angeben, das zugeordnet, um zu ändern, werden alle Attribute, die im Element in der Transformationsdatei vorhanden sind, geändert.

SetAttributes transformieren beeinflusst alle ausgewählten Elemente. Dieses Verhalten ist zu Replace transformiert Attribut abweichen, das nur das erste ausgewählte Element auswirkt, wenn mehrere Elemente ausgewählt werden.

Syntax

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

Beispiel

Im folgenden Beispiel wird gezeigt, wie alle compilation-Elemente in der Web.config-Entwicklungsdatei ausgewählt werden. (Da die Konfigurationsdatei nur ein compilation-Element enthalten kann, müssen Sie kein Locator-Attribut angeben.) In der bereitgestellten Web.config-Datei wird das batch-Attribut des compilation-Elements auf false festgelegt.

<configuration xmlns:xdt="...">
  <compilation 
    batch="false"
    xdt:Transform="SetAttributes(batch)">
  </compilation>
</configuration>

Auslassen von Locator-Attributen

Locator-Attribute sind optional. Wenn Sie kein Locator-Attribut angeben, wird das zu ändernde Element implizit von dem Element angegeben, für das das Transform-Attribut angegeben wird. Im folgenden Beispiel wird das ganze system.web-Element ersetzt, da kein Locator-Attribut angegeben ist.

<?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>

Verwenden der Transform- und Locator-Attribute für separate Elemente

Ein Transform-Attribut muss nicht im gleichen Element wie ein Locator-Element festgelegt werden. Sie können ein Locator-Element für ein übergeordnetes Element angeben, um Elemente auszuwählen, mit deren untergeordneten Elementen Sie arbeiten möchten. Anschließend können Sie ein Transform-Attribut in einem untergeordneten Element angeben, um eine Änderung auf die untergeordneten Elemente anzuwenden.

Im folgenden Beispiel wird gezeigt, wie das Locator-Attribut verwendet wird, location-Elemente für den angegebenen Pfad auszuwählen. Es werden jedoch nur Elemente transformiert, die untergeordnete Elemente der ausgewählten location-Elemente sind.

<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>

Wenn Sie ein Locator-Attribut angeben, ohne im gleichen Element oder in einem untergeordneten Element ein Transform-Attribut anzugeben, werden keine Änderungen vorgenommen.

Siehe auch

Konzepte

Einstieg in die Webbereitstellung für Visual Studio und ASP.NET

Weitere Ressourcen

Web.config-Dateitransformationen (Lernprogramm auf der ASP.NET-Site)