Sintaxis de transformación de Web.config para la implementación de proyectos de aplicación web
Los archivos Web.config suelen incluir valores que varían en función del entorno en el que se ejecuta la aplicación. Por ejemplo, es posible que deba cambiar una cadena de conexión de base de datos o deshabilitar la depuración al implementar un archivo Web.config. Para los proyectos de aplicación web, ASP.NET proporciona herramientas que automatizan el proceso de cambio (transformación) de archivos Web.config cuando se implementan. Para cada entorno en el que desee realizar una implementación, debe crear un archivo de transformación que especifique solo las diferencias entre el archivo Web.config original y el archivo Web.config para ese entorno.
Un archivo de transformación es un archivo XML que especifica cómo se debería cambiar el archivo Web.config al implementarlo. Las acciones de transformación se especifican utilizando atributos XML que se definen en el espacio de nombres XML-Document-Transform, que se asigna al prefijo xdt. El espacio de nombres XML-Document-Transform define dos atributos: Locator y Transform. El atributo Locator especifica el elemento o conjunto de elementos Web.config que desea cambiar de algún modo. El atributo Transform especifica lo que desea hacer en los elementos que localiza el atributo Locator.
En el siguiente ejemplo se muestra el contenido de un archivo de transformación que cambia una cadena de conexión y reemplaza el elemento 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>
El elemento raíz de un archivo de transformación debe especificar el espacio de nombres XML-Document-Transform en su etiqueta de apertura, tal como se muestra en el ejemplo anterior. Los propios elementos Transform y Locator no se reproduce en el archivo Web.config implementado.
En las siguientes secciones se proporciona información de referencia sobre la sintaxis que se usa en los archivos de transformación.
Sintaxis del atributo Locator
En cada una de las siguientes secciones se explica la sintaxis de un atributo Locator.
Condition
Especifica una expresión XPath que se anexa a la expresión XPath del elemento actual. Se selecciona los elementos que coinciden con la expresión XPath combinada.
Sintaxis
Locator="Condition(XPath expression)"
Ejemplo
En el siguiente ejemplo se muestra cómo seleccionar elementos de cadena de conexión cuyo valor de atributo name es oldname o cuyo valor de atributo providerName es oldprovider. En el archivo Web.config implementado, los elementos seleccionados se reemplazan con el elemento que se especifica en el archivo de transformación.
<configuration xmlns:xdt="...">
<connectionStrings>
<add name="AWLT" connectionString="newstring"
providerName="newprovider"
xdt:Transform="Replace"
xdt:Locator="Condition(@name='oldname'
or @providerName='oldprovider')" />
</connectionStrings>
</configuration>
La expresión XPath que se aplica al archivo Web.config de desarrollo como resultado de la expresión Condition especificada es la siguiente:
configuration/connectionStrings[@name='AWLT' or @providerName='System.Data.SqlClient']
Esta expresión es el resultado de combinar la condición XPath implícita del elemento actual (configuration/connectionStrings) con la expresión que se especifica explícitamente.
Match
Selecciona el elemento o elementos que tienen un valor correspondiente para los atributos especificados. Si se especifican varios nombres de atributo, solo se seleccionan los elementos que coinciden con todos los atributos especificados.
Sintaxis
Locator="Match(comma-delimited list of one or more attribute names)"
Ejemplo
En el siguiente ejemplo se muestra cómo seleccionar el elemento add de cadena de conexión que tiene AWLT en el atributo name en el archivo Web.config de desarrollo. En el archivo Web.config implementado, el elemento seleccionado se reemplaza con el elemento add que se especifica en el archivo de transformación.
<configuration xmlns:xdt="...">
<connectionStrings>
<add name="AWLT" connectionString="newstring"
providerName="newprovider"
xdt:Transform="Replace"
xdt:Locator="Match(name)" />
</connectionStrings>
</configuration>
XPath
Especifica una expresión XPath absoluta que se aplica al archivo Web.config de desarrollo. (A diferencia de Condition, la expresión que se especifica no se anexa a la expresión XPath implícita que corresponde al elemento actual).
Sintaxis
Locator="XPath(XPath expression)"
Ejemplo
En el siguiente ejemplo se muestra cómo seleccionar los mismos elementos que se seleccionan en el ejemplo anterior para la palabra clave 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>
Sintaxis del atributo Transform
En cada una de las siguientes secciones se explica la sintaxis de un atributo Transform.
Replace
Reemplaza el elemento seleccionado por el elemento que se especifica en el archivo de transformación. Si hay más de un elemento seleccionado, solo se reemplaza el primer elemento seleccionado. Para obtener un ejemplo sobre la utilización de la palabra clave Replace, vea los ejemplos de los atributos Locator.
Sintaxis
Transform="Replace"
Insert
Agrega el elemento que se define en el archivo de transformación como un elemento relacionado con los elementos seleccionados. El nuevo elemento se agrega al final de cualquier colección.
Sintaxis
Transform="Insert"
Ejemplo
En el siguiente ejemplo se muestra cómo seleccionar todas las cadenas de conexión del archivo Web.config de desarrollo. En el archivo Web.config implementado, la cadena de conexión especificada se agrega al final de la colección.
<configuration xmlns:xdt="...">
<connectionStrings>
<add name="AWLT" connectionString="newstring"
providerName="newprovider"
xdt:Transform="Insert" />
</connectionStrings>
</configuration>
InsertBefore
Inserta el elemento que se define en el archivo XML de transformación directamente antes del elemento que selecciona la expresión XPath especificada. La expresión XPath debe ser una expresión absoluta, porque se aplica al archivo Web.config de desarrollo como un conjunto; no se anexa solamente a la expresión XPath implícita del elemento actual.
Sintaxis
Transform="InsertBefore(XPath expression)"
Ejemplo
El siguiente ejemplo muestra cómo seleccionar el elemento deny que deniega el acceso a todos los usuarios y, a continuación, inserta un elemento allow antes de él que concede acceso a los administradores.
<configuration xmlns:xdt="...">
<authorization>
<allow roles="Admins"
xdt:Transform="InsertBefore(/configuration/system.web/authorization/deny[@users='*'])" />
</authorization>
</configuration>
InsertAfter
Inserta el elemento que se define en el archivo XML de transformación directamente después del elemento que selecciona la expresión XPath especificada. La expresión XPath debe ser una expresión absoluta, porque se aplica al archivo Web.config de desarrollo como un conjunto; no se anexa a la expresión XPath implícita del elemento actual.
Sintaxis
Transform="InsertAfter(XPath expression)"
Ejemplo
El siguiente ejemplo muestra cómo seleccionar el elemento allow que permite el acceso a los administradores e inserta un elemento deny después de él que deniega el acceso a un usuario especificado.
<configuration xmlns:xdt="...">
<authorization>
<deny users="UserName"
xdt:Transform="InsertAfter
(/configuration/system.web/authorization/allow[@roles='Admins'])" />
</authorization>
</configuration>
Remove
Quita el elemento seleccionado. Si hay varios elementos seleccionados, quita el primer elemento.
Sintaxis
Transform="Remove"
Ejemplo
En el siguiente ejemplo se muestra cómo seleccionar todos los elementos add de cadena de conexión del archivo Web.config de desarrollo. En el archivo Web.config implementado solo se quita el primer elemento de cadena de conexión.
<configuration xmlns:xdt="...">
<connectionStrings>
<add xdt:Transform="Remove" />
</connectionStrings>
</configuration>
RemoveAll
Quita los elementos seleccionados.
Sintaxis
Transform="RemoveAll"
Ejemplo
En el siguiente ejemplo se muestra cómo seleccionar todas las cadenas de conexión del archivo Web.config de desarrollo. En el archivo Web.config implementado se quitan todos los elementos.
<configuration xmlns:xdt="...">
<connectionStrings>
<add xdt:Transform="RemoveAll" />
</connectionStrings>
</configuration>
RemoveAttributes
Quita los atributos especificados de los elementos seleccionados.
Sintaxis
Transform="RemoveAttributes(comma-delimited list of one or more attribute names)"
Ejemplo
En el siguiente ejemplo se muestra cómo seleccionar todos los elementos compilation del archivo Web.config de desarrollo. (Dado que solo puede haber un elemento compilation en el archivo de configuración, no tiene que especificar un atributo Locator). En el archivo Web.config implementado, los atributos debug y batch se quitan del elemento compilation.
<configuration xmlns:xdt="...">
<compilation
xdt:Transform="RemoveAttributes(debug,batch)">
</compilation>
</configuration>
SetAttributes
Establece atributos para los elementos seleccionados en los valores especificados. El atributo de transformación Replace reemplaza un elemento completo incluso todos sus atributos. Por el contrario, el atributo SetAttributes permite mantener el elemento como está y cambiar atributos seleccionados.
Sintaxis
Transform="SetAttributes(comma-delimited list of one or more attribute names)"
Ejemplo
En el siguiente ejemplo se muestra cómo seleccionar todos los elementos compilation del archivo Web.config de desarrollo. (Dado que solo puede haber un elemento compilation en el archivo de configuración, no tiene que especificar un atributo Locator). En el archivo Web.config implementado, el valor del atributo batch del elemento compilation se establece en false.
<configuration xmlns:xdt="...">
<compilation
batch="false"
xdt:Transform="SetAttributes(batch)">
</compilation>
</configuration>
Omitir los atributos Locator
Los atributos Locator son opcionales. Si no especifica un atributo Locator, el elemento que se va a cambiar se especifica implícitamente mediante el elemento para el que se especifica el atributo Transform. En el siguiente ejemplo, se reemplaza el elemento system.web completo, porque no se especifica ningún atributo Locator para indicar lo contrario.
<?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>
Usar atributos Transform y Locator en elementos independientes
Un atributo Transform no se tiene que establecer en el mismo elemento que un atributo Locator. Puede especificar un atributo Locator en un elemento primario para seleccionar los elementos con cuyos elementos secundarios desea trabajar. A continuación, puede especificar un atributo Transform en un elemento secundario para aplicar un cambio en los elementos secundarios.
En el siguiente ejemplo se muestra cómo utilizar el atributo Locator para seleccionar los elementos location de la ruta de acceso especificada. Sin embargo, solo se transforman los elementos que son elementos secundarios de los elementos location seleccionados.
<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>
Si especifica un atributo Locator pero no especifica ningún atributo Transform en el mismo elemento o en un elemento secundario, no se realiza ningún cambio.
Nota
Un atributo Transform en un elemento primario puede afectar a los elementos secundarios que no se especifique ningún atributo Transform para ellos.Por ejemplo, si coloca el atributo xdt:Transform="Replace" en el elemento system.web, todos los elementos que son elementos secundarios del elemento system.web se reemplazan con el contenido del archivo de transformación.
Vea también
Conceptos
Información general sobre la implementación de proyectos de aplicación web ASP.NET
Historial de cambios
Fecha |
Historial |
Motivo |
|---|---|---|
|
Mayo de 2011 |
Se ha corregido la explicación de cómo funciona el atributo de transformación Replace. |
Comentarios de los clientes. |