Share via

Sintassi di trasformazione di Web.config per la distribuzione di un progetto di applicazione Web

  • Articolo

I file Web.config includono in genere impostazioni che devono differire in base all'ambiente in cui l'applicazione è in esecuzione. Ad esempio, potrebbe essere necessario modificare una stringa di connessione al database o disabilitare il debug quando si distribuisce un file Web.config. Per progetti di applicazione Web, ASP.NET fornisce strumenti che automatizzano il processo di modifica (trasformazione) dei file Web.config quando vengono distribuiti. Per ogni ambiente in cui si desidera effettuare la distribuzione viene creato un file di trasformazione che specifica solo le differenze tra il file Web.config originale e quello distribuito per tale ambiente.

Un file di trasformazione è un file XML in cui sono specificate quali modifiche devono essere apportate al file Web.config durante la distribuzione. Le azioni della trasformazione vengono specificate tramite attributi XML definiti dello spazio dei nomi XML-Document-Transform, mappato al prefisso xdt. Lo spazio dei nomi XML-Document-Transform definisce i due attributi Locator e Transform. L'attributo Locator specifica l'elemento o il set di elementi del file Web.config che si desidera modificare. L'attributo Transform specifica la modifica da apportare agli elementi individuati dall'attributo Locator.

Nell'esempio seguente viene mostrato il contenuto di un file di trasformazione che modifica una stringa di connessione e sostituisce l'elemento customErrors:

<?xml version="1.0"?>
<configuration xmlns:xdt="https://schemas.microsoft.com/XML-Document-Transform">
  <connectionStrings>
    <add name="MyDB" 
      connectionString="value for the deployed Web.config file" 
      xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>
  </connectionStrings>
  <system.web>
    <customErrors defaultRedirect="GenericError.htm"
      mode="RemoteOnly" xdt:Transform="Replace">
      <error statusCode="500" redirect="InternalError.htm"/>
    </customErrors>
  </system.web>
</configuration>

L'elemento radice di un file di trasformazione deve specificare lo spazio dei nomi XML-Document-Transform nel tag di apertura, come mostrato nell'esempio precedente. Gli elementi Locator e Transform non vengono riprodotti nel file Web.config distribuito.

Nelle sezioni seguenti vengono fornite le informazioni di riferimento sulla sintassi da utilizzare nei file di trasformazione.

Sintassi dell'attributo Locator

In ognuna delle sezioni seguenti viene illustrata la sintassi per un attributo Locator.

Condizione

Specifica un'espressione XPath aggiunta all'espressione XPath dell'elemento corrente. Gli elementi che corrispondono all'espressione XPath combinata vengono selezionati.

Sintassi

Locator="Condition(XPath expression)"

Esempio

Nell'esempio seguente viene illustrato come selezionare elementi della stringa di connessione il cui valore dell'attributo name è oldname o un attributo providerName il cui valore è oldprovider. Nel file Web.config distribuito gli elementi selezionati vengono sostituiti con l'elemento specificato nel file di trasformazione.

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add name="AWLT" connectionString="newstring"
       providerName="newprovider"
       xdt:Transform="Replace" 
       xdt:Locator="Condition(@name='oldname'
         or @providerName='oldprovider')" />
  </connectionStrings>
</configuration>

L'espressione XPath effettiva applicata al file Web.config di sviluppo come risultato dell'espressione Condition specificata è la seguente:

configuration/connectionStrings[@name='AWLT' or @providerName='System.Data.SqlClient']

Questa espressione è il risultato della combinazione della condizione XPath implicita per l'elemento corrente (configuration/connectionStrings) con l'espressione specificata in modo esplicito.

Match

Seleziona l'elemento o gli elementi che dispongono di un valore corrispondente per l'attributo o gli attributi specificati. Se vengono specificati più nomi di attributo, vengono selezionati solo gli elementi che corrispondono a tutti gli attributi specificati.

Sintassi

Locator="Match(comma-delimited list of one or more attribute names)"

Esempio

Nell'esempio seguente viene illustrato come selezionare l'elemento add della stringa di connessione con il valore AWLT nell'attributo name nel file Web.config di sviluppo. Nel file Web.config distribuito l'elemento selezionato viene sostituito con l'elemento add specificato nel file di trasformazione.

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add name="AWLT" connectionString="newstring"
       providerName="newprovider"
       xdt:Transform="Replace" 
       xdt:Locator="Match(name)" />
  </connectionStrings>
</configuration>

XPath

Specifica un'espressione XPath assoluta applicata al file Web.config di sviluppo. A differenza di Condition, l'espressione specificata non viene aggiunta all'espressione XPath implicita che corrisponde all'elemento corrente.

Sintassi

Locator="XPath(XPath expression)"

Esempio

Nell'esempio seguente viene illustrato come selezionare gli stessi elementi selezionati nell'esempio precedente per la parola chiave Condition.

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add name="AWLT" connectionString="newstring"
       providerName="newprovider"
       xdt:Transform="Replace" 
       xdt:Locator="XPath(configuration/connectionStrings[@name='AWLT'
         or @providerName='System.Data.SqlClient'])" />
  </connectionStrings>
</configuration>

Sintassi dell'attributo Transform

In ognuna delle sezioni seguenti viene illustrata la sintassi per un attributo Transform.

Sostituire

Sostituisce l'elemento selezionato con l'elemento specificato nel file di trasformazione. Se vengono selezionati più elementi, viene sostituito solo il primo. Per un esempio di utilizzo della parola chiave Replace, vedere gli esempi relativi agli attributi Locator.

Sintassi

Transform="Replace"

Insert

Aggiunge l'elemento definito nel file di trasformazione come elemento di pari livello all'elemento o agli elementi selezionati. Il nuovo elemento viene aggiunto alla fine di un eventuale insieme.

Sintassi

Transform="Insert"

Esempio

Nell'esempio seguente viene illustrato come selezionare tutte le stringhe di connessione nel file Web.config di sviluppo. Nel file Web.config distribuito la stringa di connessione specificata viene aggiunta alla fine dell'insieme.

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add name="AWLT" connectionString="newstring"
       providerName="newprovider"
       xdt:Transform="Insert" />
  </connectionStrings>
</configuration>

InsertBefore

Inserisce l'elemento definito nell'XML della trasformazione appena prima dell'elemento selezionato dall'espressione XPath specificata. L'espressione XPath deve essere un'espressione assoluta, perché viene applicata al file Web.config di sviluppo nel suo complesso, non viene aggiunta solo all'espressione XPath implicita dell'elemento corrente.

Sintassi

Transform="InsertBefore(XPath expression)"

Esempio

Nell'esempio seguente viene illustrato come selezionare l'elemento deny che nega l'accesso a tutti gli utenti, quindi inserire prima di esso un elemento allow che concede l'accesso agli amministratori.

<configuration xmlns:xdt="...">
  <authorization>
    <allow roles="Admins"
      xdt:Transform="InsertBefore(/configuration/system.web/authorization/deny[@users='*'])" />
  </authorization>
</configuration>

InsertAfter

Inserisce l'elemento definito nell'XML della trasformazione appena dopo l'elemento selezionato dall'espressione XPath specificata. L'espressione XPath deve essere un'espressione assoluta, perché viene applicata al file Web.config di sviluppo nel suo complesso, non viene aggiunta all'espressione XPath implicita dell'elemento corrente.

Sintassi

Transform="InsertAfter(XPath expression)"

Esempio

Nell'esempio seguente viene illustrato come selezionare l'elemento allow che concede l'accesso agli amministratori, quindi inserire dopo di esso un elemento deny che nega l'accesso a un utente specificato.

<configuration xmlns:xdt="...">
  <authorization>
    <deny users="UserName"
      xdt:Transform="InsertAfter
        (/configuration/system.web/authorization/allow[@roles='Admins'])" />
  </authorization>
</configuration>

Remove

Rimuove l'elemento selezionato. Se vengono selezionati più elementi, rimuove il primo elemento.

Sintassi

Transform="Remove"

Esempio

Nell'esempio seguente viene illustrato come selezionare tutti gli elementi add della stringa di connessione nel file Web.config di sviluppo. Nel file Web.config distribuito viene rimosso solo il primo elemento della stringa di connessione.

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add xdt:Transform="Remove" />
  </connectionStrings>
</configuration>

RemoveAll

Rimuove l'elemento o gli elementi selezionati.

Sintassi

Transform="RemoveAll"

Esempio

Nell'esempio seguente viene illustrato come selezionare tutte le stringhe di connessione nel file Web.config di sviluppo. Nel file Web.config distribuito verranno rimossi tutti gli elementi.

<configuration xmlns:xdt="...">
  <connectionStrings>
    <add xdt:Transform="RemoveAll" />
  </connectionStrings>
</configuration>

RemoveAttributes

Rimuove gli attributi specificati dagli elementi selezionati.

Sintassi

Transform="RemoveAttributes(comma-delimited list of one or more attribute names)"

Esempio

Nell'esempio seguente viene illustrato come selezionare tutti gli elementi compilation nel file Web.config di sviluppo. Poiché il file di configurazione può contenere un solo elemento compilation, non è necessario specificare un attributo Locator. Nel file Web.config distribuito gli attributi debug e batch vengono rimossi dall'elemento compilation.

<configuration xmlns:xdt="...">
  <compilation 
    xdt:Transform="RemoveAttributes(debug,batch)">
  </compilation>
</configuration>

SetAttributes

Imposta gli attributi per gli elementi selezionati sui valori specificati. L'attributo di trasformazione Replace sostituisce un intero elemento, inclusi tutti i relativi attributi. L'attributo SetAttributes consente invece di lasciare l'elemento invariato modificandone gli attributi selezionati.

Sintassi

Transform="SetAttributes(comma-delimited list of one or more attribute names)"

Esempio

Nell'esempio seguente viene illustrato come selezionare tutti gli elementi compilation nel file Web.config di sviluppo. Poiché il file di configurazione può contenere un solo elemento compilation, non è necessario specificare un attributo Locator. Nel file Web.config distribuito il valore dell'attributo batch dell'elemento compilation è impostato su false.

<configuration xmlns:xdt="...">
  <compilation 
    batch="false"
    xdt:Transform="SetAttributes(batch)">
  </compilation>
</configuration>

Omissione degli attributi Locator

Gli attributi Locator sono facoltativi. Se non si specifica un attributo Locator, l'elemento da modificare viene specificato in modo implicito dall'elemento per il quale viene specificato l'attributo Transform. Nell'esempio seguente viene sostituito l'intero elemento system.web, in quanto non è stato specificato alcun attributo Locator.

<?xml version="1.0"?>
<configuration xmlns:xdt="https://schemas.microsoft.com/XML-Document-Transform">
  <system.web xdt:Transform="Replace">
    <customErrors defaultRedirect="GenericError.htm"
      mode="RemoteOnly">
      <error statusCode="500" redirect="InternalError.htm"/>
    </customErrors>
  </system.web>
</configuration>

Utilizzo di attributi Transform e Locator su elementi distinti

Non è necessario impostare un attributo Transform nello stesso elemento di un elemento Locator. È possibile specificare un elemento Locator in un elemento padre per selezionare gli elementi i cui elementi figlio si desidera utilizzare. È possibile specificare quindi un attributo Transform in un elemento figlio per applicarvi una modifica.

Nell'esempio seguente viene illustrato come utilizzare l'attributo Locator per selezionare gli elementi location per il percorso specificato. Tuttavia, solo gli elementi figlio degli elementi location selezionati verranno trasformati.

<configuration xmlns:xdt="...">
  <location path="C:\MySite\Admin" xdt:Locator="Match(path)"> 
    <system.web>
      <pages viewStateEncryptionMode="Always"
        xdt:Transform="SetAttributes(viewStateEncryptionMode)" />
    </system.web> 
  </location> 
</configuration>

Se si specifica un attributo Locator, ma non si specifica un attributo Transform nello stesso elemento o in un elemento figlio, non vengono apportate modifiche.

Nota

Un attributo Transform per un elemento padre può influire sugli elementi figlio anche se per questi non è specificato alcun elemento Transform.Se ad esempio si inserisce l'attributo xdt:Transform="Replace" nell'elemento system.web, tutti gli elementi figlio dell'elemento system.web vengono sostituiti con il contenuto del file di trasformazione.

Vedere anche

Concetti

Cenni preliminari sulla distribuzione del progetto di applicazione Web ASP.NET

Procedura dettagliata: distribuzione di un progetto di applicazione Web utilizzando un pacchetto di distribuzione Web (parte 1 di 4)

Cronologia delle modifiche

Data

Cronologia

Motivo

Maggio 2011

Corretta la spiegazione del funzionamento della trasformazione di sostituzione.

Commenti e suggerimenti dei clienti.