ソース コードと構成ファイルの変換Transforming source code and configuration files

packages.config を使用するプロジェクトの場合、NuGet は、パッケージのインストール時およびアンインストール時にソースコードおよび構成ファイルに変換する機能をサポートします。For projects using packages.config, NuGet supports the ability to make transformations to source code and configuration files at package install and uninstall times. PackageReference を使用してパッケージがプロジェクトにインストールされている場合、ソース コード変換のみが適用されます。Only Source code transformations are applied when a package is installed in a project using PackageReference.

ソース コード変換は、パッケージがインストールされるときに、パッケージの content または contentFiles フォルダー (packages.config を使用している場合は contentPackageReference を使用している場合は contentFiles) のファイルに一方向トークンの置き換えを適用します。この場合、トークンは、Visual Studio プロジェクトのプロパティを参照します。A source code transformation applies one-way token replacement to files in the package's content or contentFiles folder (content for customers using packages.config and contentFiles for PackageReference) when the package is installed, where tokens refer to Visual Studio project properties. これにより、プロジェクトの名前空間にファイルを挿入したり、ASP.NET プロジェクトで通常は global.asax に置かれるコードをカスタマイズしたりすることができます。This allows you to insert a file into the project's namespace, or to customize code that would typically go into global.asax in an ASP.NET project.

構成ファイルの変換を使用して、web.configapp.config などのターゲット プロジェクトに既に存在するファイルを変更することができます。A config file transformation allows you to modify files that already exist in a target project, such as web.config and app.config. たとえば、場合によっては、パッケージで構成ファイルの modules セクションに項目を追加する必要があります。For example, your package might need to add an item to the modules section in the config file. この変換は、構成ファイルに追加するセクションを記述するパッケージ内の特別なファイルを含めることで行われます。This transformation is done by including special files in the package that describe the sections to add to the configuration files. パッケージがアンインストールされるときには、同じ変更が、逆に行われ、これを双方向の変換にします。When a package is uninstalled, those same changes are then reversed, making this a two-way transformation.

変換のソース コードを指定するSpecifying source code transformations

  1. パッケージからプロジェクトに挿入するファイルは、パッケージ内の content および contentFiles フォルダーに配置する必要があります。Files that you want to insert from the package into the project must be located within the package's content and contentFiles folders. たとえば、ContosoData.cs という名前のファイルをターゲット プロジェクトの Models フォルダーにインストールする場合は、パッケージの content\Models および contentFiles\{lang}\{tfm}\Models フォルダー内にファイルが置かれている必要があります。For example, if you want a file called ContosoData.cs to be installed in a Models folder of the target project, it must be inside the content\Models and contentFiles\{lang}\{tfm}\Models folders in the package.

  2. インストール時にトークンの置換を適用するように NuGet に指示するには、.pp をソース コード ファイル名に追加します。To instruct NuGet to apply token replacement at install time, append .pp to the source code file name. インストール後、ファイルには .pp 拡張子は付きません。After installation, the file will not have the .pp extension.

    たとえば、ContosoData.cs で変換を行うには、パッケージ内のファイルに ContosoData.cs.pp という名前を付けます。For example, to make transformations in ContosoData.cs, name the file in the package ContosoData.cs.pp. インストール後には、ContosoData.cs として表示されます。After installation it will appear as ContosoData.cs.

  3. ソース コード ファイル内では、$token$ 形式の大文字と小文字が区別されないトークンを使用し、NuGet でプロジェクトのプロパティと置き換える必要がある値を示します。In the source code file, use case-insensitive tokens of the form $token$ to indicate values that NuGet should replace with project properties:

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

    インストール時に、NuGet が、ターゲット プロジェクトのルート名前空間が Fabrikam であると仮定して、$rootnamespace$Fabrikam に置き換えます。Upon installation, NuGet replaces $rootnamespace$ with Fabrikam assuming the target project's whose root namespace is Fabrikam.

$rootnamespace$ トークンは、最もよく使用されるプロジェクト プロパティです。他のすべてのトークンは、プロジェクト プロパティに関するページに一覧表示されています。The $rootnamespace$ token is the most commonly used project property; all others are listed in project properties. 当然ながら、一部のプロパティはプロジェクトの種類に固有である可能性があります。Be mindful, of course, that some properties might be specific to the project type.

構成ファイルの変換を指定するSpecifying config file transformations

以降のセクションで後述するように、2 つの方法で構成ファイルの変換を実行できます。As described in the sections that follow, config file transformations can be done in two ways:

  • app.config.transform および web.config.transform ファイルをパッケージの content フォルダーに含めます。.transform 拡張子は、パッケージがインストールされるときに、これらのファイルが既存の構成ファイルにマージする XML を含んでいることを NuGet に指示します。Include app.config.transform and web.config.transform files in your package's content folder, where the .transform extension tells NuGet that these files contain the XML to merge with existing config files when the package is installed. パッケージがアンインストールされると、その同じ XML が削除されます。When a package is uninstalled, that same XML is removed.
  • app.config.install.xdt および web.config.install.xdt ファイルをパッケージの content フォルダーに含めるときに、XDT 構文を使用して、目的の変更を記述します。Include app.config.install.xdt and web.config.install.xdt files in your package's content folder, using XDT syntax to describe the desired changes. このオプションを使用して、.uninstall.xdt ファイルも含め、プロジェクトからパッケージが削除されるときに変更を逆に実行することもできます。With this option you can also include a .uninstall.xdt file to reverse changes when the package is removed from a project.

注意

変換は、Visual Studio でリンクとして参照されている .config ファイルには適用されません。Transformations are not applied to .config files referenced as a link in Visual Studio.

XDT を使用することの利点は、2 つの静的なファイルを単純にマージする代わりに、XPath が完全にサポートされる要素と属性のマッチングを使用して XML DOM の構造を操作するための構文を提供することです。The advantage of using XDT is that instead of simply merging two static files, it provides a syntax for manipulating the structure of an XML DOM using element and attribute matching using full XPath support. XDT はその後で、要素の追加、更新、削除、指定した場所での新しい要素の配置、要素の置換/削除 (子ノードを含む) を行うことができます。XDT can then add, update, or remove elements, place new elements at a specific location, or replace/remove elements (including child nodes). これにより、パッケージのインストール中に実行されたすべての変換を元に戻すアンインストール変換を簡単に作成できるようになります。This makes it straightforward to create uninstall transforms that back out all transformations done during package installation.

XML 変換XML transforms

パッケージの content フォルダーの app.config.transformweb.config.transform は、プロジェクトの既存の app.config および web.config ファイルにマージする要素のみを含んでいます。The app.config.transform and web.config.transform in a package's content folder contain only those elements to merge into the project's existing app.config and web.config files.

例のように、プロジェクトが最初に web.config 内に次のコンテンツを含んでいると仮定します。As an example, suppose the project initially contains the following content in web.config:

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

パッケージのインストール中に MyNuModule 要素を modules セクションに追加するには、次のような web.config.transform ファイルをパッケージの content フォルダー内に作成します。To add a MyNuModule element to the modules section during package install, create a web.config.transform file in the package's content folder that looks like this:

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

NuGet がパッケージをインストールした後に、web.config は次のように表示されます。After NuGet installs the package, web.config will appear as follows:

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

NuGet が modules セクションを置き換えずに、新しい要素と特性のみを追加することによって単純に新しいエントリをその中にマージしています。Notice that NuGet didn't replace the modules section, it just merged the new entry into it by adding only new elements and attributes. NuGet は、どの既存の要素または属性も変更しません。NuGet will not change any existing elements or attributes.

パッケージがアンインストールされるときに、NuGet は、.transform ファイルをもう一度調べ、含まれている要素を適切な .config ファイルから削除します。When the package is uninstalled, NuGet will examine the .transform files again and remove the elements it contains from the appropriate .config files. このプロセスは、パッケージのインストール後に変更する .config ファイルのどの行にも影響しません。Note that this process will not affect any lines in the .config file that you modify after package installation.

広範な例として、Error Logging Modules and Handlers for ASP.NET (ELMAH) パッケージは、多くのエントリを web.config に追加し、それらもパッケージがアンインストールされるときに削除されます。As a more extensive example, the Error Logging Modules and Handlers for ASP.NET (ELMAH) package adds many entries into web.config, which are again removed when a package is uninstalled.

その web.config.transform ファイルを調べるには、ELMAH パッケージを上記のリンクからダウンロードし、パッケージの拡張子を .nupkg から .zip に変更して、content\web.config.transform をその ZIP ファイル内から開きます。To examine its web.config.transform file, download the ELMAH package from the link above, change the package extension from .nupkg to .zip, and then open content\web.config.transform in that ZIP file.

パッケージのインストールおよびアンインストールの影響を確認するには、新しい ASP.NET プロジェクトを Visual Studio で作成し (テンプレートは、[新しいプロジェクト] ダイアログ ボックスの [Visual C#] > [Web] にあります)、空の ASP.NET アプリケーションを選択します。To see the effect of installing and uninstalling the package, create a new ASP.NET project in Visual Studio (the template is under Visual C# > Web in the New Project dialog), and select an empty ASP.NET application. web.config を開いて初期状態を確認します。Open web.config to see its initial state. プロジェクトを右クリックし、[NuGet パッケージの管理] を選択し、nuget.org で ELMAH を見つけて、最新バージョンをインストールします。Then right-click the project, select Manage NuGet Packages, browse for ELMAH on nuget.org, and install the latest version. web.config のすべての変更に注意してください。Notice all the changes to web.config. 次に、パッケージをアンインストールすると、web.config が前の状態に戻ります。Now uninstall the package and you see web.config revert to its prior state.

XDT 変換XDT transforms

XDT 構文を使用して構成ファイルを変更することができます。You can modify config files using XDT syntax. $ 区切り文字 (大文字と小文字は区別されません) 内にプロパティ名を含めることにより、NuGet でトークンをプロジェクト プロパティに置き換えることもできます。You can also have NuGet replace tokens with project properties by including the property name within $ delimiters (case-insensitive).

たとえば、次の app.config.install.xdt ファイルは、プロジェクトの FullPathFileNameActiveConfigurationSettings 値を含む app.configappSettings 要素を挿入します。For example, the following app.config.install.xdt file will insert an appSettings element into app.config containing the FullPath, FileName, and ActiveConfigurationSettings values from the project:

<?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 内に次のコンテンツを含んでいると仮定します。For another example, suppose the project initially contains the following content in web.config:

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

パッケージのインストール中に MyNuModule 要素を modules セクションに追加するために、パッケージの web.config.install.xdt は次を含んでいます。To add a MyNuModule element to the modules section during package install, the package's web.config.install.xdt would contain the following:

<?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 は次のようになります。After installing the package, web.config will look like this:

<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 ファイルは、次を含む必要があります。To remove only the MyNuModule element during package uninstall, the web.config.uninstall.xdt file should contain the following:

<?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>