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

  • Article

par Jason Lee

Cette rubrique explique comment définir des valeurs de paramètres, 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 Web Deploy (MSDeploy.exe) paramétrées qui publient votre package de déploiement web sur un serveur web IIS distant.
  • [ nom du projet].SetParameters.xml fichier. Cela fournit un ensemble de valeurs de paramètres à la commande MSDeploy.exe. Vous pouvez mettre à jour les valeurs de ce fichier et les passer à Web Deploy en tant que paramètre de ligne de commande lorsque vous déployez votre package web.

Notes

Pour plus d’informations sur le processus de génération et d’empaquetage, consultez Création et empaquetage de projets d’application web.

Le fichierSetParameters.xml est généré dynamiquement à partir de votre fichier projet d’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 de nombreuses variables susceptibles de changer entre les environnements de déploiement, comme l’application web IIS de destination et 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 fichierSetParameters.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 de nombreux cas, ce paramétrage automatique sera suffisant. Toutefois, si vos utilisateurs doivent varier d’autres paramètres entre les environnements de déploiement, comme 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 suivantes expliquent comment procéder.

Paramétrage automatique

Lorsque vous générez et empaquetez une application web, le WPP paramétre automatiquement les éléments suivants :

  • 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 au processus de paramétrage de quelque manière que ce soit, le WPP générerait ce fichierContactManager.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 Nom de l’application web IIS est le chemin IIS où 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 chaîne de connexionApplicationServices-Web.config a été généré à partir d’un élément connectionStrings/add dans le fichier web.config . Il 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 deweb.configde prédéploiement .

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 des services Internet, comme décrit dans Installation manuelle de 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 se tournera vers ce fichierSetParameters.xml pour fournir les valeurs de paramètre. Vous pouvez modifier manuellement les valeurs du fichier SetParameters.xml ou personnaliser le fichier dans le cadre d’un processus de génération et de déploiement automatisé. 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 d’un environnement de destination à l’autre. 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.

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 seule entrée de paramètre . 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>

En plus de paramétrer l’URL du point de terminaison dans le package de déploiement, WPP ajoute également une entrée correspondante au fichier SetParameters.xml 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 le package de déploiement manuellement, le Gestionnaire des services Internet vous invite à entrer l’adresse du point de terminaison de service en plus des propriétés qui ont été paramétrées 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 du point de terminaison de service ainsi que des valeurs pour les propriétés qui ont été paramétrées automatiquement.

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

Modification du fichier SetParameters.xml

Si vous envisagez de déployer le package d’application web manuellement (en exécutant le fichier .deploy.cmd ou en exécutant MSDeploy.exe à partir de la ligne de commande), rien ne vous empêche 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 automatisé plus large. Dans ce scénario, vous avez besoin de l’Microsoft Build Engine (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 suivants ont été modifiés pour afficher uniquement les détails pertinents pour cet exemple.

Notes

Pour obtenir une vue d’ensemble plus large du modèle de fichier projet dans l’exemple de solution et une présentation des fichiers projet personnalisés en général, consultez Comprendre le fichier projet et comprendre le processus de génération.

Tout d’abord, les valeurs de paramètre intéressantes 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>

Notes

Pour obtenir des conseils sur la façon de personnaliser les fichiers projet spécifiques à l’environnement pour vos propres environnements serveurs, consultez Configurer les propriétés de déploiement pour un environnement cible.

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 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 sur 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 name du paramètre correspondant dans le fichier SetParameters.xml .
  • La valeur ServiceEndpointValue est l’adresse du point de terminaison du service WCF sur le serveur de destination, et la valeur ServiceEndpointParamName est l’attribut name 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 Query est une requête XPath qui identifie le nœud XML que vous souhaitez modifier.
  • L’attribut Value est la nouvelle valeur que vous souhaitez insérer dans le nœud XML sélectionné.
  • L’attribut Condition est le critère sur lequel la tâche doit s’exécuter ou ne pas s’exécuter. Dans ce 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 explique comment paramétrer des paramètres supplémentaires en ajoutant un fichier parameters.xml à votre projet. Il décrit également comment vous pouvez modifier le fichier SetParameters.xml dans le cadre d’un processus de génération automatisé plus large à 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 MSDeploy.exe commandes. Dans les deux cas, vous pouvez spécifier votre fichier SetParameters.xml en tant que paramètre de déploiement.

En savoir plus

Pour plus d’informations sur la création de packages web, consultez Création et empaquetage de projets d’application web. Pour obtenir des conseils sur le déploiement réel 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 configurer les paramètres de déploiement lors de l’installation d’un package.

Pour plus d’informations générales sur le paramétrage dans Web Deploy, consultez Paramétrage du déploiement web en action (billet de blog).

PrécédentSuivant