Configurar los parámetros para la implementación de paquetes web

  • Artículo

Por Jason Lee

En este tema se describe cómo establecer valores de parámetro, como nombres de aplicación web de Internet Information Services (IIS), cadenas de conexión y puntos de conexión de servicio, al implementar un paquete web en un servidor web remoto de IIS.

Al compilar un proyecto de aplicación web, el proceso de compilación y empaquetado genera tres archivos de claves:

  • Un archivo [nombre del proyecto].zip. Este es el paquete de implementación web para el proyecto de aplicación web. Este paquete contiene todos los ensamblados, archivos, scripts de base de datos y recursos necesarios para volver a crear la aplicación web en un servidor web remoto de IIS.
  • Un archivo [nombre del proyecto].deploy.cmd. Contiene un conjunto de comandos parametrizados de Web Deploy (MSDeploy.exe) que publican el paquete de implementación web en un servidor web remoto de IIS.
  • Un archivo [nombre del proyecto].SetParameters.xml. Proporciona un conjunto de valores de parámetro al comando MSDeploy.exe. Puede actualizar los valores de este archivo y pasarlos a Web Deploy como un parámetro de línea de comandos al implementar el paquete web.

Nota:

Para obtener más información sobre el proceso de compilación y empaquetado, vea Compilación y empaquetado de proyectos de aplicación web.

El archivo SetParameters.xml se genera dinámicamente a partir del archivo de proyecto de aplicación web y de los archivos de configuración del proyecto. Al compilar y empaquetar el proyecto, la canalización de publicación web (WPP, por sus siglas en inglés) detectará automáticamente muchas de las variables que probablemente cambien entre entornos de implementación, como la aplicación web de IIS de destino y cualquier cadena de conexión de base de datos. Estos valores se parametrizan automáticamente en el paquete de implementación web y se agregan al archivo SetParameters.xml. Por ejemplo, si agrega una cadena de conexión al archivo web.config en el proyecto de aplicación web, el proceso de compilación detectará este cambio y agregará una entrada al archivo SetParameters.xml según corresponda.

En muchos casos, esta parametrización automática será suficiente. Sin embargo, si los usuarios necesitan variar otras configuraciones entre entornos de implementación, como la configuración de la aplicación o las direcciones URL del punto de conexión de servicio, debe indicar a la WPP que parametrice estos valores en el paquete de implementación y agregue las entradas correspondientes al archivo SetParameters.xml. En las secciones siguientes se explica cómo hacerlo.

Parametrización automática

Al compilar y empaquetar una aplicación web, la canalización de publicación web (WPP) parametrizará automáticamente lo siguiente:

  • La ruta de acceso y el nombre de la aplicación web de destino de IIS.
  • Cualquier cadena de conexión del archivo web.config.
  • Las cadenas de conexión para las bases de datos que agregue a la pestaña Empaquetar/publicar SQL en las páginas de propiedades del proyecto.

Por ejemplo, si tuviera que compilar y empaquetar la solución de ejemplo Contact Manager sin tocar el proceso de parametrización de ninguna manera, la WPP generaría este archivo ContactManager.Mvc.SetParameters.xml:

<parameters>
  <setParameter 
    name="IIS Web Application Name" 
    value="Default Web Site/ContactManager.Mvc_deploy" />  
  <setParameter 
    name="ApplicationServices-Web.config Connection String" 
    value="Data Source=DEVWORKSTATION\SQLEXPRESS;Initial Catalog=CMAppServices;
           Integrated Security=true;" />
</parameters>

En este caso:

  • El parámetro IIS Web Application Name es la ruta de acceso de IIS donde quiere implementar la aplicación web. El valor predeterminado se toma de la página Empaquetar/publicar web en las páginas de propiedades del proyecto.
  • El parámetro ApplicationServices-Web.config Connection String se generó a partir de un elemento connectionStrings/add en el archivo web.config. Representa la cadena de conexión que la aplicación debe usar para ponerse en contacto con la base de datos de pertenencia. El valor que proporcione aquí se reemplazará en el archivo web.config implementado. El valor predeterminado se toma del archivo web.config anterior a la implementación.

La WPP también parametriza estas propiedades en el paquete de implementación que genera. Puede proporcionar valores para estas propiedades al instalar el paquete de implementación. Si instala el paquete manualmente mediante el Administrador de IIS, como se describe en el artículo Instalación manual de paquetes web, el asistente para la instalación le pedirá que proporcione valores para los parámetros. Si instala el paquete de forma remota mediante el archivo .deploy.cmd, como se describe en el artículo Implementación de paquetes web, Web Deploy se basará en este archivo SetParameters.xml para proporcionar los valores de parámetro. Puede editar los valores del archivo SetParameters.xml manualmente, o bien puede personalizar el archivo como parte de un proceso de compilación e implementación automatizados. Este proceso se describe con más detalle más adelante en este tema.

Parametrización personalizada

En escenarios de implementación más complejos, a menudo querrá parametrizar propiedades adicionales antes de implementar el proyecto. Por lo general, debe parametrizar las propiedades y la configuración que variarán entre los entornos de destino. Estas pueden incluir:

  • Puntos de conexión de servicio en el archivo web.config.
  • Configuración de la aplicación en el archivo web.config.
  • Cualquier otra propiedad declarativa que quiera que los usuarios especifiquen.

La manera más fácil de parametrizar estas propiedades es agregar un archivo parameters.xml a la carpeta raíz del proyecto de aplicación web. Por ejemplo, en la solución Contact Manager, el proyecto ContactManager.Mvc incluye un archivo parameters.xml en la carpeta raíz.

In the Contact Manager solution, the ContactManager.Mvc project includes a parameters.xml file in the root folder.

Si abre este archivo, verá que contiene una sola entrada de parámetro. La entrada usa una consulta del lenguaje de rutas XML (XPath) para buscar y parametrizar la dirección URL del punto de conexión del servicio ContactService de Windows Communication Foundation (WCF) en el archivo web.config.

<parameters>
  <parameter name="ContactService Service Endpoint Address"
             description="Specify the endpoint URL for the ContactService WCF 
                          service in the destination environment"
             defaultValue="http://localhost/ContactManagerService">
    <parameterEntry kind="XmlFile" scope="Web.config"
                    match="/configuration/system.serviceModel/client
                           /endpoint[@name='BasicHttpBinding_IContactService']
                           /@address" />
  </parameter>
</parameters>

Además de parametrizar la dirección URL del punto de conexión en el paquete de implementación, la WPP también agrega una entrada correspondiente en el archivo SetParameters.xml que se genera junto con el paquete de implementación.

<parameters>
  ...  
  <setParameter 
    name="ContactService Service Endpoint Address" 
    value="http://localhost/ContactManagerService" />
  ...
</parameters>

Si instala el paquete de implementación manualmente, el Administrador de IIS le pedirá la dirección del punto de conexión de servicio junto con las propiedades que se parametrizaron automáticamente. Si instala el paquete de implementación ejecutando el archivo .deploy.cmd, puede editar el archivo SetParameters.xml para proporcionar un valor para la dirección del punto de conexión de servicio, así como valores para las propiedades que se parametrizaron automáticamente.

Para obtener información detallada sobre cómo crear un archivo parameters.xml, consulte Uso de parámetros para configurar las opciones de implementación cuando se instala un paquete. El procedimiento denominado Uso de parámetros de implementación para configurar el archivo Web.config proporciona instrucciones paso a paso.

Modificación del archivo de SetParameters.xml

Si tiene previsto implementar manualmente el paquete de aplicación web, ya sea ejecutando el archivo .deploy.cmd o ejecutando MSDeploy.exe desde la línea de comandos, no hay nada que le impida editar manualmente el archivo SetParameters.xml antes de la implementación. Sin embargo, si está trabajando en una solución a escala empresarial, es posible que tenga que implementar un paquete de aplicación web como parte de un proceso de compilación e implementación más grande y automatizado. En este escenario, necesitará usar Microsoft Build Engine (MSBuild) para modificar el archivo SetParameters.xml. Puede hacerlo mediante la tarea XmlPoke de MSBuild.

La solución de ejemplo Contact Manager ilustra este proceso. Los ejemplos de código siguientes se han editado para mostrar solo los detalles pertinentes para este ejemplo.

Nota:

Para obtener información general más amplia sobre el modelo de archivos del proyecto en la solución de ejemplo y una introducción a los archivos del proyecto personalizados en general, vea Descripción del archivo del proyecto y Descripción del proceso de compilación.

En primer lugar, los valores de parámetro de interés se definen como propiedades en el archivo de proyecto específico del entorno (por ejemplo, Env-Dev.proj).

<PropertyGroup> 
  <ContactManagerIisPath Condition=" '$(ContactManagerIisPath)'=='' ">
    DemoSite/ContactManager
  </ContactManagerIisPath>
  <ContactManagerTargetUrl Condition =" '$(ContactManagerTargetUrl)'=='' ">
    http://localhost:85/ContactManagerService/ContactService.svc
  </ContactManagerTargetUrl>
  <MembershipConnectionString Condition=" '$(MembershipConnectionString)'=='' ">
    Data Source=TESTDB1;Integrated Security=true;Initial Catalog=CMAppServices
  </MembershipConnectionString>  
</PropertyGroup>

Nota:

Para obtener instrucciones sobre cómo personalizar los archivos del proyecto específicos del entorno para entornos de servidor propios, vea Configuración de propiedades de implementación para un entorno de destino.

Posteriormente, el archivo Publish.proj importa estas propiedades. Dado que cada archivo SetParameters.xml está asociado a un archivo .deploy.cmd y, en última instancia, queremos que el archivo de proyecto invoque cada archivo .deploy.cmd, el archivo de proyecto crea un elemento de MSBuild para cada archivo .deploy.cmd y define las propiedades de interés como metadatos del elemento.

<ItemGroup>
  <PublishPackages Include="$(_ContactManagerDest)ContactManager.Mvc.deploy.cmd"> 
    <ParametersXml>
      $(_ContactManagerDest)ContactManager.Mvc.SetParameters.xml
    </ParametersXml>
    <IisWebAppName>
      $(ContactManagerIisPath)
    </IisWebAppName> 
    <MembershipDBConnectionName>
      ApplicationServices-Web.config Connection String
    </MembershipDBConnectionName>
    <MembershipDBConnectionString>
      $(MembershipConnectionString.Replace(";","%3b"))
    </MembershipDBConnectionString>
    <ServiceEndpointParamName>
      ContactService Service Endpoint Address
    </ServiceEndpointParamName>
    <ServiceEndpointValue>
      $(ContactManagerTargetUrl)
    </ServiceEndpointValue>
  </PublishPackages>
  ...
</ItemGroup>

En este caso:

  • El valor ParametersXml de los metadatos indica la ubicación del archivo SetParameters.xml.
  • El valor IisWebAppName es la ruta de acceso de IIS en la que quiere implementar la aplicación web.
  • El valor MembershipDBConnectionString es la cadena de conexión de la base de datos de pertenencia, y el valor MembershipDBConnectionName es el atributo name del parámetro correspondiente en el archivo SetParameters.xml.
  • El valor ServiceEndpointValue es la dirección del punto de conexión del servicio WCF en el servidor de destino, y el valor ServiceEndpointParamName es el atributo name del parámetro correspondiente en el archivo SetParameters.xml.

Por último, en el archivo Publish.proj, el destino PublishWebPackages usa la tarea XmlPoke para modificar estos valores en el archivo SetParameters.xml.

<Target Name="PublishWebPackages" Outputs="%(PublishPackages.Identity)">
  <XmlPoke 
    XmlInputPath="%(PublishPackages.ParametersXml)"
    Query="//parameters/setParameter[@name='%(PublishPackages.ConnectionName)']
           /@value"
    Value="%(PublishPackages.ConnectionString)"
    Condition =" '%(PublishPackages.ConnectionName)'!=''" 
  />
  <XmlPoke 
    XmlInputPath="%(PublishPackages.ParametersXml)"
    Query="//parameters/setParameter
           [@name='%(PublishPackages.MembershipDBConnectionName)']/@value"
    Value='%(PublishPackages.MembershipDBConnectionString)'
    Condition =" '%(PublishPackages.MembershipDBConnectionName)'!=''" 
  />
  <XmlPoke 
    XmlInputPath="%(PublishPackages.ParametersXml)"
    Query="//parameters/setParameter[@name='IIS Web Application Name']/@value"
    Value="%(PublishPackages.IisWebAppName)"
    Condition =" '%(PublishPackages.IisWebAppName)'!=''" 
  />
  <XmlPoke 
    XmlInputPath="%(PublishPackages.ParametersXml)"
    Query="//parameters/setParameter
           [@name='%(PublishPackages.ServiceEndpointParamName)']/@value"
    Value="%(PublishPackages.ServiceEndpointValue)"
    Condition =" '%(PublishPackages.ServiceEndpointParamName)'!=''" 
  /> 
  <!--Execute the .deploy.cmd file--> 
  ...
</Target>

Observará que cada tarea XmlPoke especifica cuatro valores de atributo:

  • El atributo XmlInputPath indica a la tarea dónde encontrar el archivo que quiere modificar.
  • El atributo Query es una consulta XPath que identifica el nodo XML que quiere cambiar.
  • El atributo Value es el nuevo valor que quiere insertar en el nodo XML seleccionado.
  • El atributo Condition incluye los criterios según los que se debe ejecutar o no la tarea. En estos casos, la condición garantiza que no intente insertar un valor null o vacío en el archivo SetParameters.xml.

Conclusión

En este tema se describe el rol del archivo SetParameters.xml y se explica cómo se genera al compilar un proyecto de aplicación web. También se explica cómo puede parametrizar la configuración adicional agregando un archivo parameters.xml al proyecto. Además, se describe cómo puede modificar el archivo SetParameters.xml como parte de un proceso de compilación más grande y automatizado mediante la tarea XmlPoke en los archivos del proyecto.

En el tema siguiente, Implementación de paquetes web, se describe cómo puede implementar un paquete web mediante la ejecución del archivo .deploy.cmd o usando comandos de MSDeploy.exe directamente. En ambos casos, puede especificar el archivo SetParameters.xml como un parámetro de implementación.

Lecturas adicionales

Para obtener información sobre cómo crear paquetes web, vea Compilación y empaquetado de proyectos de aplicación web. Para obtener instrucciones sobre cómo implementar realmente un paquete web, consulte Implementación de paquetes web. Para obtener un tutorial paso a paso sobre cómo crear un archivo parameters.xml, consulte Uso de parámetros para configurar las opciones de implementación cuando se instala un paquete.

Para obtener más información general sobre la parametrización en Web Deploy, consulte Parametrización de Web Deploy en acción (entrada de blog).

AnteriorSiguiente