ソースコードと構成ファイルの変換

ソースコード変換では、パッケージのインストール時に、パッケージ内のcontentフォルダまたはcontentFilesフォルダ（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として表示されます。
ソースコードファイルでは、フォームの大文字と小文字を区別しないトークンを使用して、NuGet がプロジェクトのプロパティに置き換える値を示 $token$ 。
```
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$ トークンは最も一般的に使用されるプロジェクトプロパティです。それ以外はすべてプロジェクトプロパティに一覧表示されます。もちろん、一部のプロパティはプロジェクトの種類に固有である可能性があることに注意してください。

構成ファイル変換の指定

以降のセクションで説明するように、構成ファイル変換は次の 2 つの方法で実行できます。

パッケージのapp.config.transform フォルダーにweb.config.transformファイルとcontent ファイルを含めます。.transform拡張機能は、パッケージのインストール時に、これらのファイルに既存の構成ファイルとマージする XML が含まれていることを NuGet に指示します。パッケージをアンインストールすると、同じ XML が削除されます。
app.config.install.xdtを使用して、パッケージのweb.config.install.xdt フォルダーにcontentファイルとファイルを含め、必要な変更を記述します。このオプションを使用すると、パッケージがプロジェクトから削除されたときに変更を元に戻す .uninstall.xdt ファイルを含めることもできます。

注

変換は、Visual Studio でリンクとして参照 .config ファイルには適用されません。

XDT を使用する利点は、単に 2 つの静的ファイルをマージするのではなく、要素を使用して XML DOM の構造を操作するための構文と、完全な XPath サポートを使用した属性照合を提供することです。 XDT では、要素の追加、更新、削除、特定の場所への新しい要素の配置、要素の置換/削除 (子ノードを含む) を行うことができます。これにより、パッケージのインストール中に行われたすべての変換をバックアウトするアンインストール変換を簡単に作成できます。

XML 変換

パッケージのapp.config.transform フォルダー内のweb.config.transformとcontentには、プロジェクトの既存のapp.configファイルとweb.config ファイルにマージする要素のみが含まれています。

たとえば、プロジェクトに最初に次のコンテンツが web.configに含まれているとします。

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

パッケージのインストール中にMyNuModule要素を modules セクションに追加するには、パッケージの 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 変換

注

packages.configからPackageReferenceに移行するためのドキュメントのパッケージ互換性の問題に関するセクションで説明したように、以下で説明する 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 2025-10-31

次の方法で共有

ソース コードと構成ファイルの変換

ソース コード変換の指定