Visual Studio - 根據建置的組態設定自動轉換 Web.config 值

在開發系統時，為了不影響到現有的資料庫資料，我們通常會使用測試資料庫來測試系統，等到要正式上線的時候就要把資料庫連線改到正式資料庫。相信開發 .Net 應用程式的開發人員都知道，要連線資料庫最常用的方法就是把連線字串定義在 Web.config 的connectionStrings 區段裡，遇到上面述說的情況時，連線字串改來改去都會搞混了，最糟的情況就是造成上線的系統連到的卻是測試資料庫這種窘境。但是免驚，Visual Studio 提供一個可根據建置的祖態設定來自動轉換 Web.config 的內容值，今天限量就要來報給大家知。


在開啟 ASP.NET Web 專案後，不知道你有沒有發現，其實在 Web.config 底下藏了兩個檔案，如下：

這兩個檔案就是限量今天要講的重點。

這兩個檔案在 MSDN 裡稱作 Transform File，代表的意思是當我用哪個建置的組態建置專案時， Visual Studio 會去讀取那個建置組態的 Transform File 的設定看有沒有要替換原本的 Web.config。所以上面的 Debug 建置組態就會去讀取 Web.Deb.config，而如果我自己建立一個建置組態，那就會有 Web.<組態名稱>.config 的檔案。再來我們來看看這些設定檔裡面是什麼碗糕。

<?xml version="1.0" encoding="utf-8"?>

<!-- For more information on using web.config transformation visit http://go.microsoft.com/fwlink/?LinkId=125889 -->

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <!--
    In the example below, the "SetAttributes" transform will change the value of 
    "connectionString" to use "ReleaseSQLServer" only when the "Match" locator 
    finds an attribute "name" that has a value of "MyDB".
    
    <connectionStrings>
      <add name="MyDB" 
        connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True" 
        xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>
    </connectionStrings>
  -->
  <system.web>
    <!--
      In the example below, the "Replace" transform will replace the entire 
      <customErrors> section of your web.config file.
      Note that because there is only one customErrors section under the 
      <system.web> node, there is no need to use the "xdt:Locator" attribute.
      
      <customErrors defaultRedirect="GenericError.htm"
        mode="RemoteOnly" xdt:Transform="Replace">
        <error statusCode="500" redirect="InternalError.htm"/>
      </customErrors>
    -->
  </system.web>
</configuration>

內容裡有一些註解就是教你要怎麼玩這個東西。首先看看在最前面引入了 http://schemas.microsoft.com/XML-Document-Transform 的 Namespace，代表下面要用的是 Microsoft 定義的 XML Document Transform(XDT) 的格式。在玩之前要先了解兩個屬性，Locator 與 Transform，這兩個是 XDT 定義的屬性，只有在引入 XDT 的 Namespace 後才可以使用。使用方法就是在前面加入 xdt 的前綴詞，例如：xdt:Locator="" 或 xdt:Transform=""。

Locator

Locator 的作用是定義 XDT 如何在 Web.config 找到要改變的 Element。Locator 提供了3種方法如下：

Condition
語法：xdt:Locator="Condition(<XPath語法>)"
說明：Condition 表示的是一個結果為 True 或 False 的運算式，只要 Element 經過運算式運算的結果為 True，代表該 Element 符合。
範例：

xdt:Locator="Condition(@name='MyDbConnection' and @providerName='System.Data.SqlClient')"

解說：找目標 Element 的 name 屬性值為 "MyDbConnection" 且 providerName 屬性值為 "System.Data.SqlClient"。

Match
語法：xdt:Locator="Match(<屬性名稱1>, <屬性名稱2>, ...)"
說明：Math 的參數填入要符合的屬性名稱，當這些屬性的值全部符合才算找到。
範例：

<add name="MyDbConnection" connectionString="XXXXX" providerName="System.Data.SqlClient"
  xdt:Locator="Match(name, providerName)" />

解說：找目標 Element 的 name 為 "MyDbConnection" 且 providerName 為 "System.Data.SqlClient"，這個範例與上一個 Condition 的範例結果會是一樣的。

XPath
語法：xdt:Locaotr="XPath(<XPath語法>)" 說明：
說明：完全使用 XPath 的語法，從 XPath 的指定路徑搜尋符合條件的 Element。
範例：

xdt:Locator="XPath(/configuration/connectionStrings/add[@name='MyDbConnection' and @providerName='System.Data.SqlClient'])"

解說：找在 configuration/connectionStrings 路徑底下的 add Element，再看看 add Element 的 name 為 "MyDbConnection" 且 providerName 為 "System.Data.SqlClient"，這個範例與上述兩個範例結果是一樣的。

Transform

Transform 的作用是針對 Locator 找到的 Element 定義要進行什麼改變。Transform 提供了8種改變行為如下：

Replace

語法：xdt:Transform="Replace"

說明：將目前 Transform File 的 Element 取代符合的 Element。

Insert

語法：xdt:Transform="Insert"

說明：將目前 Transform File 的 Element 插入到符合的 Element 同層的最後面。

InsertBefore

語法：xdt:Transform="InsetBefore(<XPath>語法)"

說明：將目前 Transform File 的 Element 插入到 XPath 所指定搜尋到的 Element 前面。
範例：

<remove name="MyDbConnection"
 xdt:Transform="InsertBefore(/configuration/connectionStrings/add[@name='MyDbConnection'])"/>

解說：找在 configuration/connectionStrings 路徑底下的 add Element，再看看 add Element 的 name 為 "MyDbConnection"，找到後在它的前面加上 <remove name="MyDbConnection"> 的 Element。

InsertAfter

語法：xdt:Transform="InsertAfter(<XPath>語法)"

說明：將目前 Transform File 的 Element 插入到 XPath 所指定搜尋到的 Element 後面。
範例：類似 InsertBefore，差異在於插入在後面。

Remove

語法：xdt:Transform="Remove"

說明：刪除符合條件的 Element (符合條件的可能會有多個，但只刪除找到的第一個)

RemoveAll
語法：xdt:Transform="RemoveAll"

說明：刪除所有符合條件的 Element

RemoveAttributes

語法：xdt:Transform="RemoveAttributes(<屬性名稱1>, <屬性名稱2>, ...)"

說明：刪除指定的屬性值。

SetAttributes

語法：xdt:Transform="SetAttributes(<屬性名稱1>, <屬性名稱2>, ...)"

說明：設定指定的屬性值。

上面說明了 XDT 的使用方法，接下來下面限量用 XDT 來實現動態轉換資料庫連線資訊的範例：

我們會有一個原本的 Web.config 與動態替換 Web.config 值的 Web.Release.config 和 Web.Debug.config 如下：

Web.config

<configuration>
  <connectionStrings>
    <add name="MyDbConnection" connectionString="" providerName="" />
  </connectionStrings>
</configuration>

Web.Release.config

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <connectionStrings>
    <remove name="LocalServer" xdt:Transform="InsertBefore(/configuration/connectionStrings/add)" />
    <add name="MyDbConnection" connectionString="正式DB" providerName="System.Data.OracleClient"
         xdt:Transform="Replace" xdt:Locator="Condition(@name='MyDbConnection')" />
  </connectionStrings>
</configuration>

Web.Debug.config

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <connectionStrings>
    <add name="MyDbConnection" connectionString="測試DB" providerName="System.Data.SqlClient"
         xdt:Transform="Replace" xdt:Locator="Condition(@name='MyDbConnection')" />
  </connectionStrings>
</configuration>

範例說明：
在 Release 的組態中，我們希望能夠連接正式的資料庫，且資料庫為 Oracle，並且將 LocalServer 的資料庫連線移除掉。
在 Debug 的組態中，我們希望連線測試的資料庫，資料庫為 MS SQL Server。
透過不同組態的發佈可以得到不同的資料庫連線設定。

執行結果：
Case1(以 Release 組態發佈) Web.config

<configuration>
  <connectionStrings>
    <remove name="LocalServer" />
    <add name="MyDbConnection" connectionString="正式DB" providerName="System.Data.OracleClient" />
  </connectionStrings>
</configuration>

Case2(以 Debug 組態發佈) Web.config

<configuration>
  <connectionStrings>
    <add name="MyDbConnection" connectionString="測試DB" providerName="System.Data.SqlClient" />
  </connectionStrings>
</configuration>

這篇蓋步大概就這樣了，另外提一點，目前這個功能內建只有在 ASP.NET Web Application的 Web.config 才能使用(不管是 Web Form 或 MVC)，但是如果你也想在一般的 App.config 使用這個功能，那你可以到這邊 Visual Studio Marketplace - Configuration Transform 安裝VS的擴充套件，就可以使用相同的功能了。



參考來源：
MSDN - Web.config Transformation Syntax for Web Project Deployment Using Visual Studio
Visual Studio Marketplace - Configuration Transform