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

Die Web.config-Dateien enthalten normalerweise Einstellungen, die sich je nach der Umgebung, in der die Anwendung ausgeführt wird, unterscheiden. Beim Bereitstellen einer Web.config-Datei kann es z. B. erforderlich sein, eine Datenbankverbindungszeichenfolge zu ändern oder das Debuggen zu deaktivieren. Für Webanwendungsprojekte stellt ASP.NET Tools bereit, die das Ändern (Transformieren) von Web.config-Dateien bei der Bereitstellung automatisieren. Für jede Umgebung, in der Sie eine Bereitstellung durchführen möchten, erstellen Sie eine Transformationsdatei, in der nur die Unterschiede zwischen der ursprünglichen Web.config-Datei und der bereitgestellten Web.config-Datei für diese Umgebung angegeben sind.

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.

Die folgenden Abschnitte enthalten Referenzinformationen zur Syntax für Transformationsdateien.

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

Im folgenden Beispiel wird gezeigt, wie das deny-Element ausgewählt wird, das allen Benutzern den Zugriff verweigert und anschließend davor ein allow-Element einfügt, das Administratoren den Zugriff gewährt.

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

Remove

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.

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

Übersicht über die Bereitstellung von ASP.NET-Webanwendungsprojekten

Exemplarische Vorgehensweise: Bereitstellen eines Webanwendungsprojekts mit einem Webbereitstellungspaket (Teil 1 von 4)

Änderungsprotokoll