ビルド エージェントの考慮事項
開発チームの多くは、ソフトウェアのビルドに、継続的インテグレーションと継続的デリバリー(CI/CD)パイプライン、あるいは他の自動ビルド システムを用いています。 クラウド サービスとしても、オンプレミス製品としても、さまざまなソリューションが存在しております。 代表例としては、Jenkins、TeamCity、および Azure Pipelines(クラウドでホストされている Azure DevOps サービスとオンプレミスの Azure DevOps サーバーの両方で利用でき、正式には Microsoft Team Foundation Server または TFS と呼ばれています)があります。
このようなシステムは独立したコンピューターを使用してビルド手順を実行します。 これらのコンピューターは通常「ビルド エージェント」と呼ばれますが、システムによっては「ノード」や「エグゼキュータ」と呼ばれることがあります。このドキュメントでは当用語について「ビルド エージェント」を使用します。 ビルド エージェントの多くは仮想マシンですが、専用の「ビルド ファーム」にまとめられることもあります。
Dotfuscator はビルド エージェントで動作するように設計されていますが、Dotfuscator の設定、アクティブ化、および使用には考慮すべき点がいくつかあります。
Dotfuscator の設定方法
ビルド エージェントのプロビジョニング方法によって、それらのエージェントにおける Dotfuscator の最適な設定方法が決まります。
長時間にわたって実行されるビルド エージェントを既にプロビジョニングしており、ビルド ジョブ間で再利用する場合は、各ビルド エージェントに Dotfuscator を Windows インストーラー(.msi
)でインストールするのが最も簡単かもしれません。
これにより、Dotfuscator のインストレーションをビルド エージェントと開発用コンピューターで一致させることができ、構成が簡単になります。
詳細については、Windows インストーラーを使用した Dotfuscator のプロビジョニングを参照してください。
一般のクラウド ホストのビルド サービスと同じように、ビルド エージェントがビルド プロセスの一部として動的にプロビジョニングされている場合、そのエージェントでは Windows インストーラーを使用することができないか、または不都合となる可能性があります。 例として、Microsoft がホストするエージェントで Azure Pipelines を使用する場合、プロジェクトは Microsoft が "新規作成" 状態で割り当てた仮想マシン上に構築されます。 このような場合は、Dotfuscator を通常どおりにインストールすることはできません。代わりに、Dotfuscator のプライベート NuGet パッケージを使用してビルド エージェントへのインストールを自動化する必要があります。 詳細については、NuGet パッケージを使用した Dotfuscator のプロビジョニングを参照してください。
Windows インストーラーを使用した Dotfuscator のプロビジョニング
管理者アクセス権を持つビルド エージェントに Dotfuscator をインストールするには、通常のインストール手順に従ってください。
Dotfuscator の使用方法によっては、プロジェクトおよびビルド スクリプトを更新する必要があります。
Dotfuscator を MSBuild コンポーネント経由で使用する場合(アプリケーションの保護手順に従う場合など)は、変更を加える必要はありません。 これは、Dotfuscator が常にその MSBuild コンポーネントを MSBuild 拡張ディレクトリのサブディレクトリにインストールし、プロジェクト ファイルが既知の MSBuild プロパティ
$(MSBuildExtensionsPath)
を使用して拡張ディレクトリを参照するからです。Dotfuscator のコマンド ライン インターフェイスを使用している場合は、プロジェクト ファイルやビルド スクリプトが環境変数
DOTFUSCATOR_HOME
を使用して参照していることを確認してください。 この変数は、dotfuscator.exe
を含むディレクトリを指します。
これらの変更を加えると、保護するアプリケーションを開発用コンピューターとビルド エージェントでビルドできるようになります。
NuGet パッケージを使用した Dotfuscator のプロビジョニング
PreEmptive Solutions は、Dotfuscator Professional をお使いのお客様に NuGet パッケージを提供します。 NuGet を使用して nuget.org からサードパーティのライブラリをプロジェクトに追加することには慣れているかもしれませんが、Dotfuscator NuGet パッケージはまったく異なる動作をします。
このパッケージは、一般的なプログラミング用にライブラリを公開していません。 代わりに、このパッケージにはビルド時に独立したツールとして使用できる Dotfuscator のさまざまなコンポーネントが含まれています。
プロジェクトに Dotfuscator NuGet パッケージへの参照を追加しません。 代わりに、ビルドの一部として明示的にパッケージをインストールします。 その後、プロジェクトとビルド スクリプトを編集して、このローカルの Dotfuscator を使用することができます。
このパッケージは、パブリック nuget.org フィードでは利用できません。 代わりに、パッケージは PreEmptive Solutions からプライベートで配布され、組織内のプライベート フィードでホストされる必要があります。
Dotfuscator NuGet パッケージは、従来の Windows インストーラーに代わるものとして提供されており、動的にプロビジョニングされたビルド エージェントで使用するために設計されています。 自動ビルド システムによって、パッケージをビルド ジョブの一部としてインストールさせることができます。 これにより、ビルド プロセスの一環としてプロビジョニングされた仮想マシンなど、Windows インストーラーを実行できないコンピューターでも Dotfuscator を使用できます。
以下のサブセクションでは、NuGet パッケージをホスト、インストール、および使用する方法について説明します。
NuGet パッケージの入手
Dotfuscator NuGet パッケージを入手するには:
Dotfuscator のダウンロード用 Web ページで、Dotfuscator Professional をダウンロードします。 ダウンロードするにはログインが必要です。
ダウンロードしたいバージョンを見つけて、Dotfuscator NuGet パッケージを選択します。 ブラウザーで
.nupkg
ファイルがダウンロードされます。
プライベート フィードで NuGet パッケージをホストする
ビルド エージェントがアクセスできる場所で Dotfuscator NuGet パッケージをホストする必要がありますが、この場所にアクセスできるのはあなたの組織のメンバーだけです。 そのために、あなた自身の NuGet フィードを作成することができます。 以下に例をいくつか挙げます。
クラウドでホストされている Azure Artifacts やオンプレミス バージョンの Artifactory など、NuGet をサポートするプライベートな専用の artifact リポジトリにパッケージをアップロードします。 パッケージをホストするには、artifact リポジトリのユーザー ドキュメントを参照してください。 クラウドホスティング リポジトリを使用している場合は、パッケージが組織外から見えないようにする必要があります。
ビルド エージェントからアクセスできる共有ネットワーク(
\\my_server\nuget
など)のディレクトリにパッケージを配置します。 このディレクトリはローカルの NuGet フィードとして機能します。ローカル NuGet フィードとしても機能するディレクトリで、パッケージをソース コード ツリーに追加します。
これは、NuGet クライアントが、抽出した NuGet パッケージを復元後に保持するために生成する
packages
ディレクトリと混同しないようにしてください。 対照的に、ローカル フィードとして機能するディレクトリには、.nupkg
ファイルしか含まれていません。.nupkg
ファイルは既定でソース管理システムから除外されるかもしれません(たとえば、Git の.gitignore
など)。 Dotfuscator NuGet パッケージをソース ツリーに追加するには、そのような除外をオーバーライドする必要があります(Git の場合は、git add
コマンドに--force
フラグを付ける)。
この NuGet パッケージは、Dotfuscator Professional を使用する権利を持つ組織内での使用のみを目的としています。
NuGet パッケージのインストール
nuget install
コマンドを使用して、Dotfuscator をビルド エージェントのローカル ディレクトリにインストールできます。
このコマンドをカスタム ビルドのステップで実行すれば、その後のビルド ステップで Dotfuscator のさまざまなコンポーネントを使用できます。
コマンドの例を次に示します。
nuget install -OutputDirectory "<install dir>" -ExcludeVersion PreEmptive.Protection.Dotfuscator.Pro -Source "<source url>"
ここで、
<install dir>
は、Dotfuscator をインストールするディレクトリです。 これは、プロジェクトのルート ディレクトリへの相対パスなど、後のビルド ステップで使用する周知の場所である必要があります。<source url>
は、以前に設定したプライベート フィードの NuGet エンドポイント URL です。 専用のアーティファクト リポジトリの場合は、次の(架空の)Azure Artifacts エンドポイントなど、リポジトリによって公開されるエンドポイント URL を使用します。https://pkgs.dev.azure.com/YourOrgName/_packaging/YourFeedName/nuget/v3/index.json
ローカル ファイル システム フィードの場合は、次のようにディレクトリ パスを使用します。
\\my_server\nuget
プロジェクトにパッケージを参照追加して暗黙的にしたり、nuget restore
を使用してパッケージを復元するのではなく、Dotfuscator NuGet パッケージを上記のように明示的にインストールすることをお勧めします。
nuget install
を使用すると、プロジェクトの依存関係の復元方法やインストールされた Dotfuscator のバージョンによって異なる可能性がある場所ではなく、後のビルド ステップで Dotfuscator のコンポーネントを既知の場所で参照できます。
これにより、アプリケーション保護の指示に従った場合など、 MSBuild コンポーネントの使用時のエラーも防ぎます。
ビルド エージェントでの Dotfuscator アクティブ化
Dotfuscator をビルド エージェントで実行するには、ライセンス キーを入力して Dotfuscator をアクティブ化 する必要があります。
NuGet パッケージを使用する場合は、自動ビルド プロセスの一環として、DOTFUSCATOR_LICENSE
環境変数をライセンス キーに設定することをお勧めします。
多くのビルド サービスでは、ビルドの有効期間中に設定される環境変数を設定できます。
他のサービスでは、ビルドの前後にそれぞれカスタム ビルド ステップとして環境変数を設定したりクリアしたりできます。
または、Dotfuscator を使用するときにライセンス キーを引数として指定できます。
たとえば、MSBuild を用いたアプリケーションの保護手順を使用している場合、ソリューションを構築するために MSBuild を呼び出すときに、MSBuild プロパティの DotfuscatorLicense
を設定することによってライセンス キーを提供できます。
msbuild YourSolution.sln /p:DotfuscatorLicense=<license key> <other MSBuild arguments>
どちらの場合も、ライセンス キーを保護するための措置を講じてください。 ビルド システムによっては、パスワードやその他の機密情報を保持するための資格情報ストアを提供しています。これを使ってライセンス キーを保存できます。 たとえば、Azure Pipelines では、ソース コードに格納されず、ビルド ログからマスクされているシークレット変数を宣言する機能を提供します。 Dotfuscator 自体は、ライセンス キーの最後の 4 桁を除くすべてをテキスト形式のビルド出力でマスクします。
ライセンス サーバーの保守
アクティブ化サーバーが計画メンテナンス中のために利用できない場合、Dotfuscator はビルド エラーを回避するために接続を複数回実行します。 既定では、Dotfuscator は最長 30 分間にわたり 30 秒ごとに接続を再試行します。
接続の再試行の間隔(遅延)およびタイムアウトの値はそれぞれ、DOTFUSCATOR_MAINTENANCE_RETRY_DELAY
および DOTFUSCATOR_MAINTENANCE_RETRY_TIMEOUT
環境変数を使用して設定することができます。
DOTFUSCATOR_MAINTENANCE_RETRY_DELAY
変数には、接続の再試行の間隔(秒単位)を設定します。
DOTFUSCATOR_MAINTENANCE_RETRY_TIMEOUT
変数には、接続エラーになるまでの再試行期間(分単位)を設定します。
どちらの値も正の整数値で設定する必要があります。
NuGet パッケージの使用
NuGet パッケージをインストールすると、Dotfuscator のコンポーネントは <install dir>\PreEmptive.Protection.Dotfuscator.Pro\tools
に配置されます。
このディレクトリは、次のようにさらにサブディレクトリに分けられます。
programdir
には通常、Dotfuscatorのインストール場所にあるコンポーネント(コマンド ライン インターフェイスなど)が含まれています。msbuilddir
には通常、Dotfuscator の MSBuild 拡張パスにある MSBuild コンポーネントが含まれています。
Windows インストーラーがコンポーネントを配置する通常のディレクトリではなく、これらのディレクトリにあるコンポーネントを使用するようにビルドを更新する必要があります。
PreEmptive.Protection.Dotfuscator.Pro
の代わりに、PreEmptive.Protection.Dotfuscator.Pro.Eval
を使用してください。
アプリケーションの保護の主な手順を使用している場合、変更されたプロジェクト ファイルは、既定では、Windows インストーラーが通常配置する場所から Dotfuscator の MSBuild ターゲットをインポートしようとします。
ビルド エージェントでプロジェクトの MSBuild を呼び出すときに DotfuscatorMSBuildDir
プロパティを設定して、この場所をオーバーライドする必要があります。
msbuild YourSolution.sln /p:DotfuscatorMSBuildDir="<install dir>\PreEmptive.Protection.Dotfuscator.Pro\tools\msbuilddir" <other MSBuild arguments>
代替のアプローチの場合は、プロジェクトをコンパイルした後のカスタム ビルド ステップの一部として Dotfuscator を呼び出します。
次のように、NuGet を介してインストールされたコンポーネントを使用するには、これらのビルド ステップを更新する必要があります。<install dir>
は nuget install
コマンドの -OutputDirectory
引数に使用されるディレクトリです。
Dotfuscate
MSBuild タスクを含むアセンブリは、次の場所にあります。<install dir>\PreEmptive.Protection.Dotfuscator.Pro\tools\msbuilddir\PreEmptive.Dotfuscator.Tasks.dll
コマンド ライン インターフェイスは次の場所にあります。
<install dir>\PreEmptive.Protection.Dotfuscator.Pro\tools\programdir\dotfuscator.exe
Dotfuscator Azure Pipelines Extension を使用している場合は、Location of Dotfuscator アプリケーション フィールド(または、YAML 構文では
dotfuscatorHome
入力値)を次のように設定します。<install dir>\PreEmptive.Protection.Dotfuscator.Pro\tools\programdir
メモ: このパスは絶対パスである必要があります。 Azure Pipelines の既定の作業ディレクトリの絶対パスを取得するには、プロパティ$(System.DefaultWorkingDirectory)
を使用します。
開発者環境での作業
NuGet パッケージをインストールし、それを使用するようにプロジェクトとビルド スクリプトを更新すると、ビルド エージェントはアプリケーションをビルドして Dotfuscator の保護を適用できるようになります。
ただし、開発者のコンピューターがこれらのプロジェクトとスクリプトも使用している場合は、追加の変更が必要になることがあります。 これは、開発者のコンピューターが Windows インストーラーで Dotfuscator をインストールするからです。 NuGet パッケージと Windows インストーラーのどちらでも、ほとんど同じコンポーネントが展開されますが、インストール場所やシステム全体の環境変数などの要因によって環境間に違いが生じる可能性があります。
たとえば、Visual Studio プロジェクト ファイルが Dotfuscate
タスクを使用している場合、そのプロジェクトには、タスクを保持しているアセンブリのディスク上の場所を指定する <UsingTask>
ディレクティブ を含める必要があります。
この場所は、Dotfuscator のインストール方法によって異なります。
プロジェクトは、Visual Studio で開かれたときのエラーを回避するために、両方の可能性に対応する必要があります。
DotfuscatorMSBuildDir
プロパティの有無に基づいて、プロジェクト ファイルは既に両方の種類の環境に対応しています。
この場合、Dotfuscator を開発者環境で機能させるために変更を加える必要はありません。
開発者環境とビルド環境の両方で、共有プロジェクトとビルド スクリプトを Dotfuscator と連携させるために考えられる方法は次のとおりです。
Dotfuscator のパスをプロジェクトとビルド スクリプトに渡してください。 通常は、コンポーネントが配置される場所は Windows インストーラーによる既定の場所とし、自動ビルド システムに NuGet のインストールを指すパスを上書きさせる必要があります。 これにより開発者は、ビルド エージェントには NuGet パッケージを使用させながら、プロジェクトでの作業を通常どおり続行することができます。
この方法の例として、Dotfuscator の MSBuild ターゲットをインポートするアプリケーションの保護での手順を考えてください。 以下は、Visual Studio プロジェクト ファイルへの追加に関連する行の抜粋です。
<PropertyGroup> <DotfuscatorMSBuildDir Condition="'$(DotfuscatorMSBuildDir)' == ''">$(MSBuildExtensionsPath)\PreEmptive\Dotfuscator\4</DotfuscatorMSBuildDir> </PropertyGroup> <Import Project="$(DotfuscatorMSBuildDir)\PreEmptive.Dotfuscator.Common.targets" />
まず、MSBuild プロパティ
DotfuscatorMSBuildDir
が、まだ設定されていない場合は、Windows インストーラーによる Dotfuscator の MSBuild コンポーネントの場所に設定されます。 次に、このプロパティを<Import>
タグで使用して、ターゲット ファイルを保持しているディレクトリを指定します。MSBuild が呼び出された時点でこのプロパティが設定されている場合は、Windows インストーラーによる配置場所ではなくそのディレクトリのパスが使用されます。 Dotfuscator NuGet パッケージを使用してプロジェクトをビルドするときに、このプロパティを明示的に指定する必要があるのはこのためです。指定していない場合は、ターゲットはビルド エージェント上のその場所にないため、 Windows インストーラーによる既定の場所が使用され、ビルドは失敗します。
この方法を変更するには、両方のパス セットをプロジェクトとビルド スクリプトでハードコードし、自動ビルドで設定されたフラグに基づいてどちらのセットを使用するかを選択します。
開発者のコンピュータでは、Windows インストーラーの代わりに NuGet パッケージを使用してください。 これにより、開発者環境とビルド エージェントが一致し、プロジェクトとビルド スクリプトが一貫した単一の場所で Dotfuscator を参照できるようになります。
ただし、この方法には多くの影響があります。
パッケージが同じ場所にインストールされるようにするには、
nuget install
コマンドをビルド時と同じ引数で実行する必要があります。 ビルドが依存する特定のコマンドを含むバッチ ファイルまたはスクリプトを作成することをお勧めします。こうすることで、開発者は引数を入力しなくても簡単にコマンドを実行できます。Visual Studioは、
nuget install
コマンドが実行されるまで、MSBuild コンポーネントを参照するプロジェクト(推奨されるアプリケーションの保護の手順に従って変更されたコンポーネントなど)を開くことができません。Dotfuscator をビルドの一部として正常に実行するには、開発者が
nuget install
を実行する必要があります。通常、開発者は環境変数を設定することで Dotfuscator をアクティブ化 しておく必要があります。これで、Dotfuscator をビルドの一部として正常に実行させることができます。
構成エディターに対する、スタート メニューのショートカットはありません。 代わりに、開発者は NuGet パッケージのインストール場所で
programdir\dotfuscatorUI.exe
を実行する必要があります。環境変数
DOTFUSCATOR_HOME
は自動的に設定されず、Dotfuscator の実行可能ファイルは PATH 上にありません。 代わりに、Dotfuscator のコンポーネントは NuGet パッケージのインストール場所に基づいて明示的に参照される必要があります。
開発者のコンピュータには、Windowsインストーラーに加えて NuGet パッケージを使用してください。 これは前の方法と似ていますが、開発者が Dotfuscator を Windows インストーラーでもインストールするという点が異なります。 Dotfuscator のインストレーションは、インストールされた NuGet パッケージと同時に存在します。
この方法では、NuGet パッケージ インストールの Dotfuscator コンポーネントを参照するので、開発者はプロジェクトとビルド スクリプトを機能させるために、依然として
nuget install
を実行する必要があります。 結果として、この方法には、前の方法の影響 1、2、および 3 が残ります。ただし、Windows インストーラーを使用すると、スタート メニューのショートカットが追加され、環境変数の
DOTFUSCATOR_HOME
が設定されます。 開発者は、インストール中またはスタート メニューから Config Editor(構成エディター)を実行しているときに Dotfuscator をアクティブ化できます。 これにより、影響 4、5、および 6 が軽減します。
この方法を適用したら、それをチーム全体にも一貫して適用し、Dotfuscator が開発者環境および自動ビルドの一部の両方で実行されることをテストします。