轉換原始程式碼和設定檔

原始程式碼轉換會在安裝套件時，將單向權杖取代套用至套件或contentcontentFiles資料夾中的檔案（content 適用於使用 packages.config 和 contentFiles 的PackageReference客戶），其中權杖會參考 Visual Studio 專案屬性。這可讓您在專案的命名空間中插入檔案，或自訂通常會在 ASP.NET 專案中位於 global.asax 的程式碼。

組態檔轉換可讓您修改目標專案中已存在的檔案，例如 web.config 和 app.config。例如，您的套件可能需要將項目 modules 新增至設定檔中的區段。此轉換是透過在套件中包含特殊檔案來完成，這些檔案描述要新增至設定檔的區段。卸載套件時，這些相同的變更會反轉，使其成為雙向轉換。

指定原始碼轉換

您要從套件插入專案的檔案必須位於套件的 content 和 contentFiles 資料夾中。例如，如果您希望將名為ContosoData.cs的檔案安裝在目標專案的Models資料夾中，則該檔案必須位於套件中的content\Models和contentFiles\{lang}\{tfm}\Models資料夾內。
若要指示 NuGet 在安裝時套用權杖取代，請附加 .pp 至原始程式碼檔名。安裝後，該文件將沒有 .pp 副檔名。

例如，若要在中 ContosoData.cs進行轉換，請將套件 ContosoData.cs.pp中的檔案命名為。安裝後，它將顯示為 ContosoData.cs。

在原始程式碼檔案中，使用不區分大小寫形式為 $token$ 的權杖來指出 NuGet 應該以專案屬性取代的值：

namespace $rootnamespace$.Models
{
    public struct CategoryInfo
    {
        public string categoryid;
        public string description;
        public string htmlUrl;
        public string rssUrl;
        public string title;
    }
}

安裝時，NuGet 會取代 $rootnamespace$ 為 Fabrikam 假設目標專案的根命名空間為 Fabrikam。

$rootnamespace$ 專案屬性是最常用的屬性，其餘的所有專案屬性都會列在專案屬性中。當然，請注意，某些屬性可能特定於專案類型。

指定設定文件變換

如以下各節所述，設定檔轉換可以透過兩種方式完成：

在套件的 content 資料夾中包含app.config.transform 和 web.config.transform 檔案，其中 .transform 副檔名告知 NuGet 這些檔案包含 XML，用於在安裝套件時與現有的組態檔合併。解除安裝套件時，會移除相同的 XML。
將 app.config.install.xdt 和 web.config.install.xdt 檔案包含在套件的 content 資料夾中，使用 XDT 語法描述所需的變更。使用此選項時，您還可以包含一個.uninstall.xdt檔案，以便在從專案中移除套件時反轉變更。

備註

不會將轉換套用至 Visual Studio 中被參考為連結的 .config 檔案。

使用 XDT 的優點是，它不是簡單地合併兩個靜態文件，而是提供了一種語法，用於使用完整的 XPath 支援，使用元素和屬性匹配來操作 XML DOM 的結構。然後，XDT 可以新增、更新或移除元素、將新元素放置在特定位置，或取代/移除元素（包括子節點）。這可讓您輕鬆建立解除安裝轉換，以取消套件安裝期間完成的所有轉換。

XML 轉換

套件資料夾中的app.config.transform 和 web.config.transform 僅包含要合併到專案現有的app.config和web.config檔案中的元素。

例如，假設專案最初包含以下內容 web.config：

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
        </modules>
    </system.webServer>
</configuration>

若要在套件安裝期間將元素新增至MyNuModulemodules區段，請在套件資料夾web.config.transform中建立如下content所示的檔案：

<configuration>
    <system.webServer>
        <modules>
            <add name="MyNuModule" type="Sample.MyNuModule" />
        </modules>
    </system.webServer>
</configuration>

NuGet 安裝套件之後， web.config 將顯示如下：

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
            <add name="MyNuModule" type="Sample.MyNuModule" />
        </modules>
    </system.webServer>
</configuration>

請注意，NuGet 並沒有取代modules區段，而是合併新的項目，只新增元素和屬性至其中。 NuGet 不會變更任何現有的元素或屬性。

解除安裝套件時，NuGet 會再次檢查 .transform 檔案，並從適當的 .config 檔案中移除其中包含的元素。請注意，此程序不會影響您在套件安裝後修改的檔案中 .config 的任何行。

作為範圍更大的範例，「ASP.NET 的錯誤記錄模組和處理常式（ELMAH）」套件會在web.config 中新增許多項目，這些項目會在解除安裝套件時再次移除。

若要檢查其 web.config.transform 檔案，請從上述連結下載 ELMAH 套件，將套件副檔名從 .nupkg 變更為 .zip，然後在該 ZIP 檔案中開啟 content\web.config.transform 。

若要查看安裝和解除安裝套件的效果，請在 Visual Studio 中建立新的 ASP.NET 專案（範本位於 [新增專案] 對話方塊的 Visual C# > Web 底下），然後選取空白的 ASP.NET 應用程式。打開 web.config 查看其初始狀態。然後以滑鼠右鍵按一下專案，選取 [管理 NuGet 套件]，在 nuget.org 上瀏覽 ELMAH，然後安裝最新版本。請注意對 web.config 的所有變更。現在卸載該軟件包，您會看到 web.config 恢復到其先前的狀態。

XDT 轉換處理

備註

如文件中從遷移至的套件相容性問題一節所述，XDT 轉換僅由支援，詳述如下。如果您將下列檔案新增至套件，則使用您的套件搭配PackageReference的消費者將不會套用轉換（請參閱此範例，了解如何讓XDT轉換與PackageReference一起運作）。

您可以使用 XDT 語法修改設定檔。您也可以讓 NuGet 將標記替換為專案屬性，方法是將屬性名稱置於 $ 分隔符號中（不區分大小寫）。

例如，下列app.config.install.xdt檔案會在專案中插入含有appSettingsapp.configFullPath、FileName和ActiveConfigurationSettings值的元素：

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <appSettings xdt:Transform="Insert">
        <add key="FullPath" value="$FullPath$" />
        <add key="FileName" value="$filename$" />
        <add key="ActiveConfigurationSettings " value="$ActiveConfigurationSettings$" />
    </appSettings>
</configuration>

另一個範例，假設專案最初包含下列內容 web.config：

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
        </modules>
    </system.webServer>
</configuration>

若要在套件安裝期間將MyNuModule元素新增至modules區段，套件的web.config.install.xdt將包含下列專案：

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <system.webServer>
        <modules>
            <add name="MyNuModule" type="Sample.MyNuModule" xdt:Transform="Insert" />
        </modules>
    </system.webServer>
</configuration>

安裝套件後， web.config 會如下所示：

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
            <add name="MyNuModule" type="Sample.MyNuModule" />
        </modules>
    </system.webServer>
</configuration>

若只在套件解除安裝期間移除 MyNuModule 元素，檔案 web.config.uninstall.xdt 應包含下列內容：

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <system.webServer>
        <modules>
            <add name="MyNuModule" xdt:Transform="Remove" xdt:Locator="Match(name)" />
        </modules>
    </system.webServer>
</configuration>

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2025-10-31