Configuration des paramètres pour le déploiement de package web

par Jason Lee

Cette rubrique explique comment définir des valeurs de paramètre, telles que les noms d’applications web IIS (Internet Information Services), les chaînes de connexion et les points de terminaison de service, lorsque vous déployez un package web sur un serveur web IIS distant.

Lorsque vous générez un projet d’application web, le processus de génération et d’empaquetage génère trois fichiers clés :

• Un fichier [nom du projet].zip . Il s’agit du package de déploiement web pour votre projet d’application web. Ce package contient tous les assemblys, fichiers, scripts de base de données et ressources nécessaires pour recréer votre application web sur un serveur web IIS distant.
• Un fichier [nom du projet].deploy.cmd . Il contient un ensemble de commandes de déploiement web paramétrables (MSDeploy.exe) qui publient votre package de déploiement web sur un serveur web IIS distant.
• Un fichier [nom du projet].SetParameters.xml . Cela fournit un ensemble de valeurs de paramètre à la commande MSDeploy.exe. Vous pouvez mettre à jour les valeurs de ce fichier et la transmettre à Web Deploy en tant que paramètre de ligne de commande lorsque vous déployez votre package web.

Le fichier SetParameters.xml est généré dynamiquement à partir du fichier projet de votre application web et de tous les fichiers de configuration au sein de votre projet. Lorsque vous générez et empaquetez votre projet, le pipeline de publication web (WPP) détecte automatiquement un grand nombre de variables susceptibles de changer entre les environnements de déploiement, comme l’application web IIS de destination et toutes les chaînes de connexion de base de données. Ces valeurs sont automatiquement paramétrées dans le package de déploiement web et ajoutées au fichier SetParameters.xml . Par exemple, si vous ajoutez une chaîne de connexion au fichier web.config dans votre projet d’application web, le processus de génération détecte cette modification et ajoute une entrée au fichier SetParameters.xml en conséquence.

Dans beaucoup de cas, ce paramétrage automatique sera suffisant. Toutefois, si vos utilisateurs doivent varier d’autres paramètres entre les environnements de déploiement, tels que les paramètres d’application ou les URL de point de terminaison de service, vous devez indiquer à WPP de paramétrer ces valeurs dans le package de déploiement et d’ajouter des entrées correspondantes au fichier SetParameters.xml . Les sections qui suivent expliquent comment procéder.

Paramétrage automatique

Lorsque vous générez et empaquetez une application web, wpP paramétre automatiquement ces éléments :

• Chemin et nom de l’application web IIS de destination.
• Toutes les chaînes de connexion dans votre fichier web.config .
• Chaînes de connexion pour toutes les bases de données que vous ajoutez à l’onglet Package/Publier SQL dans les pages de propriétés du projet.

Par exemple, si vous deviez générer et empaqueter l’exemple de solution Contact Manager sans toucher le processus de paramétrage de quelque manière que ce soit, wpP génère ce fichier 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>

Dans ce cas :

• Le paramètre IIS Web Application Name est le chemin d’accès IIS dans lequel vous souhaitez déployer l’application web. La valeur par défaut est extraite de la page Web Package/Publish dans les pages de propriétés du projet.
• Le paramètre ApplicationServices-Web.config Connection String a été généré à partir d’un élément connectionStrings/add dans le fichier web.config . Elle représente la chaîne de connexion que l’application doit utiliser pour contacter la base de données d’appartenance. La valeur que vous fournissez ici sera remplacée dans le fichier web.config déployé. La valeur par défaut est extraite du fichier de prédéploiementweb.config .

WpP paramétre également ces propriétés dans le package de déploiement qu’il génère. Vous pouvez fournir des valeurs pour ces propriétés lorsque vous installez le package de déploiement. Si vous installez le package manuellement via le Gestionnaire IIS, comme décrit dans l’installation manuelle des packages web, l’Assistant Installation vous invite à fournir des valeurs pour tous les paramètres. Si vous installez le package à distance à l’aide du fichier .deploy.cmd , comme décrit dans Déploiement de packages web, Web Deploy recherche ce fichier SetParameters.xml pour fournir les valeurs des paramètres. Vous pouvez modifier les valeurs dans le fichier SetParameters.xml manuellement, ou vous pouvez personnaliser le fichier dans le cadre d’un processus de génération et de déploiement automatisés. Ce processus est décrit plus en détail plus loin dans cette rubrique.

Paramétrage personnalisé

Dans des scénarios de déploiement plus complexes, vous souhaiterez souvent paramétrer des propriétés supplémentaires avant de déployer votre projet. En règle générale, vous devez paramétrer toutes les propriétés et paramètres qui varient entre les environnements de destination. Ces stratégies peuvent inclure :

• Points de terminaison de service dans le fichier web.config .
• Paramètres d’application dans le fichier web.config .
• Toutes les autres propriétés déclaratives que vous souhaitez inviter les utilisateurs à spécifier.

Le moyen le plus simple de paramétrer ces propriétés consiste à ajouter un fichier parameters.xml au dossier racine de votre projet d’application web. Par exemple, dans la solution Gestionnaire de contacts, le projet ContactManager.Mvc inclut un fichier parameters.xml dans le dossier racine.

Si vous ouvrez ce fichier, vous verrez qu’il contient une entrée de paramètre unique. L’entrée utilise une requête XPath (XML Path Language) pour localiser et paramétrer l’URL du point de terminaison du service ContactService Windows Communication Foundation (WCF) dans le fichier 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>

Outre le paramétrage de l’URL du point de terminaison dans le package de déploiement, WPP ajoute également une entrée correspondante au fichier SetParameters.xml qui est généré en même temps que le package de déploiement.

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

Si vous installez manuellement le package de déploiement, le Gestionnaire IIS vous invite à entrer l’adresse du point de terminaison de service en même temps que les propriétés paramétrables automatiquement. Si vous installez le package de déploiement en exécutant le fichier .deploy.cmd , vous pouvez modifier le fichier SetParameters.xml pour fournir une valeur pour l’adresse de point de terminaison de service, ainsi que des valeurs pour les propriétés paramétrables automatiquement.

Pour plus d’informations sur la création d’un fichier parameters.xml , consultez Guide pratique pour utiliser des paramètres pour configurer les paramètres de déploiement lorsqu’un package est installé. La procédure nommée Pour utiliser des paramètres de déploiement pour les paramètres du fichier Web.config fournit des instructions pas à pas.

Modification du fichier SetParameters.xml

Si vous envisagez de déployer manuellement le package d’application web, soit en exécutant le fichier .deploy.cmd , soit en exécutant MSDeploy.exe à partir de la ligne de commande, il n’y a rien pour vous empêcher de modifier manuellement le fichier SetParameters.xml avant le déploiement. Toutefois, si vous travaillez sur une solution à l’échelle de l’entreprise, vous devrez peut-être déployer un package d’application web dans le cadre d’un processus de génération et de déploiement plus volumineux et automatisé. Dans ce scénario, vous avez besoin du moteur de build Microsoft (MSBuild) pour modifier le fichier SetParameters.xml pour vous. Pour ce faire, utilisez la tâche MSBuild XmlPoke .

L’exemple de solution Contact Manager illustre ce processus. Les exemples de code qui suivent ont été modifiés pour afficher uniquement les détails pertinents pour cet exemple.

Tout d’abord, les valeurs de paramètre d’intérêt sont définies en tant que propriétés dans le fichier projet spécifique à l’environnement (par exemple, 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>

Ensuite, le fichier Publish.proj importe ces propriétés. Étant donné que chaque fichier SetParameters.xml est associé à un fichier .deploy.cmd et que nous voulons finalement que le fichier projet appelle chaque fichier .deploy.cmd , le fichier projet crée un élément MSBuild pour chaque fichier .deploy.cmd et définit les propriétés d’intérêt en tant que métadonnées d’élément.

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

Dans ce cas :

• La valeur des métadonnées ParametersXml indique l’emplacement du fichier SetParameters.xml .
• La valeur IisWebAppName est le chemin d’accès IIS vers lequel vous souhaitez déployer l’application web.
• La valeur MembershipDBConnectionString est la chaîne de connexion de la base de données d’appartenance, et la valeur MembershipDBConnectionName est l’attribut nom du paramètre correspondant dans le fichier SetParameters.xml .
• La valeur ServiceEndpointValue est l’adresse de point de terminaison du service WCF sur le serveur de destination, et la valeur ServiceEndpointParamName est l’attribut de nom du paramètre correspondant dans le fichier SetParameters.xml .

Enfin, dans le fichier Publish.proj , la cible PublishWebPackages utilise la tâche XmlPoke pour modifier ces valeurs dans le fichier 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>

Vous remarquerez que chaque tâche XmlPoke spécifie quatre valeurs d’attribut :

• L’attribut XmlInputPath indique à la tâche où trouver le fichier à modifier.
• L’attribut Requête est une requête XPath qui identifie le nœud XML que vous souhaitez modifier.
• L’attribut Valeur est la nouvelle valeur que vous souhaitez insérer dans le nœud XML sélectionné.
• L’attribut Condition est les critères sur lesquels la tâche doit s’exécuter ou non. Dans ces cas, la condition garantit que vous n’essayez pas d’insérer une valeur null ou vide dans le fichier SetParameters.xml .

Conclusion

Cette rubrique décrit le rôle du fichier SetParameters.xml et explique comment il est généré lorsque vous générez un projet d’application web. Il a expliqué comment paramétrer des paramètres supplémentaires en ajoutant un fichier parameters.xml à votre projet. Il a également décrit comment modifier le fichier SetParameters.xml dans le cadre d’un processus de génération automatisé plus volumineux, à l’aide de la tâche XmlPoke dans vos fichiers projet.

La rubrique suivante, Déploiement de packages web, décrit comment déployer un package web en exécutant le fichier .deploy.cmd ou en utilisant directement les commandes MSDeploy.exe. Dans les deux cas, vous pouvez spécifier votre fichier SetParameters.xml en tant que paramètre de déploiement.

Lectures complémentaires

Pour plus d’informations sur la création de packages web, consultez Création et empaquetage de projets d’applications web. Pour obtenir des conseils sur le déploiement d’un package web, consultez Déploiement de packages web. Pour obtenir une procédure pas à pas sur la création d’un fichier parameters.xml , consultez Guide pratique pour utiliser des paramètres pour configurer les paramètres de déploiement lorsqu’un package est installé.

Pour plus d’informations générales sur le paramétrage dans Web Deploy, consultez web Deploy Parameterization in Action (billet de blog).