使用 Visual Studio ASP.NET Web 部署:Web.config檔案轉換
By Tom Dykstra
本教學課程系列說明如何使用 Visual Studio 2012 或 Visual Studio 2010,將 (發佈) ASP.NET Web 應用程式部署至Azure App 服務 Web Apps或協力廠商裝載提供者。 如需系列的相關資訊,請參閱 系列的第一個教學課程。
概觀
本教學課程說明如何在您將Web.config檔案部署到不同的目的地環境時,將變更 Web.config 檔案的程式自動化。 大部分的應用程式在部署應用程式時, Web.config 檔案中的設定必須不同。 自動化進行這些變更的程式,可讓您不必在每次部署時手動執行這些變更,這很繁瑣且容易出錯。
提醒:如果您在完成教學課程時收到錯誤訊息或某些專案無法運作,請務必檢查 疑難排解頁面。
Web.config轉換與 Web Deploy 參數
有兩種方式可將變更 Web.config 檔案設定的程式自動化: Web.config轉換 和 Web Deploy 參數。 Web.config轉換檔包含 XML 標記,指定如何在部署時變更Web.config檔案。 您可以指定特定組建組態和特定發行設定檔的不同變更。 預設組建組態為 [偵錯] 和 [發行],您可以建立自訂群組建組態。 發佈設定檔通常會對應至目的地環境。 (您將深入瞭解 部署至 IIS 作為測試環境 教學課程中的發佈設定檔。)
Web Deploy 參數可用來指定部署期間必須設定的許多不同種類的設定,包括 Web.config 檔案中找到的設定。 當用來指定 Web.config 檔案變更時,Web Deploy 參數會比較複雜,但在部署之前,您不知道要設定的值時會很有用。 例如,在企業環境中,您可能會建立 部署套件 ,並將它提供給 IT 部門中的人員在生產環境中安裝,而且該人員必須能夠輸入您不知道的連接字串或密碼。
針對本教學課程系列涵蓋的案例,您事先知道必須對 Web.config 檔案執行的所有動作,因此您不需要使用 Web Deploy 參數。 您將根據使用的組建組態來設定一些不同轉換,而有些轉換會根據所使用的發行設定檔而有所不同。
在 Azure 中指定Web.config設定
如果您想要變更的Web.config檔案設定位於 <connectionStrings>
或 <appSettings>
元素中,而且您要部署至 Azure App 服務 中的 Web Apps,則有另一個選項可在部署期間自動變更。 您可以在 Web 應用程式的 [管理入口網站] 頁面的 [設定] 索引卷標中,輸入您想要在 Azure 中生效的設定, (向下捲動至應用程式設定和連接字串區段) 。 當您部署專案時,Azure 會自動套用變更。 如需詳細資訊,請參閱 Windows Azure 網站:應用程式字串和連接字串的運作方式。
預設轉換檔案
在方案總管中,展開[Web.config],以查看兩個預設建置組態預設所建立的Web.Debug.config和Web.Release.config轉換檔案。
您可以用滑鼠右鍵按一下Web.config檔案,然後選擇操作功能表中的 [ 新增組態轉換 ],以建立自訂群組建組態的轉換檔案。 在本教學課程中,您不需要這麼做,而且功能表選項已停用,因為您尚未建立任何自訂群組建組態。
稍後您將建立三個轉換檔案,分別用於測試、預備和生產發行設定檔。 您在發行設定檔轉換檔案中處理之設定的一般範例,因為它取決於目的地環境是測試與生產環境不同的 WCF 端點。 建立發行設定檔之後,您將在稍後的教學課程中建立發行設定檔轉換檔案。
停用偵錯模式
相依于組建組態而非目的地環境的設定範例是 debug
屬性。 針對發行組建,您通常想要停用偵錯,而不論您要部署的環境為何。 因此,根據預設,Visual Studio 專案範本會建立 Web.Release.config 轉換檔案,其中包含從 元素移除 debug
屬性的程式 compilation
代碼。 以下是預設Web.Release.config:除了已批註化的一些範例轉換程式碼之外,它也會在移除 debug
屬性的 元素中包含 compilation
程式碼:
<?xml version="1.0" encoding="utf-8"?>
<!-- For more information on using web.config transformation visit https://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>
<compilation xdt:Transform="RemoveAttributes(debug)" />
<!--
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>
屬性 xdt:Transform="RemoveAttributes(debug)"
會指定您希望 debug
屬性從 system.web/compilation
已部署 Web.config 檔案中的 元素中移除。 每次部署發行組建時,都會完成此動作。
限制系統管理員的錯誤記錄檔存取
如果應用程式執行時發生錯誤,應用程式會顯示一般錯誤頁面來取代系統產生的錯誤頁面,並使用 Elmah NuGet 套件 進行錯誤記錄和報告。 customErrors
應用程式Web.config檔案中的 元素會指定錯誤頁面:
<customErrors mode="RemoteOnly" defaultRedirect="~/GenericErrorPage.aspx">
<error statusCode="404" redirect="~/GenericErrorPage.aspx" />
</customErrors>
若要查看錯誤頁面,請暫時將元素的 customErrors
屬性從 「RemoteOnly」 變更 mode
為 「On」,然後從 Visual Studio 執行應用程式。 藉由要求不正確 URL 來造成錯誤,例如 Studentsxxx.aspx。 您看不到 GenericErrorPage.aspx 頁面,而不是 IIS 產生的「找不到資源」錯誤頁面。
若要查看錯誤記錄檔,請將 URL 中的所有專案取代為 elmah.axd (,例如 http://localhost:51130/elmah.axd
,) 然後按 Enter:
當您完成時,別忘了將元素設定 customErrors
回 「RemoteOnly」 模式。
在您的開發電腦上,允許免費存取錯誤記錄頁面,但在生產環境中,這是安全性風險的便利性。 針對生產網站,您想要新增授權規則,以限制系統管理員的錯誤記錄存取權,並確定限制可在測試和預備環境中運作。 因此,這是您想要在每次部署發行組建時實作的另一項變更,因此它屬於 Web.Release.config 檔案。
開啟Web.Release.config,並在結尾 configuration
標籤之前立即新增專案 location
,如下所示。
<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>
<compilation xdt:Transform="RemoveAttributes(debug)" />
<!--
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>
<location path="elmah.axd" xdt:Transform="Insert">
<system.web>
<authorization>
<allow roles="Administrator" />
<deny users="*" />
</authorization>
</system.web>
</location>
</configuration>
Transform
「Insert」 的屬性值會使這個專案 location
新增為Web.config檔案中任何現有 location
元素的同層級專案。 (已經有一個 location
元素指定 [更新點數 ] 頁面的授權規則。)
現在您可以預覽轉換,以確定您已正確編碼轉換。
在方案總管中,以滑鼠右鍵按一下Web.Release.config,然後按一下 [預覽轉換]。
隨即開啟頁面,其中會顯示左側的開發 Web.config 檔案,以及所部署 Web.config 檔案在右側的外觀,並醒目提示變更。
(在預覽版中,您可能會注意到您未撰寫轉換的一些其他變更:這些通常涉及移除不會影響功能的空白字元。)
當您在部署之後測試月臺時,您也會測試以確認授權規則是否有效。
注意
安全性注意事項 請勿在生產應用程式中向公用顯示錯誤詳細資料,或將該資訊儲存在公用位置。 攻擊者可以使用錯誤資訊來探索網站中的弱點。 如果您在自己的應用程式中使用 ELMAH,請將 ELMAH 設定為將安全性風險降至最低。 本教學課程中的 ELMAH 範例不應視為建議的組態。 這是為了說明如何處理應用程式必須能夠建立檔案的資料夾所選擇的範例。 如需詳細資訊,請參閱 保護 ELMAH 端點。
您將在發佈設定檔轉換檔案中處理的設定
常見的案例是 Web.config 檔案設定在您部署的每個環境中必須不同。 例如,呼叫 WCF 服務的應用程式在測試和生產環境中可能需要不同的端點。 Contoso University 應用程式也包含這種設定。 此設定可控制網站頁面上可見的指標,告知您位於哪個環境,例如開發、測試或生產環境。 設定值會決定應用程式是否會將 「 (Dev) 」 或 「 (Test) 」 附加至 Site.Master 主版頁面中的主要標題:
當應用程式在預備或生產環境中執行時,會省略環境指標。
Contoso University 網頁會讀取在Web.config檔案中 appSettings
設定的值,以判斷應用程式執行所在的環境:
<appSettings>
<add key="Environment" value="Dev" />
</appSettings>
此值在測試環境中應該是 「測試」,而「Prod」則用於預備和生產環境。
轉換檔案中的下列程式碼會實作此轉換:
<appSettings>
<add key="Environment" value="Test" xdt:Transform="SetAttributes" xdt:Locator="Match(key)"/>
</appSettings>
xdt:Transform
屬性值 「SetAttributes」 表示此轉換的目的是變更Web.config檔案中現有元素的屬性值。 xdt:Locator
屬性值 「比對 (索引鍵) 」表示要修改的專案是 key
屬性符合 key
此處指定之屬性的專案。 元素的唯一另一個屬性 add
是 value
,也就是部署 Web.config的檔案 中將會變更的內容。 這裡所示的程式碼會導致 value
元素的 Environment
appSettings
屬性在部署的Web.config檔案中設定為 「測試」。
此轉換屬於您尚未建立的發行設定檔轉換檔案。 當您為測試、預備和生產環境建立發行設定檔時,您將建立並更新實作此變更的轉換檔案。 您將在 部署至 IIS 並 部署至生產教學 課程中執行此動作。
注意
因為此設定位於 元素中 <appSettings>
,所以當您部署 Web Apps至 Azure App 服務 Azure App 服務 請參閱本主題稍早在 Azure 中指定Web.config設定時,有另一個替代方法可指定轉換。
設定連接字串
雖然預設轉換檔案包含示範如何更新連接字串的範例,但在大多數情況下,您不需要設定連接字串轉換,因為您可以在發行設定檔中指定連接字串。 您將在 部署至 IIS 並 部署至生產教學 課程中執行此動作。
總結
您現在已盡可能完成 Web.config 轉換,再建立發佈設定檔,而且您已看到已部署Web.config檔案中的內容預覽。
在下列教學課程中,您將負責部署設定需要設定專案屬性的工作。
相關資訊
如需本教學課程涵蓋之主題的詳細資訊,請參閱在 Visual Studio 的 Web 部署內容對應和 ASP.NET 部署 期間,使用Web.config轉換來變更目的地Web.config檔案中的設定或app.config檔案 。
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應