Konfigurieren von Parametern für die Bereitstellung von Webpaketen

von Jason Lee

In diesem Thema wird beschrieben, wie Sie Parameterwerte wie Internetinformationsdienste (IIS)-Webanwendungsnamen, Verbindungszeichenfolgen und Dienstendpunkte festlegen, wenn Sie ein Webpaket auf einem IIS-Remotewebserver bereitstellen.

Wenn Sie ein Webanwendungsprojekt erstellen, generiert der Build- und Paketerstellungsprozess drei Schlüsseldateien:

• Eine [Projektname].zip Datei. Dies ist das Webbereitstellungspaket für Ihr Webanwendungsprojekt. Dieses Paket enthält alle Assemblys, Dateien, Datenbankskripts und Ressourcen, die erforderlich sind, um Ihre Webanwendung auf einem IIS-Remotewebserver neu zu erstellen.
• Eine [Projektname].deploy.cmd-Datei . Dies enthält eine Reihe parametrisierter Web Deploy-Befehle (MSDeploy.exe), die Ihr Webbereitstellungspaket auf einem IIS-Remotewebserver veröffentlichen.
• Eine [Projektname].SetParameters.xml-Datei . Dadurch wird eine Reihe von Parameterwerten für den Befehl MSDeploy.exe bereitgestellt. Sie können die Werte in dieser Datei aktualisieren und sie als Befehlszeilenparameter an Web Deploy übergeben, wenn Sie Ihr Webpaket bereitstellen.

Hinweis

Weitere Informationen zum Build- und Paketerstellungsprozess finden Sie unter Erstellen und Verpacken von Webanwendungsprojekten.

Die SetParameters.xml-Datei wird dynamisch aus Ihrer Webanwendungsprojektdatei und allen Konfigurationsdateien in Ihrem Projekt generiert. Wenn Sie Ihr Projekt erstellen und packen, erkennt die Web publishing Pipeline (WPP) automatisch viele Variablen, die sich wahrscheinlich zwischen Bereitstellungsumgebungen ändern, z. B. die IIS-Zielwebanwendung und alle Datenbankverbindungszeichenfolgen. Diese Werte werden automatisch im Webbereitstellungspaket parametrisiert und der SetParameters.xml-Datei hinzugefügt. Wenn Sie beispielsweise der web.config-Datei in Ihrem Webanwendungsprojekt eine Verbindungszeichenfolge hinzufügen, erkennt der Buildprozess diese Änderung und fügt der dateiSetParameters.xml entsprechend einen Eintrag hinzu.

In vielen Fällen ist diese automatische Parametrisierung ausreichend. Wenn Ihre Benutzer jedoch andere Einstellungen zwischen Bereitstellungsumgebungen ändern müssen, z. B. Anwendungseinstellungen oder Dienstendpunkt-URLs, müssen Sie den WPP anweisen, diese Werte im Bereitstellungspaket zu parametrisieren und der SetParameters.xml-Datei entsprechende Einträge hinzuzufügen. In den folgenden Abschnitten wird erläutert, wie Dies geschieht.

Automatische Parametrisierung

Wenn Sie eine Webanwendung erstellen und verpacken, parametrisiert das WPP automatisch folgendes:

• Pfad und Name der IIS-Zielwebanwendung.
• Alle Verbindungszeichenfolgen in Ihrer web.config-Datei .
• Verbindungszeichenfolgen für alle Datenbanken, die Sie auf den Projekteigenschaftenseiten der Registerkarte SQL-Paket/Veröffentlichen hinzufügen.

Wenn Sie beispielsweise die Contact Manager-Beispiellösung erstellen und verpacken würden, ohne den Parametrisierungsprozess in irgendeiner Weise zu berühren, würde der WPP diese ContactManager.Mvc.SetParameters.xml Datei generieren:

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

In diesem Fall:

• Der IIS-Webanwendungsname-Parameter ist der IIS-Pfad, in dem Sie die Webanwendung bereitstellen möchten. Der Standardwert wird von der Seite Paket/Veröffentlichung auf den Projekteigenschaftenseiten übernommen.
• Der parameterApplicationServices-Web.config Verbindungszeichenfolge wurde aus einem connectionStrings/add-Element in der web.config-Datei generiert. Sie stellt die Verbindungszeichenfolge dar, die die Anwendung verwenden sollte, um die Mitgliedschaftsdatenbank zu kontaktieren. Der wert, den Sie hier angeben, wird in der bereitgestellten web.config-Datei ersetzt. Der Standardwert stammt aus der Datei vor der Bereitstellungweb.config.

Der WPP parametrisiert diese Eigenschaften auch im generierten Bereitstellungspaket. Sie können Werte für diese Eigenschaften angeben, wenn Sie das Bereitstellungspaket installieren. Wenn Sie das Paket manuell über den IIS-Manager installieren, wie unter Manuelles Installieren von Webpaketen beschrieben, werden Sie vom Installations-Assistenten aufgefordert, Werte für alle Parameter anzugeben. Wenn Sie das Paket remote mithilfe der Datei .deploy.cmd installieren, wie unter Bereitstellen von Webpaketen beschrieben, sucht Web Deploy nach dieser SetParameters.xml-Datei , um die Parameterwerte bereitzustellen. Sie können die Werte in der SetParameters.xml-Datei manuell bearbeiten oder die Datei im Rahmen eines automatisierten Build- und Bereitstellungsprozesses anpassen. Dieser Prozess wird weiter unten in diesem Thema ausführlicher beschrieben.

Benutzerdefinierte Parametrisierung

In komplexeren Bereitstellungsszenarien sollten Sie häufig zusätzliche Eigenschaften parametrisieren, bevor Sie Ihr Projekt bereitstellen. Im Allgemeinen sollten Sie alle Eigenschaften und Einstellungen parametrisieren, die in den Zielumgebungen variieren. Folgende sind möglich:

• Dienstendpunkte in der web.config-Datei .
• Anwendungseinstellungen in der web.config-Datei .
• Alle anderen deklarativen Eigenschaften, zu denen Sie Benutzer auffordern möchten, anzugeben.

Die einfachste Möglichkeit zum Parametrisieren dieser Eigenschaften besteht darin, dem Stammordner Ihres Webanwendungsprojekts eine parameters.xml-Datei hinzuzufügen. In der Contact Manager-Projektmappe enthält das Projekt ContactManager.Mvc beispielsweise eine parameters.xml-Datei im Stammordner.

Wenn Sie diese Datei öffnen, sehen Sie, dass sie einen einzelnen Parametereintrag enthält. Der Eintrag verwendet eine XPath-Abfrage (XML Path Language), um die Endpunkt-URL des ContactService-WCF-Diensts (Windows Communication Foundation) in der web.config-Datei zu suchen und zu parametrisieren.

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

Zusätzlich zur Parametrisierung der Endpunkt-URL im Bereitstellungspaket fügt der WPP der SetParameters.xml-Datei , die zusammen mit dem Bereitstellungspaket generiert wird, auch einen entsprechenden Eintrag hinzu.

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

Wenn Sie das Bereitstellungspaket manuell installieren, werden Sie vom IIS-Manager zur Eingabe der Dienstendpunktadresse zusammen mit den automatisch parametrisierten Eigenschaften aufgefordert. Wenn Sie das Bereitstellungspaket installieren, indem Sie die Datei .deploy.cmd ausführen, können Sie die dateiSetParameters.xml bearbeiten, um einen Wert für die Dienstendpunktadresse zusammen mit Werten für die automatisch parametrisierten Eigenschaften anzugeben.

Ausführliche Informationen zum Erstellen einer parameters.xml-Datei finden Sie unter Vorgehensweise: Verwenden von Parametern zum Konfigurieren von Bereitstellungseinstellungen bei Der Installation eines Pakets. Die Prozedur So verwenden Sie Bereitstellungsparameter für Web.config Dateieinstellungen , um schritt-für-Schritt-Anweisungen zu erhalten.

Ändern der SetParameters.xml-Datei

Wenn Sie das Webanwendungspaket manuell bereitstellen möchten – entweder durch Ausführen der Datei .deploy.cmd oder durch Ausführen von MSDeploy.exe über die Befehlszeile –, gibt es nichts, was Sie daran hindern kann, die SetParameters.xml-Datei vor der Bereitstellung manuell zu bearbeiten. Wenn Sie jedoch an einer Lösung auf Unternehmensebene arbeiten, müssen Sie möglicherweise ein Webanwendungspaket als Teil eines größeren, automatisierten Build- und Bereitstellungsprozesses bereitstellen. In diesem Szenario benötigen Sie die Microsoft-Build-Engine (MSBuild), um die SetParameters.xml-Datei für Sie zu ändern. Dazu können Sie die MSBuild-XmlPoke-Aufgabe verwenden.

Die Contact Manager-Beispiellösung veranschaulicht diesen Prozess. Die folgenden Codebeispiele wurden so bearbeitet, dass nur die Details angezeigt werden, die für dieses Beispiel relevant sind.

Hinweis

Eine umfassendere Übersicht über das Projektdateimodell in der Beispiellösung und eine Einführung in benutzerdefinierte Projektdateien im Allgemeinen finden Sie unter Grundlegendes zur Projektdatei und Grundlegendes zum Buildprozess.

Zunächst werden die relevanten Parameterwerte als Eigenschaften in der umgebungsspezifischen Projektdatei definiert (z. B. 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>

Hinweis

Eine Anleitung zum Anpassen der umgebungsspezifischen Projektdateien für Ihre eigenen Serverumgebungen finden Sie unter Konfigurieren von Bereitstellungseigenschaften für eine Zielumgebung.

Als Nächstes importiert die Datei Publish.proj diese Eigenschaften. Da jede SetParameters.xml Datei einer .deploy.cmd-Datei zugeordnet ist und die Projektdatei letztendlich jede .deploy.cmd-Datei aufrufen soll, erstellt die Projektdatei ein MSBuild-Element für jede .deploy.cmd-Datei und definiert die relevanten Eigenschaften als Elementmetadaten.

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

In diesem Fall:

• Der ParameterXml-Metadatenwert gibt den Speicherort der SetParameters.xml-Datei an.
• Der IisWebAppName-Wert ist der IIS-Pfad, zu dem Sie die Webanwendung bereitstellen möchten.
• Der Wert MembershipDBConnectionString ist die Verbindungszeichenfolge für die Mitgliedschaftsdatenbank, und der Wert MembershipDBConnectionName ist das name-Attribut des entsprechenden Parameters in der SetParameters.xml-Datei .
• Der Wert ServiceEndpointValue ist die Endpunktadresse für den WCF-Dienst auf dem Zielserver, und der Wert ServiceEndpointParamName ist das name-Attribut des entsprechenden Parameters in der SetParameters.xml-Datei .

Schließlich verwendet das PublishWebPackages-Ziel in der Datei Publish.proj die XmlPoke-Aufgabe, um diese Werte in der SetParameters.xml-Datei zu ändern.

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

Sie werden feststellen, dass jede XmlPoke-Aufgabe vier Attributwerte angibt:

• Das XmlInputPath-Attribut teilt der Aufgabe mit, wo die Datei zu finden ist, die Sie ändern möchten.
• Das Query-Attribut ist eine XPath-Abfrage, die den XML-Knoten identifiziert, den Sie ändern möchten.
• Das Value-Attribut ist der neue Wert, den Sie in den ausgewählten XML-Knoten einfügen möchten.
• Das Condition-Attribut ist das Kriterium, nach dem der Task ausgeführt werden soll oder nicht. In diesen Fällen stellt die Bedingung sicher, dass Sie nicht versuchen, einen NULL-Wert oder einen leeren Wert in die SetParameters.xml-Datei einzufügen.

Zusammenfassung

In diesem Thema wurde die Rolle der SetParameters.xml-Datei beschrieben und erläutert, wie sie beim Erstellen eines Webanwendungsprojekts generiert wird. Es wurde erläutert, wie Sie zusätzliche Einstellungen parametrisieren können, indem Sie Ihrem Projekt eine parameters.xml-Datei hinzufügen. Außerdem wurde beschrieben, wie Sie die SetParameters.xml-Datei im Rahmen eines größeren, automatisierten Buildprozesses ändern können, indem Sie den XmlPoke-Task in Ihren Projektdateien verwenden.

Im nächsten Thema, Bereitstellen von Webpaketen, wird beschrieben, wie Sie ein Webpaket entweder durch Ausführen der Datei .deploy.cmd oder direkt mit MSDeploy.exe-Befehlen bereitstellen können. In beiden Fällen können Sie Ihre SetParameters.xml-Datei als Bereitstellungsparameter angeben.

Weitere Informationen

Informationen zum Erstellen von Webpaketen finden Sie unter Erstellen und Verpacken von Webanwendungsprojekten. Eine Anleitung zum tatsächlichen Bereitstellen eines Webpakets finden Sie unter Bereitstellen von Webpaketen. Eine schrittweise exemplarische Vorgehensweise zum Erstellen einer parameters.xml-Datei finden Sie unter Vorgehensweise: Verwenden von Parametern zum Konfigurieren von Bereitstellungseinstellungen bei der Installation eines Pakets.

Weitere allgemeine Informationen zur Parametrisierung in Web Deploy finden Sie unter Web Deploy Parametrization in Action (Blogbeitrag).

ZurückWeiter