Konfigurieren von Parametern für die Webpaketbereitstellung

von Jason Lee

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

Wenn Sie ein Webanwendungsprojekt erstellen, generiert der Build- und Paketprozess 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 (MSDeploy.exe) Befehle, die Ihr Webbereitstellungspaket auf einem Remote-IIS-Webserver veröffentlichen.
• Eine [Projektname].SetParameters.xml Datei. Dies stellt einen Satz von Parameterwerten für den befehl MSDeploy.exe bereit. Sie können die Werte in dieser Datei aktualisieren und an Web Deploy als Befehlszeilenparameter übergeben, wenn Sie Ihr Webpaket bereitstellen.

Die SetParameters.xml-Datei wird dynamisch aus der Webanwendungsprojektdatei und allen Konfigurationsdateien in Ihrem Projekt generiert. Wenn Sie Ihr Projekt erstellen und verpacken, 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 Web-Bereitstellungspaket parametrisiert und zur SetParameters.xml-Datei hinzugefügt. Wenn Sie beispielsweise der web.config-Datei in Ihrem Webanwendungsprojekt eine Verbindungszeichenfolge hinzufügen, erkennt der Buildvorgang diese Änderung und fügt der SetParameters.xml Datei entsprechend einen Eintrag hinzu.

In einigen Fällen reicht diese automatische Parametrisierung aus. Wenn Ihre Benutzer jedoch andere Einstellungen zwischen Bereitstellungsumgebungen wie Anwendungseinstellungen oder Dienstendpunkt-URLs variieren müssen, müssen Sie das WPP anweisen, diese Werte im Bereitstellungspaket zu parametrisieren und der SetParameters.xml Datei entsprechende Einträge hinzuzufügen. In den folgenden Abschnitten wird die Vorgehensweise erläutert.

Automatische Parametrisierung

Wenn Sie eine Webanwendung erstellen und verpacken, wird das WPP diese Dinge automatisch parametrisieren:

• Der IIS-Zielwebanwendungspfad und -name.
• Alle Verbindungszeichenfolgen in Ihrer web.config Datei.
• Verbindungszeichenfolgen für alle Datenbanken, die Sie der Registerkarte " Sql packen/veröffentlichen " auf den Projekteigenschaftenseiten hinzufügen.

Wenn Sie beispielsweise die Contact Manager-Beispiellösung erstellen und verpacken würden, ohne den Parameterisierungsprozess auf irgendeine Weise zu berühren, würde das 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 Package/Publish Web auf den Eigenschaften-Seiten des Projekts übernommen.
• Der Parameter ApplicationServices-Web.config Connection String wurde aus einem connectionStrings/add-Element in der Datei web.config generiert. Sie stellt die Verbindungszeichenfolge dar, die von der Anwendung zum Kontaktieren der Mitgliedschaftsdatenbank verwendet werden soll. Der hier bereitgestellte Wert wird durch die bereitgestellte web.config Datei ersetzt. Der Standardwert stammt aus der Datei vor der Bereitstellung web.config .

Das 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 in der manuellen Installation von Webpaketen beschrieben, werden Sie vom Installations-Assistenten aufgefordert, Werte für alle Parameter anzugeben. Wenn Sie das Paket remote mithilfe der .deploy.cmd-Datei installieren, wie in der Bereitstellung von Webpaketen beschrieben, sucht Web Deploy in dieser SetParameters.xml Datei, um die Parameterwerte bereitzustellen. Sie können die Werte in der SetParameters.xml Datei manuell bearbeiten, oder Sie können die Datei als Teil eines automatisierten Build- und Bereitstellungsprozesses anpassen. Dieser Vorgang wird weiter unten in diesem Thema ausführlicher beschrieben.

Benutzerdefinierte Parameterisierung

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 zwischen Zielumgebungen variieren. Folgende sind möglich:

• Dienstendpunkte in der web.config-Datei .
• Anwendungseinstellungen in der Datei web.config.
• Alle anderen deklarativen Eigenschaften, die Sie Benutzer zur Angabe auffordern möchten.

Am einfachsten können Sie diese Eigenschaften parametrisieren, indem Sie dem Stammordner Ihres Webanwendungsprojekts eine parameters.xml Datei hinzufügen. Beispielsweise enthält das Projekt ContactManager.Mvc in der Contact Manager-Projektmappe eine parameters.xml Datei im Stammordner.

Wenn Sie diese Datei öffnen, sehen Sie, dass sie einen einzelnen Parametereintrag enthält. Der Eintrag verwendet eine XML Path Language (XPath)-Abfrage, um die Endpunkt-URL des ContactService Windows Communication Foundation (WCF)-Diensts 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>

Neben der Parameterisierung der Endpunkt-URL im Bereitstellungspaket fügt das WPP auch einen entsprechenden Eintrag zur SetParameters.xml Datei hinzu, die zusammen mit dem Bereitstellungspaket generiert wird.

<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 Endpunktadresse des Dienstes aufgefordert, zusammen mit den Eigenschaften, die automatisch parametrisiert wurden. Wenn Sie das Bereitstellungspaket installieren, indem Sie die datei .deploy.cmd ausführen, können Sie die SetParameters.xml-Datei bearbeiten, um einen Wert für die Dienstendpunktadresse zusammen mit Werten für die Eigenschaften bereitzustellen, die automatisch parametrisiert wurden.

Ausführliche Informationen zum Erstellen einer parameters.xml-Datei finden Sie unter So verwenden Sie Parameter zur Konfiguration von Bereitstellungseinstellungen während der Installation eines Pakets. Das Verfahren namens "So verwenden Sie Bereitstellungsparameter für Web.config Dateieinstellungen " enthält schrittweise Anleitungen.

Ändern der SetParameters.xml Datei

Wenn Sie das Webanwendungspaket manuell bereitstellen möchten – entweder durch Ausführen der .deploy.cmd-Datei oder durch Ausführen von MSDeploy.exe über die Befehlszeile – gibt es nichts, das manuelle Bearbeiten der SetParameters.xml-Datei vor der Bereitstellung zu beenden. Wenn Sie jedoch an einer Unternehmenslösung arbeiten, müssen Sie möglicherweise ein Webanwendungspaket als Teil eines größeren, automatisierten Build- und Bereitstellungsprozesses bereitstellen. In diesem Szenario benötigen Sie das 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 bearbeitet, um nur die Details anzuzeigen, die für dieses Beispiel relevant sind.

Zunächst werden die von Interesse bezogenen 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>

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 Eigenschaften von Interesse 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 Namensattribute des entsprechenden Parameters in der SetParameters.xml Datei.
• Der Wert ServiceEndpointValue ist die Endpunktadresse für den WCF-Dienst auf dem Zielserver, und der ServiceEndpointParamName-Wert ist das Namensattribute des entsprechenden Parameters in der SetParameters.xml Datei.

Schließlich verwendet das Ziel PublishWebPackages in der Datei Publish.proj die Aufgabe XmlPoke, um diese Werte in der Datei SetParameters.xml 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 gefunden werden soll, 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 die Aufgabe ausgeführt werden soll oder nicht. In diesen Fällen stellt die Bedingung sicher, dass Sie nicht versuchen, einen Null- oder leeren Wert in die SetParameters.xml Datei einzufügen.

Fazit

In diesem Thema wird 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 als Teil eines größeren, automatisierten Buildprozesses mithilfe der XmlPoke-Aufgabe in Ihren Projektdateien ändern können.

Im nächsten Thema, Bereitstellen von Webpaketen, wird beschrieben, wie Sie ein Webpaket bereitstellen können, indem Sie die .deploy.cmd Datei ausführen oder MSDeploy.exe Befehle direkt verwenden. In beiden Fällen können Sie Ihre SetParameters.xml Datei als Bereitstellungsparameter angeben.

Weiterführende Lektüre

Informationen zum Erstellen von Webpaketen finden Sie unter Building and Packaging Web Application Projects. Anleitungen zum Tatsächlichen Bereitstellen eines Webpakets finden Sie unter Bereitstellen von Webpaketen. Für eine schrittweise Anleitung zum Erstellen einer parameters.xml-Datei siehe So verwenden Sie Parameter zur Konfiguration der Bereitstellungseinstellungen bei der Installation eines Pakets.

Allgemeine Informationen zur Parametrisierung in Web Deploy finden Sie unter Web Deploy Parameterization in Action (Blogbeitrag).