通过

转换源代码和配置文件

安装包时，源代码转换会对包的content或contentFiles文件夹中的文件进行单向令牌替换（content供使用packages.config的客户，contentFiles供使用PackageReference的客户），其中令牌引用 Visual Studio 项目属性。 这样，就可以将文件插入项目的命名空间，或自定义通常在 ASP.NET 项目中输入 global.asax 的代码。

配置文件转换允许修改目标项目中已存在的文件，例如web.config和 app.config。 例如，您的包可能需要将一个项目添加到配置文件的 modules 部分中。 此转换是通过在包中包含描述需要添加到配置文件中的各个节的特殊文件来完成的。 卸载包后，将撤消这些相同的更改，从而实现双向转换。

指定源代码转换

  1. 要从包插入到项目中的文件必须位于包 content 和 contentFiles 文件夹中。 例如，如果你想要一个名为ContosoData.cs的文件安装在目标项目的Models文件夹中，则该文件必须位于包中的content\Models和contentFiles\{lang}\{tfm}\Models文件夹内。

  2. 若要指示 NuGet 在安装时应用令牌替换，请追加 .pp 到源代码文件名。 安装后，该文件将不具有 .pp 扩展名。

    例如，若要进行 ContosoData.cs转换，请命名包 ContosoData.cs.pp中的文件。 安装后，它将显示为 ContosoData.cs.

  3. 在源代码文件中，使用不区分大小写的 $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$ 是最常用的项目属性;所有其他令牌都列在 项目属性中。 当然，请注意，某些属性可能特定于项目类型。

指定配置文件的转换方式

如以下各节中所述，可以通过两种方式完成配置文件转换：

  • 在包的app.config.transform文件夹中包括web.config.transform和content文件，其中.transform扩展告知 NuGet 这些文件包含 XML，在安装包时要与现有配置文件合并。 卸载包后，将删除同一 XML。
  • 在包的content文件夹中包含app.config.install.xdt和web.config.install.xdt文件，并使用XDT语法描述所需的更改。 使用此选项，还可以在从项目中删除包时包含一个 .uninstall.xdt 文件来反向更改。

注释

转换不适用于 .config 在 Visual Studio 中作为链接引用的文件。

使用 XDT 的优点是，它不是简单地合并两个静态文件，而是提供一种语法，使用完整的 XPath 支持来匹配和操作 XML DOM 的结构和元素属性。 然后，XDT 可以添加、更新或删除元素、将新元素放置在特定位置或替换/删除元素（包括子节点）。 这样，可以轻松创建卸载转换，以备份在包安装过程中完成的所有转换。

XML 转换

包content的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>

若要在安装包过程中将MyNuModule元素添加到modules节，请在包的content文件夹中创建一个如下所示的web.config.transform文件：

<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 转换

注释

如从packages.configPackageReference迁移的文档包兼容性问题部分中所述，XDT转换仅由packages.config支持。 如果将以下文件添加到您的包中，则使用带 PackageReference 的包的使用者将不会应用转换（请参考 此示例 来确保 XDT 转换正常工作PackageReference）。

可以使用 XDT 语法修改配置文件。 还可以让 NuGet 使用 项目属性 替换令牌，只需将属性名称包含在 $ 分隔符中（不区分大小写）。

例如，以下app.config.install.xdt文件将插入一个appSettings元素，app.config其中包含FullPath项目中的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>
  • Last updated on