MSBuild – Preemptive Support Center Japanese

MSBuild は、Visual Studio、Visual Studio for Mac、および .NET Core SDK（dotnet）が使用するビルドシステムです。これはコマンドラインから呼び出すこともできます。 Dotfuscator の MSBuild ターゲットを使用することで、.NET プロジェクトに Dotfuscator を統合することができます。また、Dotfuscator には、ユーザー独自のカスタムビルドターゲットから呼び出すことのできる MSBuild タスクも用意されています。

このページでは、これらのコンポーネントの機能概要を示し、それらのコンポーネントの最優良使用事例を説明します。詳細なリファレンスについては、MSBuild リファレンスのページを参照してください。

MSBuild コンポーネントの場所

Dotfuscator の MSBuild コンポーネントは、使用したインストールパッケージに応じて、次のディレクトリにあります。

インストールパッケージ	ディレクトリ
Windows インストーラー	`$(MSBuildProgramFiles32)\MSBuild\PreEmptive\Dotfuscator\7`
NuGet パッケージ	`{install dir}/tools/msbuilddir`

ここで、

$(MSBuildProgramFiles32) は予約済みの MSBuild プロパティで、 Windows の C:\Program Files (x86) ディレクトリ（64 ビット版）および C:\Program Files（32 ビット版）を指します。
{install dir} は、NuGet パッケージのインストール時に示した Dotfuscator インストールディレクトリです。

複数の環境の処理

MSBuild コンポーネントディレクトリは Dotfuscator のインストール方法によって異なるので、ターゲットまたはタスクをプロジェクトファイルにインポートする場合は MSBuild プロパティを使用することをお勧めします。この User Guide では DotfuscatorMSBuildDir という名前のプロパティを使用します。プロジェクトファイルでも同様にこの名前で定義されています。

<!-- 環境固有のプロパティをインポートします。これには DotfuscatorMSBuildDir が含まれる可能性があります。 -->
<Import Project="$([System.Environment]::GetFolderPath(SpecialFolder.UserProfile))/.dotfuscator.user.props" 
        Condition="Exists('$([System.Environment]::GetFolderPath(SpecialFolder.UserProfile))/.dotfuscator.user.props')"/>

<!-- DotfuscatorMSBuildDir プロパティには既定値を設定します -->
<PropertyGroup>
  <DotfuscatorMSBuildDir Condition="'$(DotfuscatorMSBuildDir)' == ''">$(MSBuildProgramFiles32)/MSBuild/PreEmptive/Dotfuscator/7</DotfuscatorMSBuildDir>
</PropertyGroup>

Dotfuscator を Windows インストーラーを使用してインストールしたコンピューターでは、DotfuscatorMSBuildDir に別の場所を設定する必要はありあません。プロジェクトファイルに指定されている既定の値が正しいディレクトリを指します。

Dotfuscator を NuGet パッケージを使用してインストールしたコンピューターでは、DotfuscatorMSBuildDir プロパティに NuGet {install dir} を設定する必要があります。これには以下の方法があります。

.dotfuscator.user.props ファイルでこのプロパティを設定する。
DotfuscatorMSBuildDir 環境変数を設定する（すべての環境変数が MSBuild プロパティとして公開される）。
プロジェクトのディレクトリの上位ディレクトリにある、Directory.Build.props または Directory.Build.targets ファイルでこのプロパティを設定する。
msbuild または dotnet コマンドラインを呼び出したときに、このプロパティを引数として指定する。

必要に応じてこのプロパティが設定されると、$(DotfuscatorMSBuildDir) をプロジェクトディレクトリとして指定し、プロジェクトでターゲットをインポートする、またはタスク使用することができます。

.dotfuscator.user.props ファイル

上記の DotfuscatorMSBuildDir など、ユーザー固有の MSBuild プロパティを設定する便利な方法は、既知のディレクトリに MSBuild .props ファイルを作成し、そのファイルをプロジェクトでインポートすることです。プロジェクトは全環境にわたって同じ内容を持ちますが、.props ファイルは異なります。

この .props ファイルのパスは任意ですが、この User Guide の例との一貫性を保つため、.dotfuscator.user.props ファイルをご自分の環境のユーザーディレクトリに作成することをお勧めします（ユーザーディレクトリは、Windows では環境変数 USERPROFILE、macOS および Linux では HOME によって指定されます）。

このようなファイルの例を以下に示します。

<!-- これは Dotfuscator の MSBuild コンポーネントを使用する、プロジェクト用の MSBuild プロパティ ファイルです。
     詳細については、<https://www.preemptive.com/dotfuscator/pro/userguide/ja/interfaces_msbuild.html#user> を参照してください。
-->
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <PropertyGroup>
        <!-- Dotfuscator の MSBuild コンポーネントがインストールされるパス。 -->
        <DotfuscatorMSBuildDir>C:\apps\Dotfuscator\tools\msbuilddir</DotfuscatorMSBuildDir>
        <!-- Dotfuscator のライセンス文字列。 -->
        <DotfuscatorLicense>00000000000000000000000000000000</DotfuscatorLicense>
    </PropertyGroup>
</Project>

この例では環境固有の 2 つのプロパティを設定します。

DotfuscatorMSBuildDir には、Dotfuscator が NuGet パッケージによってインストールされたカスタムディレクトリが設定されます。

Dotfuscator が Windows インストーラーでインストールされた場合は、このプロパティを設定する必要はありません。
DotfuscatorLicenseには、ライセンス文字列形式のライセンスキーが設定されます。これによって、MSBuild ターゲットの実行時に、Dotfuscator 自身が自動的にアクティブ化します。 Dotfuscate タスクを手動で呼び出す場合は、このプロパティをタスクの License 入力パラメーターに渡すことによって、同様の効果が得られます。

Dotfuscator を Windows インストーラー、構成エディター、または環境変数を使ってアクティブ化する場合は、このプロパティを設定する必要はありません。

設定するプロパティがない場合は、.dotfuscator.user.props ファイルを完全に削除することができます。

ユーザーディレクトリにある .dotfuscator.user.props をプロジェクトへインポートするには、次のコード行を（まだない場合は）プロジェクトファイル（.csproj, .vbproj など）に追加します。

<Import Project="$([System.Environment]::GetFolderPath(SpecialFolder.UserProfile))/.dotfuscator.user.props" 
        Condition="Exists('$([System.Environment]::GetFolderPath(SpecialFolder.UserProfile))/.dotfuscator.user.props')"/>

これらのコード行は、プロジェクトファイル内で、設定できるプロパティの使用よりも前に配置してください。

MSBuild ターゲット

Dotfuscator に用意されている MSBuild ターゲットを Visual Studio プロジェクトにインポートすることで、ビルド中に保護が自動的に適用されます。 MSBuild ターゲットを使用する利点は以下のとおりです。

Dotfuscator は、Visual Studio および MSBuild における通常のビルド処理の一環として保護を適用するので、保護を別のビルドステップとして適用せずに済みます。
Dotfuscator はビルドのパッケージ手順の前に実行されるので、ユニバーサル Windows プラットフォーム（UWP）アプリなどのパッケージ形式で配布されるアプリケーションに保護を簡単に適用できます。
統合により、Dotfuscator 構成ファイルがプロジェクトの参照に基づいて自動的に生成、管理されるので、コード全体が、ソリューションの複数のプロジェクトに分散している場合でも、保護されます。

アプリケーションの保護ページでは、このターゲットを使って一般的なプロジェクトを保護することが非常に簡単であることを例で示します。このセクションでは、保護するプロジェクトと構成を選択する方法など、より高度なケースに使用できる追加の詳細を記載します。

メモ： このセクションでは、PreEmptive.Dotfuscator.Common.targets ファイルに定義される MSBuild ターゲットについて説明します。 PreEmptive.Dotfuscator.targets に定義される廃止予定の MSBuild ターゲットについては、非推奨の MSBuild ターゲットを参照してください。

これらの MSBuild ターゲットは、インポートして有効にすると、ビルド中、コンパイルからパッケージ手順までの間に自動的に実行されます。ビルド処理において Dotfuscator を実行する方法とタイミングをより厳格に管理するには、PreEmptive.Dotfuscator.Common.targets からでなく、自身の MSBuild ターゲットから、MSBuild タスクを呼び出します。

MSBuild ターゲットの技術的な詳細については、ターゲットのリファレンスを参照してください。

保護する対象の選択

ビルドに Dotfuscator を追加すると、アプリケーションのセキュリティは向上しますが、ビルドに要する時間が長くなるほか、間違った構成やランタイムエラーを生じるリスクを取り込むことになります。また、アプリケーションのデバッグが困難になる可能性があります。このため、Dotfuscator は、実行可能プロジェクトの Release 構成など、Dotfuscator を必要とするプロジェクトやビルド構成に対してのみ使用してください。

保護するプロジェクトの選択

Visual Studio プロジェクトに Dotfuscator を統合すると、既定では、そのプロジェクトのソリューションで出力ディレクトリ（ProjectDir/bin/Release）に生成されるすべてのアセンブリが保護されます。したがって、配布するすべてのアセンブリを保護するために、ソリューション内のすべてのプロジェクトに Dotfuscator を統合する必要はありません。

メモ： 必要なプロジェクトファイル（Project.csproj など）に、MSBuild プロパティ DotfuscatorIncludeAsInput を適用することで、プロジェクトを保護から除外することができます。

たとえば、次のソリューション、MySolution.sln とその依存関係について考えましょう。

MyApp.exe とその依存関係を信頼されていないユーザーに配布する必要があるため、自社が所有し配布するコード全体を Dotfuscator で保護しなければなりません。 LibA.dll と LibB.dll は MyApp.exe と一緒にのみ配布します。

MyApp プロジェクトにのみ Dotfuscator を統合し、Release 構成に対して保護を有効にすると、MyApp/bin/Release ディレクトリ内の以下の 3 つのアセンブリが保護されます。

LibA.dll
LibB.dll
MyApp.exe

以下の 2 つのアセンブリも MyApp/bin/Release ディレクトリに生成されますが、これらは保護されません。

ExtLib1.dll
ExtLib2.dll

他のプロジェクトの出力ディレクトリ（LibA/bin/Release など）に生成されるアセンブリも保護されません。

この例から学ぶべき重要ポイントは以下の 3 つです。

Dotfuscator は、統合されたプロジェクトの出力ディレクトリに生成されたアセンブリのみを保護する。

MyApp/bin/Release に生成される LibA.dll のコピーが保護されるのに対し、LibA/bin/Release と LibB/bin/Release に生成される同じアセンブリのコピーは保護されません。これと同じ規則が LibB.dll にも適用されます。
Dotfuscator を統合する必要があるのは最終出力プロジェクトのみ、つまり、出力を直接配布したいプロジェクトのみである。

この例では、LibA および LibB プロジェクトに Dotfuscator を統合する必要はないということです。信頼されていないユーザーは LibA.dll および LibB.dll アセンブリを MyApp の依存関係としてのみ受け取ることができ、MyApp/bin/Release ディレクトリに生成された、これらのアセンブリのコピーは Dotfuscator によって保護されます。

ソリューションに複数の出力プロジェクトがある場合は、個々の出力プロジェクトに Dotfuscator を統合する必要があります。信頼されていないユーザーに LibA も配布する別のシナリオ（例：組織の外部の開発者が API ライブラリを参照する場合）では、MyApp プロジェクトと LibA プロジェクトの両方に Dotfuscator を統合する必要があり、LibA のライブラリモードは有効であるようにします。
Dotfuscator はコードのみを保護する（既定）。

既定では、NuGet 内のアセンブリ（ExtLib1.dll）や、ファイルシステム上のパスにあるアセンブリ（ExtLib2.dll）など、ビルドするソリューションの外部にあるアセンブリは、保護されません。「保護するアセンブリの制御」で説明しているとおり、DotfuscatorIncludeAsInput 項目メタデータを使ってディスク上の外部アセンブリを保護することができます。当バージョンの Dotfuscator では、既に NuGet パーッケージへパッケージ済みのアセンブリの保護はサポートしていません。

メモ： どのアセンブリを保護するか評価するために、Dotfuscator は、統合されたプロジェクトからProjectReference 項目を再帰的に追跡します。プロジェクトの 1 つが Reference 項目を使って別のプロジェクトの出力アセンブリを参照している場合、その参照されるアセンブリを DotfuscatorIncludeAsInput 項目メタデータを使って手動で含めると、そのアセンブリのみが保護されます。詳細については、「保護するアセンブリの制御」を参照してください。

保護する構成の選択

Visual Studio のソリューションおよびプロジェクトにおけるビルドは、構成別にパラメーター化されます。既定では、ソリューションには Debug と Release という 2 つの構成が用意されています。各プロジェクトには対応する構成があるため、ソリューションを Release 構成でビルドした場合には、すべてのプロジェクトも各自の Release 構成でビルドされます。

Dotfuscator をプロジェクトに統合した後で、これら 2 つの構成のどちらを保護する必要があるかを知る必要があります。保護する対象を選択するためのガイドラインを以下に示します。

すべてのリリースビルド構成に Dotfuscator を適用する必要があります。 信頼されていないユーザーに配布するビルドはすべて保護する必要があります。
テストするビルド構成には、Dotfuscator を適用する必要があります。 他の静的分析ツールと同様に、Dotfuscator もアプリケーションの動作に関してすべてを判別できるわけではありません。ランタイムエラーを発見して解決するには、保護されたアプリケーションをテストする必要があります。
デバッグ専用のビルド構成に Dotfuscator を適用しないでください。 保護されていないコードのデバッグに比べ、難読化されたコードのデバッグははるかに困難で経験も限られています。ソースコードを提示し、Dotfuscator で更新されたデバッグシンボルを自動的に出力するように設定されている場合でも、デバッグ機能のいくつかは利用できないでしょう。このため、Dotfuscator をローカルの開発構成の一部としてを実行しないようにしてください。

これらのガイドラインが示す一般的な意味は、Debug 構成でなく Release 構成を保護するということです。プロジェクトに含まれる構成がさらにある場合は、それらの構成も保護する必要があります。たとえば、Xamarin.iOS プロジェクトでは Release、Ad-Hoc、AppStore を保護する必要があります。

保護するアセンブリの制御

Dotfuscator の MSBuild ターゲットがプロジェクトに統合され有効になると、Dotfuscator の既定の動作は、統合されたプロジェクトのアセンブリを保護するだけでなく、同一ソリューション内のほかのプロジェクトから、統合されたプロジェクトの出力ディレクトリにすべてのアセンブリもコピーされます。ただし、既定では、ソリューションの外部にあるアセンブリは保護されません。

この既定の動作は DotfuscatorIncludeAsInput を使って変更することができます。これは、MSBuild プロパティとして、および MSBuild Reference 項目に対するメタデータとして適用できる設定です。

プロジェクトの対象除外

Dotfuscator から、参照されるプロジェクトを除外するには、除外するプロジェクトのプロジェクトファイル（.csproj など）に DotfuscatorIncludeAsInput タグを追加します。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- 追加のプロパティ タグ -->

    <DotfuscatorIncludeAsInput>false</DotfuscatorIncludeAsInput>

    <!-- 追加のプロパティ タグ -->
  </PropertyGroup>

</Project>

アセンブリに対する保護を再度有効にするには、このタグを完全に削除するか、またはこのタグの値を true に設定します。

外部アセンブリの対象選択

Dotfuscator への入力として外部アセンブリを追加するには、そのアセンブリ用の Reference 項目に DotfuscatorIncludeAsInput タグを追加し、その値に true を設定します。 Dotfuscator で構成されたプロジェクトだけでなく、外部アセンブリを参照する入力プロジェクトへ DotfuscatorIncludeAsInput タグを追加できます。

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <Reference Include="ExternalAssembly">
      <HintPath>../path/to/the/assembly/ExternalAssembly.dll</HintPath>

      <DotfuscatorIncludeAsInput>true</DotfuscatorIncludeAsInput>

    </Reference>
  </ItemGroup>
</Project>

アセンブリに対する保護を無効にするには、DotfuscatorIncludeAsInput タグの値を false に変更するか、またはこのタグを完全に削除します。

警告： DotfuscatorIncludeAsInput タグが動作するのは Reference 項目を使用した場合のみです。ProjectReference または PackageReference 項目ではサポートされません。

警告： 当バージョンの Dotfuscator は、NuGet 経由で参照される外部アセンブリの保護はサポートしていません。

詳細情報

上記の例で使用される 2 つの DotfuscatorIncludeAsInput タグは同じ構文を持つ可能性がありますが、最初に示したタグは MSBuild プロジェクトプロパティで、2 番目に示したタグは MSBuild 項目メタデータです。どちらも使用法は基本的に同じですが、プロジェクトプロパティの方は Dotfuscator に直接統合されないプロジェクトファイルへ追加する必要があります。一方、メタデータはすべてのファイルの Reference 項目に追加できます。

DotfuscatorIncludeAsInput プロジェクトプロパティは再帰的に適用されます。これは、保護されたプロジェクトによって参照されるソリューション内プロジェクトも保護されますが、保護対象から除外されたプロジェクトによって参照されるソリューション内プロジェクトは除外されることを意味します。ソリューション内プロジェクトが、保護されたプロジェクトおよび保護対象から除外されたプロジェクトの両方で参照される場合は、その参照されるプロジェクトが既定で保護されます。

警告： 保護されていないプロジェクトによって参照されるプロジェクトを保護すると、保護されていないプロジェクトにある参照が壊れることがあります。保護されたプロジェクトに対するライブラリモードを有効にするか、または、プロジェクトを完全に保護の対象から除外することをお勧めします。

Dotfuscator は、保護の対象から除外されたプロジェクトの Reference 項目に対する DotfuscatorIncludeAsInput メタデータを無視します。

ターゲットのインポート

メモ： ターゲットをインポートするだけでは、ビルドが保護されるようにはなりません。保護を有効にするには、プロパティを設定することも必要です。

Dotfuscator の MSBuild ターゲットファイル PreEmptive.Dotfuscator.Common.targets は、MSBuild コンポーネントディレクトリにあります。このため、ターゲットを選択したプロジェクトにインポートするには、テキストエディターでプロジェクトファイルを編集（または、 Visual Studio でアンロード、編集、および再読み込み）します。

MSBuild コンポーネントディレクトリはコンピューターによって異なる可能性があるため、ディレクトリのパスを示す DotfuscatorMSBuildDir プロパティを設定することをお勧めします。詳細については、複数の環境の処理を参照してください。
ターゲットをインポートするには、プロジェクトファイルの 終わり で <Project> タグを閉じる直前に次の行を追加します。
```
<Import Project="$(DotfuscatorMSBuildDir)/PreEmptive.Dotfuscator.Common.targets"/>
```

.NET Core と .NET Standard で導入された新しい SDK ベースのフォーマットをプロジェクトで使用する場合は、SDK のターゲットの後に Dotfuscator のターゲットがインポートされるようにするため、ルートの <Project> 要素の Sdk 属性を明示的なインポートに置き換えることも必要になります。たとえば、以下のようなプロジェクトがあるとします。

<Project Sdk="Microsoft.NET.Sdk">

  <!-- その他のタグ（手順 1 以降の説明にあるタグなど） -->

  <Import Project="$(DotfuscatorMSBuildDir)/PreEmptive.Dotfuscator.Common.targets"/>
</Project>

これを次のように更新します。

<Project> <!-- Sdk 属性を除去 -->

  <!-- 次のインポートを追加 -->
  <Import Project="Sdk.props" Sdk="Microsoft.NET.Sdk" />

  <!-- その他のタグ（手順 1 以降の説明にあるタグなど） -->

  <!-- 次のインポートを追加 -->
  <Import Project="Sdk.targets" Sdk="Microsoft.NET.Sdk" />

  <Import Project="$(DotfuscatorMSBuildDir)/PreEmptive.Dotfuscator.Common.targets"/>
</Project>

新しい 2 つの <Import> タグで設定される Sdk 属性の値は、元の <Project> タグにあった Sdk 属性の値と同じであることを確認してください。

ターゲットのプロパティの設定

ターゲットを制御する MSBuild プロパティは、プロジェクトファイルにおいて、ターゲットの import ステートメントより前に宣言しておく必要があります。このセクションでは、よく使われるプロパティについて説明します。詳細な一覧については、利用可能なプロパティを参照してください。

DotfuscatorEnabled

既定では、ビルド中に Dotfuscator は実行されません。明示的に実行するには、次のように DotfuscatorEnabled プロパティを true に設定します。

<PropertyGroup>
  <DotfuscatorEnabled>true</DotfuscatorEnabled>
</PropertyGroup>

しかし、Release などの特定の構成のみを Dotfuscator で保護したいでしょう。特定の構成のみを保護するには、次のように DotfuscatorEnabled の Condition を指定します。

<PropertyGroup>
  <DotfuscatorEnabled Condition="'$(Configuration)' == 'Release'">true</DotfuscatorEnabled>
</PropertyGroup>

Xamarin.iOS アプリケーションの場合のように複数の構成を保護するには、次のように構成ごとに異なる Condition を使って繰り返し定義を行います。

<PropertyGroup>
  <DotfuscatorEnabled Condition="'$(Configuration)' == 'Release'">true</DotfuscatorEnabled>
  <DotfuscatorEnabled Condition="'$(Configuration)' == 'Ad-Hoc'">true</DotfuscatorEnabled>
  <DotfuscatorEnabled Condition="'$(Configuration)' == 'AppStore'">true</DotfuscatorEnabled>
</PropertyGroup>

あるいは、DotfuscatorEnabled をこのプロパティ独自の <PropertyGroup> に宣言するのではなく、構成と対象プラットフォームに基づいて既に選択されている既存のグループの中で宣言することもできます。たとえば、次のように記述します。

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
  <DebugType>pdbonly</DebugType>
  <Optimize>true</Optimize>
  <OutputPath>bin/Release/</OutputPath>
  <!-- ...他のプロパティ... -->

  <!-- Release|AnyCPU に対して Dotfuscator を有効にします -->
  <DotfuscatorEnabled>true</DotfuscatorEnabled>

</PropertyGroup>

この方法を選択する場合は、構成の対象プラットフォームのすべてについて DotfuscatorEnabled を設定することを忘れないでください。たとえば、Release 構成を保護したい場合は、Release|AnyCPU、Release|x86、Release|iPhone などの <PropertyGroup> セクションに DotfuscatorEnabled を設定してください。

DotfuscatorGenerateConfigFileIfMissing

Dotfuscator で保護を行うには、構成ファイル（既定の名前は DotfuscatorConfig.xml）が必要です。このファイルは、Dotfuscator の MSBuild ターゲットを設定する際に、生成されるようにする必要があります。そうするには、次のように DotfuscatorGenerateConfigFileIfMissing プロパティを true に設定します。

<PropertyGroup>
  <DotfuscatorGenerateConfigFileIfMissing>true</DotfuscatorGenerateConfigFileIfMissing>
</PropertyGroup>

ただし、構成ファイルの生成後（つまり、最初のビルドの完了後）は、この機能を無効にすることで、特定の種類のビルドエラーを回避する必要があります。

最初のビルド

ターゲットをインポートして必要なプロパティを設定したら、Visual Studio または MSBuild コマンドラインを使ってプロジェクトをビルドすることができます。必ず、DotfuscatorEnabled を true に設定した構成を選択してください。

初めてビルドを行うとき、DotfuscatorGenerateConfigFileIfMissing は true に設定されているものとして、Dotfuscator は新しい構成ファイルを生成し、構成ファイルを生成した旨の警告を出力します。この警告は、構成ファイルが既に存在しているはずの後続のビルドでビルドエラーが発生する可能性を通知するためのものなので、最初のビルドでは無視してください。

ビルドを行うたびに、Dotfuscator により、プロジェクトの出力ディレクトリ（bin/Release など）にあるアセンブリに保護が適用されます。どのアセンブリが保護されるのかの詳細な例については、保護するプロジェクトの選択を参照してください。

また、Dotfuscator では、ビルドの一環としてレポートファイルも作成されます。

ビルドが完了したら、それをローカルで実行して、引き続き期待どおりに動作することを確認できます。

メモ： ビルドやランタイムの問題を診断する方法については、トラブルシューティングを参照してください。

構成ファイルについて

Dotfuscator では、構成ファイルを使って、さまざまな保護設定を制御します。

既定では、構成ファイルはプロジェクトディレクトリに DotfuscatorConfig.xml として保存されます。構成ファイルのパスを変更するには、プロジェクトファイル内の DotfuscatorConfigPath プロパティを設定します（構成ファイルが古いパスに既に生成されている場合は、設定を保持するため、そのファイルを新しいパスに移動する必要があります）。

最初のビルドでは、Dotfuscator により、既定のレベルの保護を提供する構成ファイルが生成されます。 Dotfuscator では、後続のビルドの一環として、ソリューション内のプロジェクト参照に関するすべての変更が構成ファイルに反映されます。

Dotfuscator の保護をカスタマイズして強化するには、Dotfuscator 構成エディターを使って構成ファイルを編集します。詳細な例については、保護の強化を参照してください。

構成ファイルはビルド処理への入力になります。以下を行う必要があります。

このファイルをバージョン管理の対象にする。これにより、ビルドエージェントと同僚のチームメンバーが同じ保護設定を使ってプロジェクトをビルドできるようになります。構成ファイルに対するチームの変更、したがって保護設定を、時系列で追跡できるようにもなります。
構成ファイルの生成を無効にする。 Dotfuscator は、ビルド時に構成ファイルが見つからない場合には、自動的に構成ファイルを生成します。これは最初のビルドで役に立ちますが、この機能を後続のビルドにも有効のままにしておけば、構成ファイルがない場合でも、それら後続のビルドが成功するようになります。構成ファイルを誤って削除した場合は、ビルドが、カスタマイズした保護設定でなく、既定の設定でのみ保護されることになります。

構成ファイルの生成機能を無効にすることで、構成ファイルがない場合にはビルドが失敗するようにするには、プロジェクトファイルを編集して次のプロパティを false に変更します。
```
<DotfuscatorGenerateConfigFileIfMissing>false</DotfuscatorGenerateConfigFileIfMissing>
```
構成ファイルは、決して組織の外部に配布しない。ソースコードの要素の名前など、機密性の高い情報は、構成ファイルに記述することができます。

最後に留意すべき点は、Visual Studio のソリューションエクスプローラーにおいて、構成ファイルはプロジェクトノードの下に表示されるということです。このように表示されるのは、MSBuild ターゲットが構成ファイルを MSBuild 項目としてプロジェクトに追加するからです。これにより、Visual Studio がプロジェクトをビルドすべきかどうかを判断するときに、構成ファイルへの変更が考慮されるようになります。

レポートファイルについて

Dotfuscator は、ビルドの一環として実行されるたびに、さまざまなレポートファイルを生成します。保護設定に応じて、以下のレポートファイルが生成されます。

Renaming.xml：名前の変更レポートファイル。名前変更の割り当てファイルとも呼ばれます。
Removal.xml：除去レポートファイル。
SmartObfuscation.xml：スマート難読化レポートファイル。

既定では、これらのレポートはプロジェクトの DotfuscatorReports サブディレクトリに格納されます。レポートファイルのパスを変更するには、構成エディターの［設定］タブを使って構成ファイルを編集します。

メモ： MSBuild ターゲットは、Dotfuscator を呼び出す際、現在のビルド構成およびプラットフォームに対応する、configuration および platform という Dotfuscator プロパティの値を渡します。これらの値をカスタムレポートファイルのパスの一部として使用することで、異なるビルド構成およびプラットフォームのレポートを別々に保持することができます。

レポートファイルは、（bin ディレクトリにある）アセンブリ自体と同様にビルドの出力です。以下を行う必要があります。

レポートファイルをバージョン管理の対象から除外する。レポートファイルはビルドの一環として Dotfuscator を実行するたびに更新されるため、DotfuscatorReports サブディレクトリをバージョン管理の対象から除外する必要があります。
レポートファイルは、アプリケーションをリリースする際に、バージョン管理されている安全な場所にアーカイブする。 Dotfuscator の名前の変更による難読化を有効にすると、アプリケーションのスタックトレースには難読化された型名とメソッド名が格納されます。これは、カスタマーによって報告された問題の診断を難しくする可能性があります。

このような状況を解決するため、Dotfuscator が生成するレポートの 1 つ、名前変更の割り当てファイルでは、名前変更された各コード要素がその要素の元の名前に関連付けられます。このファイル（とその他のレポート）は、アプリケーションをリリースする際に、安全な場所にコピーしてください。次に、カスタマーから難読化されたスタックトレースを渡されたら、それとアーカイブした割り当てファイルを難読化されたスタックトレースを復号する Dotfuscator ツールに渡すことで、元のソースコードに対応するスタックトレースが生成されるようにします。
レポートファイルは、決して組織の外部に配布しない。 Dotfuscator を持っていないユーザーでも、これらのレポート内の情報を使って、Dotfuscator の保護の一部を元に戻すことができるためです。

後続のビルド

プロジェクトを一度ビルドし、次いで構成ファイルとレポートファイルを推奨事項どおりに構成したら、引き続き、プロジェクトをローカルでビルドすることができます。また、自身の変更内容をチームのバージョン管理にプッシュすると、自動ビルドシステムから保護されたビルドが開始されるようになります。

引き続き、Dotfuscator の保護を使ってアプリケーションを開発、テストすることができます。また、保護を強化することもできます。

MSBuild タスク

Dotfuscator には、カスタマイズされた MSBuild プロジェクトから呼び出すことのできる MSBuild タスクも用意されています。最もよく使われるタスクは Dotfuscate タスクで、これは Dotfuscator を呼び出して、既存の Dotfuscator 構成ファイルで指定された保護を実行します。

タスクおよび関連するパラメーターの一覧については、MSBuild タスクリファレンスを参照してください。

Dotfuscate タスクの参照

Dotfuscator MSBuild タスクライブラリ PreEmptive.Dotfuscator.Tasks.dll は、MSBuild コンポーネントディレクトリにあります。このタスクは PreEmptive.Tasks 名前空間に公開されます。

MSBuild プロジェクトで Dotfuscate タスクを参照して使用できるようにするには：

MSBuild コンポーネントディレクトリはコンピューターによって異なる可能性があるため、ディレクトリのパスを示す DotfuscatorMSBuildDir プロパティを使用することをお勧めします。詳細については、複数の環境の処理を参照してください。
以下のコードを、プロジェクトファイルのルートの <Project> 要素の子として追加します。追加する場所は DotfuscatorMSBuildDir プロパティが定義された後で、かつ Dotfuscate タスクを使用するターゲットの前である必要があります。
```
<UsingTask TaskName="PreEmptive.Tasks.Dotfuscate"
           AssemblyFile="$(DotfuscatorMSBuildDir)/PreEmptive.Dotfuscator.Tasks.dll" />
```
バージョンが 15.0 より前の MSBuild を使用する場合は、$(DotfuscatorMSBuildDir)/ を $(DotfuscatorMSBuildDir)/legacy/ に置き換えてください。既定の "最新" タスクと "従来" タスクの違いの詳細については、MSBuild タスクリファレンスを参照してください。

Dotfuscate タスクの呼び出し

Dotfuscate タスクを参照できるようにしたら、このタスクをカスタマイズした MSBuild ターゲットから呼び出すことができます。簡単な例として、C# プロジェクトにおける次の AfterBuild ターゲットについて考えましょう。

<Target Name="AfterBuild">

  <Dotfuscate ConfigPath="MyDotfuscatorConfig.xml" License="$(DotfuscatorLicense)">
    <Output
        TaskParameter="OutputAssemblies"
        ItemName="MyDotfuscatorOutputAssemblies" />
  </Dotfuscate>

  <Message
    Importance="high"
    Text="Dotfuscator wrote: @(MyDotfuscatorOutputAssemblies)" />

</Target>

この AfterBuild 宣言は、MSBuild によってあらかじめ定義されたターゲットをオーバーライドします。このため、MSBuild は通常のビルドステップを実行した後でターゲットを実行します。

ここでは、まずターゲットから Dotfuscate タスクを呼び出します。 3 つのタスクパラメーター（入力用に 2 つ、出力用に 1 つ）を指定します。

必須の入力パラメーター ConfigPath を MyDotfuscatorConfig.xml に設定します。プロジェクトディレクトリにあるこの Dotfuscator 構成ファイルに指定した保護が、Dotfuscator によって実行されます。
オプションの License 入力パラメーターを DotfuscatorLicense MSBuild プロパティの値に設定します。このプロパティを .dotfuscator.user.props ファイルで指定した場合は、そのファイルを、Dotfuscate を使用する前にプロジェクトへインポートしておいてください。次に例を示します。
```
<Import Project="$([System.Environment]::GetFolderPath(SpecialFolder.UserProfile))/.dotfuscator.user.props" 
        Condition="Exists('$([System.Environment]::GetFolderPath(SpecialFolder.UserProfile))/.dotfuscator.user.props')"/>
```
このプロパティが設定されると、Dotfuscator は実行時に自身でアクティブ化します。このプロパティを設定しない場合は、別の方法でアクティブ化する必要があります。
出力パラメーター OutputAssemblies 内の MSBuild 項目が MyDotfuscatorOutputAssemblies という MSBuild 項目セットとして保存されるように指定します。この出力パラメーターには、Dotfuscator によって書き込まれた、アセンブリの絶対パスが出力されます。

次に、ターゲットから Message タスクを呼び出すことで、Dotfuscator によって書き込まれたパスを記録します。

パラメーターの一覧については、Dotfuscate タスクを参照してください。

非推奨の MSBuild ターゲット

警告： これらの MSBuild ターゲットの使用は現在推奨されておらず、今後の Dotfuscator のバージョンからは削除されます。新しい MSBuild ターゲットまたは MSBuild タスクを使用してください。

既存のプロジェクトとの互換性のため、Dotfuscator では PreEmptive.Dotfuscator.targets ファイルに別の MSBuild ターゲットセットが定義されています。これらのターゲットは既存の Visual Studio または MSBuild プロジェクトに簡単に統合できるようには設計されていないため、新しい方の MSBuild ターゲットを使って Dotfuscator をプロジェクトに統合するか、ご自身のターゲットから該当する MSBuild タスクを呼び出すことをお勧めします。