Configurazione dei parametri per la distribuzione di pacchetti Web

di Jason Lee

In questo argomento viene descritto come impostare i valori dei parametri, ad esempio i nomi delle applicazioni Web di Internet Information Services (IIS), le stringhe di connessione e gli endpoint di servizio, quando si distribuisce un pacchetto Web in un server Web IIS remoto.

Quando si compila un progetto di applicazione Web, il processo di compilazione e creazione di pacchetti genera tre file chiave:

• Un file [nome progetto].zip . Si tratta del pacchetto di distribuzione Web per il progetto di applicazione Web. Questo pacchetto contiene tutti gli assembly, i file, gli script di database e le risorse necessari per ricreare l'applicazione Web in un server Web IIS remoto.
• File [nome progetto].deploy.cmd . Contiene un set di comandi di distribuzione Web con parametri (MSDeploy.exe) che pubblicano il pacchetto di distribuzione Web in un server Web IIS remoto.
• Un file [nome progetto].SetParameters.xml . In questo modo viene fornito un set di valori di parametro al comando MSDeploy.exe. È possibile aggiornare i valori in questo file e passarlo a Distribuzione Web come parametro della riga di comando quando si distribuisce il pacchetto Web.

Il fileSetParameters.xml viene generato dinamicamente dal file di progetto dell'applicazione Web e da eventuali file di configurazione all'interno del progetto. Quando si compila e si crea un pacchetto del progetto, la pipeline di pubblicazione Web rileva automaticamente molte delle variabili che probabilmente cambiano tra gli ambienti di distribuzione, ad esempio l'applicazione Web IIS di destinazione e tutte le stringhe di connessione del database. Questi valori vengono parametrizzati automaticamente nel pacchetto di distribuzione Web e aggiunti al file diSetParameters.xml . Ad esempio, se si aggiunge una stringa di connessione al file web.config nel progetto dell'applicazione Web, il processo di compilazione rileverà questa modifica e aggiungerà una voce al file SetParameters.xml di conseguenza.

In molti casi, questa parametrizzazione automatica sarà sufficiente. Tuttavia, se gli utenti devono variare altre impostazioni tra gli ambienti di distribuzione, ad esempio le impostazioni dell'applicazione o gli URL degli endpoint di servizio, è necessario indicare al WPP di parametrizzare questi valori nel pacchetto di distribuzione e aggiungere voci corrispondenti al file diSetParameters.xml . Le sezioni seguenti illustrano come eseguire questa operazione.

Parametrizzazione automatica

Quando si compila e crea un pacchetto di un'applicazione Web, il WPP parametrizza automaticamente questi elementi:

• Percorso e nome dell'applicazione Web IIS di destinazione.
• Qualsiasi stringa di connessione nel file diweb.config .
• Stringhe di connessione per tutti i database aggiunti alla scheda Pacchetto/Pubblica SQL nelle pagine delle proprietà del progetto.

Ad esempio, se si desidera compilare e creare un pacchetto della soluzione di esempio Contact Manager senza toccare il processo di parametrizzazione in alcun modo, il WPP genererà questo file 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>

In questo caso:

• Il parametro Nome applicazione Web IIS è il percorso IIS in cui si vuole distribuire l'applicazione Web. Il valore predefinito viene ricavato dalla pagina Web Package/Publish nelle pagine delle proprietà del progetto.
• Il ApplicationServices-Web.config parametro Connection String è stato generato da un elemento connectionStrings/add nel file web.config . Rappresenta la stringa di connessione che l'applicazione deve usare per contattare il database di appartenenza. Il valore specificato qui verrà sostituito nel file diweb.config distribuito. Il valore predefinito viene ricavato dal file web.config pre-distribuzione.

Il WPP parametrizza anche queste proprietà nel pacchetto di distribuzione generato. È possibile fornire valori per queste proprietà quando si installa il pacchetto di distribuzione. Se si installa manualmente il pacchetto tramite Gestione IIS, come descritto in Installazione manuale di pacchetti Web, l'installazione guidata richiede di specificare i valori per tutti i parametri. Se si installa il pacchetto in modalità remota usando il file .deploy.cmd , come descritto in Distribuzione di pacchetti Web, Distribuzione Web cercherà questo fileSetParameters.xml per fornire i valori dei parametri. È possibile modificare i valori nel file SetParameters.xml manualmente oppure personalizzare il file come parte di un processo di compilazione e distribuzione automatizzato. Questo processo viene descritto in modo più dettagliato più avanti in questo argomento.

Parametrizzazione personalizzata

Negli scenari di distribuzione più complessi è spesso necessario parametrizzare proprietà aggiuntive prima di distribuire il progetto. In generale, è consigliabile parametrizzare le proprietà e le impostazioni che variano tra gli ambienti di destinazione. Possono includere:

• Endpoint di servizio nel file web.config .
• Impostazioni dell'applicazione nel file web.config .
• Tutte le altre proprietà dichiarative che si desidera richiedere agli utenti di specificare.

Il modo più semplice per parametrizzare queste proprietà consiste nell'aggiungere un fileparameters.xml alla cartella radice del progetto dell'applicazione Web. Nella soluzione Contact Manager, ad esempio, il progetto ContactManager.Mvc include un fileparameters.xml nella cartella radice.

Se si apre questo file, si noterà che contiene una singola voce di parametro . La voce usa una query XPath (XML Path Language) per individuare e parametrizzare l'URL dell'endpoint del servizio ContactService Windows Communication Foundation (WCF) nel file 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>

Oltre a parametrizzare l'URL dell'endpoint nel pacchetto di distribuzione, il WPP aggiunge anche una voce corrispondente al file SetParameters.xml che viene generato insieme al pacchetto di distribuzione.

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

Se si installa manualmente il pacchetto di distribuzione, Gestione di IIS richiederà l'indirizzo dell'endpoint del servizio insieme alle proprietà che sono state parametrizzate automaticamente. Se si installa il pacchetto di distribuzione eseguendo il file .deploy.cmd, è possibile modificare il file SetParameters.xml in modo da fornire un valore per l'indirizzo dell'endpoint di servizio e i valori per le proprietà che sono state parametrizzate automaticamente.

Per informazioni dettagliate su come creare un file diparameters.xml , vedere Procedura: Usare i parametri per configurare le impostazioni di distribuzione quando viene installato un pacchetto. La procedura denominata Per utilizzare i parametri di distribuzione nelle impostazioni del file Web.config fornisce istruzioni dettagliate.

Modifica del file di SetParameters.xml

Se si prevede di distribuire manualmente il pacchetto dell'applicazione Web, eseguendo il file .deploy.cmd o eseguendo MSDeploy.exe dalla riga di comando, non è necessario interrompere la modifica manuale del file SetParameters.xml prima della distribuzione. Tuttavia, se si lavora a una soluzione su scala aziendale, potrebbe essere necessario distribuire un pacchetto di applicazione Web come parte di un processo di compilazione e distribuzione più ampio e automatizzato. In questo scenario è necessario Microsoft Build Engine (MSBuild) per modificare il file SetParameters.xml. A tale scopo, è possibile usare l'attività MSBuild XmlPoke .

La soluzione di esempio Contact Manager illustra questo processo. Gli esempi di codice che seguono sono stati modificati per visualizzare solo i dettagli rilevanti per questo esempio.

Prima di tutto, i valori dei parametri di interesse vengono definiti come proprietà nel file di progetto specifico dell'ambiente, ad esempio 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>

Il file Publish.proj importa quindi queste proprietà. Poiché ogni SetParameters.xml file è associato a un file .deploy.cmd e si vuole che il file di progetto richiami ogni file .deploy.cmd , il file di progetto crea un elemento MSBuild per ogni file .deploy.cmd e definisce le proprietà di interesse come metadati dell'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>

In questo caso:

• Il valore dei metadati ParametersXml indica il percorso del file SetParameters.xml .
• Il valore IisWebAppName è il percorso IIS a cui si vuole distribuire l'applicazione Web.
• Il valore MembershipDBConnectionString è la stringa di connessione per il database di appartenenza e il valore MembershipDBConnectionName è l'attributo name del parametro corrispondente nel file SetParameters.xml .
• Il valore ServiceEndpointValue è l'indirizzo dell'endpoint per il servizio WCF nel server di destinazione e il valore ServiceEndpointParamName è l'attributo name del parametro corrispondente nel file SetParameters.xml .

Infine, nel file Publish.proj , la destinazione PublishWebPackages usa l'attività XmlPoke per modificare questi valori nel file 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>

Si noterà che ogni attività XmlPoke specifica quattro valori di attributo:

• L'attributo XmlInputPath indica all'attività dove trovare il file da modificare.
• L'attributo Query è una query XPath che identifica il nodo XML da modificare.
• L'attributo Value è il nuovo valore da inserire nel nodo XML selezionato.
• L'attributo Condition è il criterio in base al quale l'attività deve essere eseguita o meno. In questi casi, la condizione garantisce che non si tenti di inserire un valore Null o vuoto nel file SetParameters.xml .

Conclusione

In questo argomento è stato descritto il ruolo del file SetParameters.xml e viene illustrato come viene generato quando si compila un progetto di applicazione Web. È stato illustrato come è possibile parametrizzare impostazioni aggiuntive aggiungendo un fileparameters.xml al progetto. Descrive anche come modificare il fileSetParameters.xml come parte di un processo di compilazione automatizzato di dimensioni maggiori, usando l'attività XmlPoke nei file di progetto.

Nell'argomento successivo, Distribuzione di pacchetti Web, viene descritto come distribuire un pacchetto Web eseguendo il file .deploy.cmd o usando direttamente i comandi MSDeploy.exe. In entrambi i casi, è possibile specificare il file SetParameters.xml come parametro di distribuzione.

Altre informazioni

Per informazioni su come creare pacchetti Web, vedere Compilazione e creazione di pacchetti di progetti di applicazioni Web. Per indicazioni su come distribuire effettivamente un pacchetto Web, vedere Distribuzione di pacchetti Web. Per una procedura dettagliata su come creare un fileparameters.xml , vedere Procedura: Usare i parametri per configurare le impostazioni di distribuzione quando viene installato un pacchetto.

Per informazioni più generali sulla parametrizzazione in Web Deploy, vedere Web Deploy Parameterization in Action (post sul blog "Parametrizzazione in azione").