ASP.NET マージ ツール (Aspnet_merge.exe)
更新 : 2007 年 11 月
ASP.NET マージ ツール (Aspnet_merge.exe) を使用すると、ASP.NET コンパイル ツール (Aspnet_compiler.exe) で作成したアセンブリを結合および管理することができます。ASP.NET マージ ツールは、ASP.NET Version 2.0 以降で作成したアセンブリに対応しています。
ASP.NET コンパイル ツールでは、アプリケーションを配置用にプリコンパイルできます。このツールでは、ターゲット Web サイトのコンテンツ フォルダごとに 1 つのアセンブリを作成することも、コンテンツ ファイルごとに 1 つのアセンブリを作成することも可能です。ASP.NET マージ ツールによって、配置やリリース管理での柔軟性が高まります。ASP.NET マージ ツールでは次のタスクを実行できます。
Web サイト全体に対応する 1 つのアセンブリを作成します。
Web サイト フォルダごとに 1 つのアセンブリを作成し、アセンブリ名にプレフィックスを追加します。
Web サイトのユーザー インターフェイス (UI) 要素 (ページやコントロールなど) のみを対象とする 1 つのアセンブリを作成します。
aspnet_merge [-?]
applicationPath
[-keyfile filename [-delaysign]]
[-o assemblyname | -w assemblyname | -prefix prefix]
[-copyattrs [assemblyfile]]
[-debug]
[-nologo]
[-errorstack]
[-r]
[-xmldocs]
[-a]
[-logfile logfile]
[-allowattrs textfile]
引数
引数 |
説明 |
|---|---|
applicationPath |
(必須) 作成するアセンブリの対象となるアプリケーションがあるフォルダの名前を指定します。これが既定のマージ操作です。この引数を指定すると、fixednames コンパイラ オプションを指定した場合より生成されるアセンブリの数が少なくなります。 |
オプション
オプション |
説明 |
||
|---|---|---|---|
-keyfile filename |
コンパイル済みのアセンブリに AssemblyKeyFileAttribute 属性を適用することを指定します。この属性は、厳密な名前の生成に使用される公開キーと秘密キーのペアが含まれるファイルの名前を指定します。 入力アセンブリに署名が付いていて、マージ ツールがアセンブリに署名しない場合は、キーが削除されていることを示す警告メッセージが表示されます。 キー ファイル名を指定せず、公開キーを持つアセンブリと持たないアセンブリの両方を対象とした場合、マージ ツールの実行は失敗します。 |
||
-delaysign |
生成されたアセンブリに AssemblyDelaySignAttribute 属性を適用することを指定します。この属性は、公開キーと秘密キーのペアではなく公開キー トークンでのみアセンブリに署名する必要があることを示します。 このオプションは、-keyfile オプションと組み合わせる必要があります。この属性が既にコード ファイルのアセンブリに適用されている場合、マージ ツールは例外をスローします。 delaysign オプションを使用した場合、厳密な名前の検証が有効になっていなければ、マージ ツールによって生成されたコードは署名が完了する前に実行できます。厳密な名前の検証が有効でない場合は、コードに脆弱性がなく、署名が完了するまでの間に悪意のあるユーザーから攻撃を受ける可能性がないことを確認してください。 |
||
-o assemblyname |
すべての Web UI コンテンツおよび最上位レベル アセンブリに対応する 1 つのマージされたアセンブリの名前を指定します。拡張子が .compiled であるファイルでは、参照先がこのアセンブリに変更されます (拡張子が .compiled であるファイルは、.aspx、.master、.ascx などのファイルのコンテンツからコンパイルされます)。 このオプションは、w オプションや prefix オプションと組み合わせることはできません。assemblyname パラメータは必須です。 |
||
-w assemblyname |
すべての Web UI コンテンツ (ページおよびユーザー コントロール) に対応する 1 つのマージされたアセンブリの名前を指定します。コンパイルされた .aspx、.master、および .ascx の各ファイルでは、参照先がこのアセンブリに変更されます。これによって、コードとは別に UI 要素だけを更新することができます。 ローカル リソースおよびグローバル リソースの最上位レベル アセンブリはマージされません。 このオプションは、o オプションや prefix オプションと組み合わせることはできません。assemblyname パラメータは必須です。 |
||
-prefix prefix |
アセンブリ名のプレフィックスを指定します。ルート フォルダ アセンブリの名前は prefix パラメータの値だけで構成されます。サブフォルダ アセンブリの名前は、prefix パラメータの値とサブフォルダ名で構成されます。たとえば、サブフォルダ名が Admin である場合、生成されるアセンブリの名前は prefix.Admin.dll となります。 更新できない Web サイトに対してコンパイル ツールを実行すると、コンパイルされたテーマとローカル リソースが別のアセンブリとして Bin フォルダに格納されます。更新が可能な Web サイトの場合は、コンパイルされたテーマとローカル リソースが別のアセンブリとして Bin フォルダに格納されず、アプリケーションの元のフォルダに残ります。また、更新可能なサイトの場合、.aspx、.master、および .ascx の各ファイルで参照先がこれらのファイルのフォルダに対応する新たにマージされたアセンブリに変更されます。 このオプションは、o オプションや w オプションと組み合わせることはできません。prefix パラメータは必須です。 |
||
-copyattrs assemblyfile |
マージされた 1 つまたは複数のアセンブリに指定のアセンブリと同じアセンブリ属性を割り当てることを指定します。assemblyFile を指定しなかった場合は、マージ出力に App_Code.dll 最上位レベル アセンブリが含まれていなくても、App_Code アセンブリが使用されます。マージするアセンブリと assemblyFile アセンブリの間に属性の不整合がある場合は、エラーがスローされます。a オプションを使用すると、属性の整合性チェックを省略できます。また、allowattrs を使用してチェックの対象外とする属性を指定することもできます。 整合性チェックの対象とならない属性については、この表の allowattrs オプションの説明を参照してください。 |
||
-debug |
マージされたアセンブリ内にデバッグ出力を保持することを指定します。 |
||
-nologo |
著作権メッセージが表示されないようにします。 |
||
-errorstack |
アプリケーションのコンパイルに失敗した場合にスタック トレース情報を出力することを指定します。 |
||
-r |
メイン コード アセンブリ (App_Code フォルダ内のコード) の .compiled ファイルを削除します。アプリケーションにメイン コード アセンブリへの明示的な型参照が含まれている場合は、このオプションを使用しないでください。 |
||
-xmldocs |
入力アセンブリに関連付けられた XML ドキュメント ファイルをマージします。XML ファイルはマージされたサイトの Bin フォルダに格納されます。 |
||
-a |
マージ ツールに対し、対象となるすべてのアセンブリに AllowPartiallyTrustedCallersAttribute が適用されていない場合、またはアセンブリ間で属性の不整合がある場合でも、マージを実行するように指定します。AllowPartiallyTrustedCallersAttribute は、部分信頼の呼び出し元にアセンブリへのアクセスを許可する属性であり、コンパイル ツールによるコンパイルの実行中に指定されます。
|
||
-log logfile |
メッセージを指定されたファイルに書き込みます。 |
||
-allowattrs textfile |
マージされたアセンブリの属性の整合性チェックで対象外とする属性が示されたファイルを指定します。このファイルには、各行に属性の完全修飾名または完全修飾名前空間を指定できます。名前空間を指定した場合は、その名前空間に含まれるすべての属性がチェックの対象外となります。属性または名前空間は 1 行に 1 つずつ指定する必要があります。 明示的に指定する必要のない属性もあります。以下の属性を検出した場合、マージ ツールは警告を出力して処理を続行します。 |
||
-? |
このツールのコマンド構文とオプションを表示します。 |
.gif "重要 :")
重要 :解説
ASP.NET Web アプリケーションは、埋め込み先でコンパイルすることも、運用サーバーなどの目的の場所に配置するためにプリコンパイルすることもできます。アプリケーションを埋め込み先でコンパイルすることを動的コンパイルといいます。このコンパイル方法は高速開発シナリオで役に立ちます。配置を目的としたアプリケーションのプリコンパイルには、次の 2 つの方法があります。
分離コード ファイルやマークアップ ファイルなど、すべてのソース ファイルをコンパイルし、削除します。
マークアップ ファイルをコンパイルし、更新できるように保持します。
ASP.NET マージ ツールを使用すると、Web サイトをプリコンパイルするときに、ASP.NET コンパイル ツールを単独で使用した場合より高い柔軟性が得られます。
ASP.NET マージ ツールは ASP.NET コンパイル ツールの出力をマージしてアセンブリを生成します。マージされたアセンブリを使用することにより、大規模な Web サイトのリリース管理や配置を効率化できます。ASP.NET マージ ツールには、次の 3 とおりの使い方があります。
すべての出力を 1 つのアセンブリにマージします。
各フォルダの Web UI コンテンツ (Web ページやスキンなど) をそれぞれ固有のアセンブリにマージします。
サイト内のすべての Web UI コンテンツを 1 つのアセンブリにマージします。
以降のセクションで、これらのシナリオについて説明します。ASP.NET マージ ツールの使用例については、MSDN Web サイトの「Managing ASP.NET Precompiled Output for Deployment Using the aspnet_merge.exe Command」を参照してください。
ASP.NET マージ ツールは Visual Studio Web Deployment Projects に含まれています。Visual Studio Web Deployment Projects は Visual Studio のアドインであり、ビルド構成の管理、ビルド前およびビルド後のタスクの指定、およびアセンブリのマージに利用できます。詳細については、「Using Web Deployment Projects with Visual Studio 2005」を参照してください。
アセンブリ グループ
コンパイル ツールでは、ソース ファイルおよびソース フォルダの種類によってアセンブリの作成方法が異なります。コンパイル ツールの出力は 2 つのアセンブリ グループに分類できます。マージ ツールによるマージの方法はアセンブリ グループによって異なります。
2 つのアセンブリ グループは次のとおりです。
Web UI コンテンツ アセンブリ。.aspx、.ascx、.master、.ashx、.skin、ローカル .resx などの Web UI コンテンツ ファイル (App_LocalResources フォルダ内) から生成されます。これらのアセンブリのマージ方法は、プリコンパイルされたサイトが更新可能かどうかによって異なります。サイトが更新可能かどうかはコンパイル ツールの u オプションによって決まります。コンパイルされたサイトが更新可能な場合は、サイトを再コンパイルしなくても UI コンテンツを更新できます。Web サイトが更新可能な場合は、コンテンツ ファイルが元のフォルダに残り、関連付けられているコード ファイルだけがマージされます。サイトが更新できない場合は、.ascx、.master、および .skin の各コンテンツ ファイルが元のフォルダから削除されます。ASP.NET .aspx ファイルは、コンテンツのないマーカー ファイルと置き換えられます。この場合は UI コンテンツとコードがマージされます。
最上位レベル アセンブリ。App_Code、App_GlobalResources、App_WebReferences などのアプリケーション フォルダから生成されるアセンブリです。最上位レベル アセンブリは、Global.asax などの特殊ファイルでも生成されます。最上位レベル アセンブリは必ずコンパイルされ、配置サイトの Bin フォルダに格納されます。最終的な配置サイトには、App_Code、App_GlobalResources、または App_WebReferences の各フォルダや Global.asax ファイルは存在せず、1 つまたは複数のアセンブリが Bin ディレクトリに含まれています。アセンブリの数はマージ ツールで使用されるオプションによって異なります。ユーザー定義のフォルダも常にコンパイルされます。ただし、UI コンテンツ ファイルが含まれているユーザー定義のフォルダは最終的な配置サイトに残ります。予約済みのフォルダの詳細については、「ASP.NET Web サイトのレイアウト」を参照してください。
静的コンテンツ (.css、.gif、.htm、.html、.jpg、.js などの拡張子を持つファイル) は、プリコンパイルされたディレクトリ構造の元の場所に残ります。マージ ツールを実行しても、これらのファイルが移動または変更されることはありません。
コンパイル シナリオとマージ シナリオ
ASP.NET 2.0 では、動的コンパイル、コンパイル ツールによるプリコンパイル、およびマージ ツールによるマージを組み合わせることにより、配置とリリース管理の目標を達成できます。次の表では、さまざまなコンパイル シナリオおよびマージ シナリオを示し、どのような場合にマージ ツールを使用するのかを説明します。
シナリオ |
説明 |
|---|---|
動的コンパイル (プリコンパイルなし) |
動的コンパイルは高速開発シナリオで役立ちます。Visual Studio は動的コンパイルを使用しています。F5 キーまたは Ctrl + F5 キーを押すと、作業中のページとその依存関係だけが動的にコンパイルされます。Web サイトの完全なコンパイルは行われません。 詳細については、「ASP.NET の動的コンパイルの概要」を参照してください。 |
Aspnet_compiler.exe を fixednames オプションで実行し、プリコンパイルによって Web UI コンテンツ ファイルごとに 1 つのアセンブリを作成する。 |
fixednames オプションを指定してプリコンパイルすると、ページ レベルの小さい単位でインクリメンタル更新を行い、変更されたページだけを再配置することができます。fixednames オプションと共に u オプションを使用することにより、更新可能なサイトと更新できないサイトの両方をプリコンパイルできます。fixednames オプションを使用しても、マージ ツールによるアセンブリのマージ方法には影響しません。 大規模なサイトの場合、fixednames オプションを使用すると、大量のアセンブリが生成され、リリース管理や配置に関して問題が発生することがあります。 詳細については、「ASP.NET コンパイル ツール (Aspnet_compiler.exe)」を参照してください。 |
Aspnet_merge.exe を prefix オプションで実行し、マージによって Web UI コンテンツ ファイルごとに 1 つのアセンブリを作成する。 |
この場合は、アセンブリを UI コンテンツ フォルダ レベルで制御できます。このシナリオは、fixenames オプションなしでコンパイル ツールを使用する場合と似ています。相違点として、マージ ツールを使用した方が、ルート フォルダやユーザー定義のコンテンツ フォルダから派生する、最終的なアセンブリの名前をより柔軟に制御できるという点が挙げられます。最上位レベル アセンブリおよび静的コンテンツは影響を受けません。 このシナリオの短所として、フォルダ内のファイルが変更された場合に、対応するフォルダ アセンブリと変更されたページを再配置しなければならないことがあります。 prefix オプションを使用すると、プリコンパイルされたサイトのマージにおいて、更新可能なサイトと更新できないサイトの両方を対象とすることができます。このシナリオは、オプションをまったく使用せずにマージ ツールを実行する場合に適用される既定のシナリオです。 |
Aspnet_merge.exe を w オプションで実行し、マージによってすべての Web UI コンテンツ ファイルに対応する 1 つのアセンブリを作成する。 |
このシナリオでは、すべての UI コンテンツが assemblyname パラメータで指定した名前を持つ 1 つのアセンブリにマージされます。これにより、最終的な配置サイトのアセンブリの総数が削減されます。ただし、コンテンツ ファイルを変更した場合は、UI コンテンツ アセンブリの再配置が必要になります。 最上位レベル アセンブリおよび静的コンテンツは影響を受けません。 |
Aspnet_merge.exe を o オプションで実行し、マージによって Web サイト全体に対応する 1 つのアセンブリを作成する。 |
このシナリオでは、最終的な配置サイトには assemblyname パラメータで指定した名前を持つ 1 つのアセンブリだけが含まれます。アセンブリが 1 つだけであるため、サイトの配置が容易です。ただし、これはサイト内のコンテンツを変更した場合にサイト アセンブリの再作成と再配置が必要であることを意味します。 最上位レベル アセンブリ (App_Code、App_GlobalResources、および App_WebReferences) が 1 つのアセンブリに含まれているため、これらのアセンブリも影響を受けます。静的コンテンツは影響を受けません。 |
アプリケーションの配置用のマージ
Web サイトのアセンブリをマージするには、プリコンパイルされたサイトの場所を applicationPath パラメータで指定し、マージ ツールを実行します。ASP.NET マージ ツールは、プリコンパイルされたサイトを元の場所でマージします。つまり、プリコンパイルされたサイトとは別にマージされたサイトが作成されるわけではありません。applicationPath パラメータには、Web アプリケーションの最終的な場所を指定できます。また、ディレクトリのコピーなどにより、コンパイルされたアプリケーションを別の場所に配置することもできます。
マージ ツールでプリコンパイルされたサイトをマージした場合、動的ファイルの場所はプリコンパイルの段階から変わりません。マージ ツールによって変更される動的ファイルのコンテンツは、@ Page、@ Control、および @ Master の各ディレクティブだけです。マージ ツールは、これらのディレクティブを含むファイルが Bin フォルダ内の適切なマージされたアセンブリを継承していることを確認します。コンパイル ツールによるファイルの種類の扱い方の詳細については、「ASP.NET コンパイル ツール (Aspnet_compiler.exe)」の「解説」を参照してください。
ユーザー定義のフォルダ (ルート サイト フォルダを含む) から派生したアセンブリの場合、マージ オプションによっては、プリコンパイルされたサイト内の名前とは異なる名前が作成されることがあります。例として、マージ ツールにオプションをまったく指定しなかった場合に作成されるマージされたアセンブリの名前を次の表に示します。ユーザー定義のフォルダのアセンブリ名は App_Web_nnnn.dll となります。nnnn は内部的に生成されるハッシュ値です。
プリコンパイルされたサイトのフォルダ |
Aspnet_merge.exe にオプションを指定せずにマージしたアセンブリの名前 |
|---|---|
\ |
Root.dll |
Admin |
Admin.dll |
次の表は、prefix オプションと NewName パラメータを使用してマージしたアセンブリの名前を示しています。
プリコンパイルされたサイトのフォルダ |
Aspnet_merge.exe に prefix オプションを指定してマージしたアセンブリの名前 |
|---|---|
\ |
NewName.dll |
Admin |
NewName.Admin.dll |
マージされたサイトが更新できない場合、更新できる場合とはテーマの扱い方が異なります。プリコンパイルされ、マージされていないサイトには、テーマごとに別のアセンブリが存在します。各アセンブリの名前は、App_Theme_ThemeName.dll となります。マージされたサイトには、Theme.dll という名前のアセンブリが 1 つだけ含まれています。プリコンパイルされたサイトが更新可能な場合、マージされた Bin フォルダにはテーマに対応するアセンブリは存在しません。
マージ プロセスのトラブルシューティング
Web サイトのコンパイルまたはマージの実行中に、アセンブリのパスが Microsoft Windows で許容されるファイル パスの最大長を超えることがあります。その場合に、マージされたアセンブリのリソースを要求すると、そのリソースがプリコンパイルされていないため要求に応じられないことを示す HttpException エラーがスローされます。
Microsoft Windows のファイル パスの最大長は 260 文字です。アセンブリのパスが最大長を超えた場合は、Web サイトまたはそのサブフォルダのパスを短くする必要があります。さらに、場合によっては Web.config ファイルで hostingEnvironment 要素の ShadowCopyBinAssemblies プロパティを使用してシャドウ コピーを無効にする必要もあります。ファイル名の詳細については、MSDN Web サイトの「Naming a File」を参照してください。
o オプションを指定してマージ ツールを実行し、サイト全体に対応する 1 つのアセンブリを作成した場合、マージ プロセス中に循環参照が生成されると、エラーが発生します。この状況を回避する方法として、次の 2 つがあります。
代わりに w オプションを使用して、循環参照が含まれるソース ファイルを外部参照のままとし、マージの対象外とします。
循環参照に関係するコントロールを別のディレクトリに移動します。
マージするアセンブリの間に属性の不整合がある場合、マージ操作が正常に実行されるようにするには、以下のガイドラインに従う必要があります。
allowattrs オプションを使用して、整合性のない属性を一覧表示します。
copyattrs オプションを使用して、マージするすべてのアセンブリで属性が一致していることを確認します。
a オプションを使用します。
アセンブリの署名
マージ ツールに delaysign オプションと keyfile オプションを指定すると、厳密名ツール (Sn.exe) を使用しなくても厳密な名前を持つアセンブリを作成できます。delaysign オプションは AssemblyDelaySignAttribute 属性に対応し、keyfile オプションは AssemblyKeyFileAttribute 属性に対応します。
これらのオプションによって、それぞれに対応する属性がマージされたアセンブリに適用されます。適用される属性は、AllowMultiple プロパティが false に設定された AttributeUsageAttribute 属性でマークされます。したがって、これらのオプションを使用して、上記の属性のいずれかで既にマークされているアセンブリをマージすると、マージは失敗します。
例
次のコマンドは、C:\PrecompiledSite ディレクトリ内のプリコンパイルされたサイトのアセンブリをマージします。
Aspnet_merge C:\PrecompiledSite
次のコマンドは、C:\PrecompiledSite ディレクトリ内のプリコンパイルされたサイトのアセンブリをマージし、マージされたアセンブリに KeyFile.snk ファイルで署名します。マージされたサイトには、プリコンパイルされたサイト フォルダごとに 1 つのアセンブリが存在します。
Aspnet_merge C:\PrecompiledSite -keyfile KeyFile.snk
次のコマンドは、C:\PrecompiledSite ディレクトリ内のプリコンパイルされたサイトのアセンブリをすべて 1 つのアセンブリにマージし、そのアセンブリに MyApp.dll という名前を付けます。マージされたサイトには、すべての Web サイト UI コンテンツに対応する 1 つのアセンブリが存在します。
Aspnet_merge C:\PrecompiledSite -w MyApp.dll
次のコマンドは、C:\PrecompiledSite ディレクトリ内のプリコンパイルされたサイトのアセンブリをすべて 1 つのアセンブリにマージし、そのアセンブリに MyApp.dll という名前を付けます。
Aspnet_merge C:\PrecompiledSite -o MyApp.dll