高度な C# コンパイラオプション

[アーティクル]
05/10/2023

次のオプションでは高度なシナリオがサポートされます。新しい MSBuild 構文は、太字で示されています。以前の csc.exe 構文は、code style で示されています。

MainEntryPoint、StartupObject / -main: エントリポイントを含む型を指定します。
PdbFile / -pdb: デバッグ情報ファイルの名前を指定します。
PathMap / -pathmap: コンパイラによるソースパス名出力のマッピングを指定します。
ApplicationConfiguration / -appconfig: アセンブリバインド設定を含むアプリケーション構成ファイルを指定します。
AdditionalLibPaths / -lib: 参照を検索する追加のディレクトリを指定します。
GenerateFullPaths / -fullpath: コンパイラにより絶対パスが生成されます。
PreferredUILang / -preferreduilang: 優先される出力言語名を指定します。
BaseAddress / -baseaddress: ビルドするライブラリのベースアドレスを指定します。
ChecksumAlgorithm / -checksumalgorithm : PDB に格納されているソースファイルのチェックサムを計算するためのアルゴリズムを指定します。
CodePage / -codepage: ソースファイルを開くときに使用するコードページを指定します。
Utf8Output / -utf8output: UTF-8 エンコードでコンパイラのメッセージを出力します。
FileAlignment / -filealign: 出力ファイルセクションで使用される配置を指定します。
ErrorEndLocation / -errorendlocation: 各エラーの終了位置の出力行および列。
NoStandardLib / -nostdlib: 標準ライブラリ (mscorlib.dll) を参照しません。
SubsystemVersion / -subsystemversion: このアセンブリのサブシステムバージョンを指定します。
ModuleAssemblyName / -moduleassemblyname: このモジュールが一部となるアセンブリの名前。
ReportIVTs / -reportivts: System.Runtime.CompilerServices.InternalsVisibleToAttribute の情報に関する追加情報を生成します。

*.csproj ファイルの <PropertyGroup> 要素に、これらいずれかのオプションを追加します。

<PropertyGroup>
    <StartupObject>...</StartupObject>
    ...
</PropertyGroup>

MainEntryPoint または StartupObject

このオプションは、Main メソッドを含むクラスが複数ある場合に、プログラムへのエントリポイントを含むクラスを指定します。

<StartupObject>MyNamespace.Program</StartupObject>

<MainEntryPoint>MyNamespace.Program</MainEntryPoint>

ここで、Program は Main メソッドを含む型です。指定するクラス名は完全に修飾する必要があります。クラスを含む完全な名前空間を指定し、そのあとにクラス名を続ける必要があります。たとえば、Main メソッドが、MyApplication.Core 名前空間の Program クラス内に置かれている場合、コンパイラオプションは -main:MyApplication.Core.Program とする必要があります。コンパイルに Main メソッドの型以外のものが含まれている場合は、Main メソッドを含む型を指定することができます。

注意

このオプションは、プロジェクトに 1 つまたは複数の Main メソッドが含まれている場合でも、最上位レベルのステートメントを含むプロジェクトには使用できません。

PdbFile

PdbFile コンパイラオプションでは、デバッグシンボルファイルの名前と場所を指定します。 filename の値で、デバッグシンボルファイルの名前と場所が示されます。

<PdbFile>filename</PdbFile>

DebugType を指定すると、コンパイラで出力ファイル (.exe または .dll) が作成されるのと同じディレクトリに .pdb ファイルが作成されます。 .pdb ファイルには、出力ファイルの名前と同じベースファイル名が付けられます。 PdbFile では、.pdb ファイルに対し、既定以外のファイル名と場所を指定することができます。このコンパイラオプションは、Visual Studio 開発環境で設定することはできません。また、プログラムで変更することもできません。

PathMap

Note

PathMap を指定すると、ブレークポイントがローカルデバッグビルドで機能しなくなります。 PathMap を設定するのは、運用ビルドまたは継続的インテグレーションビルドに対してだけにしてください。

PathMap コンパイラオプションでは、コンパイラによるソースパス名出力への物理パスのマップ方法を指定します。このオプションは、コンパイラが実行されるコンピューター上の各物理パスを、出力ファイルに書き込まれる必要がある対応するパスにマップします。次の例では、path1 は現在の環境内のソースファイルへの完全パスであり、sourcePath1 は、すべての出力ファイルで path1 に置き換えられるソースパスです。複数のマップされるソースパスを指定するには、コンマで区切ります。

<PathMap>path1=sourcePath1,path2=sourcePath2</PathMap>

コンパイラは、次の理由でその出力にソースパスを書き込みます。

CallerFilePathAttribute が省略可能なパラメーターに適用される場合、引数はソースパスに置き換えられます。
ソースパスは、PDB ファイルに埋め込まれます。
PDB ファイルのパスは、PE (ポータブル実行可能) ファイルに埋め込まれます。

ApplicationConfiguration

ApplicationConfiguration コンパイラオプションを利用すると、C# アプリケーションで、アセンブリのバインド時に共通言語ランタイム (CLR) にアセンブリのアプリケーション構成 (app.config) ファイルの場所を指定できます。

<ApplicationConfiguration>file</ApplicationConfiguration>

ここで、file はアセンブリバインド設定を含むアプリケーション構成ファイルです。 ApplicationConfiguration の用途の 1 つは、1 つのアセンブリで、特定の参照アセンブリの .NET Framework バージョンと .NET Framework for Silverlight バージョンの両方を同時に参照する必要がある高度なシナリオです。たとえば、WPF (Windows Presentation Foundation) で作成された XAML デザイナーにおいて、デザイナーのユーザーインターフェイスとして WPF デスクトップを参照すると共に、Silverlight に組み込まれている WPF のサブセットも参照する必要がある場合があります。同じデザイナーアセンブリで両方のアセンブリにアクセスする必要があります。既定では、この 2 つのアセンブリはアセンブリバインディングで同等と見なされるため、別々に参照するとコンパイラエラーが発生します。 ApplicationConfiguration コンパイラオプションを利用すると、次の例に示されているように、<supportPortability> タグを使用して既定の動作を無効にする app.config ファイルの場所を指定できます。

<supportPortability PKT="7cec85d7bea7798e" enable="false"/>

このコンパイラは、CLR のアセンブリバインドロジックにファイルの場所を渡します。

注意

プロジェクトに既に設定されている app.config ファイルを使用するには、プロパティタグ <UseAppConfigForCompiler> を .csproj ファイルに追加し、その値を true に設定します。異なる app.config ファイルを指定するには、プロパティタグ <AppConfigForCompiler> を追加し、その値をファイルの場所に設定します。

.NET Framework と .NET Framework for Silverlight の両方の実装に存在する .NET Framework アセンブリについて、その両方の実装をアプリケーションで参照できるようにする app.config ファイルの例を次に示します。 ApplicationConfiguration コンパイラオプションでは、この app.config ファイルの場所を指定します。

<configuration>
  <runtime>
    <assemblyBinding>
      <supportPortability PKT="7cec85d7bea7798e" enable="false"/>
      <supportPortability PKT="31bf3856ad364e35" enable="false"/>
    </assemblyBinding>
  </runtime>
</configuration>

AdditionalLibPaths

AdditionalLibPaths オプションでは、References オプションで参照されるアセンブリの場所を指定します。

<AdditionalLibPaths>dir1[,dir2]</AdditionalLibPaths>

ここで dir1 は、参照されているアセンブリが現在の作業ディレクトリ (コンパイラを起動するディレクトリ) または共通言語ランタイムのシステムディレクトリに見つからない場合に、コンパイラによって検索されるディレクトリです。 dir2 は、アセンブリ参照を検索する 1 つまたは複数の追加ディレクトリです。ディレクトリ名はコンマで区切り、それらの間に空白は入れません。コンパイラによって、完全に修飾されていないアセンブリ参照が次の順序で検索されます。

現在の作業ディレクトリ。
共通言語ランタイムのシステムディレクトリ。
AdditionalLibPaths によって指定されているディレクトリ。
LIB 環境変数によって指定されているディレクトリ。

アセンブリ参照を指定するには、Reference を使います。 AdditionalLibPaths は付加的なものです。複数回指定すると、前の値に追加されます。依存アセンブリへのパスはアセンブリマニフェストで指定されていないため、アプリケーションにより、グローバルアセンブリキャッシュでアセンブリが検索されて使用されます。コンパイラでアセンブリが参照されているからといって、共通言語ランタイムで実行時にアセンブリを見つけて読み込めるわけではありません。ランタイムが参照されているアセンブリを検索する方法について詳しくは、「ランタイムがアセンブリを検索する方法」をご覧ください。

GenerateFullPaths

GenerateFullPaths オプションを指定すると、コンパイルのエラーや警告を一覧表示する際に、コンパイラによってファイルの完全なパスが指定されます。

<GenerateFullPaths>true</GenerateFullPaths>

既定では、コンパイルの結果として発生したエラーや警告には、エラーが見つかったファイルの名前が指定されます。 GenerateFullPaths オプションを使用すると、コンパイラによってファイルの完全なパスが指定されます。このコンパイラオプションは Visual Studio では使用できず、プログラムで変更することはできません。

PreferredUILang

PreferredUILang コンパイラオプションを使うと、C# コンパイラで、エラーメッセージなどの出力を表示する言語を指定できます。

<PreferredUILang>language</PreferredUILang>

ここで language は、コンパイラ出力に使う言語の言語名です。 PreferredUILang コンパイラオプションを使うと、C# コンパイラで、エラーメッセージおよびその他のコマンドライン出力に使用する言語を指定できます。言語の言語パックがインストールされていない場合は、オペレーティングシステムの言語設定が代わりに使用されます。

BaseAddress

BaseAddress オプションを使用すると、DLL を読み込む位置に推奨されるベースアドレスを指定できます。このオプションを使用するタイミングと理由の詳細については、Larry Osterman のブログを参照してください。

<BaseAddress>address</BaseAddress>

ここで、address は DLL のベースアドレスです。このアドレスは、10 進数、16 進数、または 8 進数で指定できます。 DLL の既定のベースアドレスは、.NET 共通言語ランタイムにより設定されます。このアドレスの下位ワードは丸められます。たとえば、0x11110001 と指定すると、丸められて 0x11110000 になります。 DLL の署名プロセスを完了するには、-R オプションを指定した SN.EXE を使用します。

ChecksumAlgorithm

このオプションでは、PDB 内のソースファイルをエンコードするために使用するチェックサムアルゴリズムを制御します。

<ChecksumAlgorithm>algorithm</ChecksumAlgorithm>

algorithm は、SHA1 (既定値) または SHA256 である必要があります。

CodePage

このオプションでは、必要とするページが、システムの現在の既定のコードページでない場合に、コンパイル時に使用するコードページを指定します。

<CodePage>id</CodePage>

ここで id は、コンパイル時にすべてのソースコードファイルで使用するコードページの ID です。コンパイラでは、まずすべてのソースファイルを UTF-8 として解釈しようと試みられます。ソースコードファイルが UTF-8 以外のエンコードで、7 ビット ASCII 文字以外の文字が使われている場合は、CodePage オプションを使って、使用する必要があるコードページを指定します。 CodePage は、コンパイル時にすべてのソースコードファイルに適用されます。使用しているシステムでサポートされているコードページを確認する方法については、GetCPInfo に関するページをご覧ください。

Utf8Output

Utf8Output オプションでは、UTF-8 エンコードを使用してコンパイラ出力を表示します。

<Utf8Output>true</Utf8Output>

国際化の設定によっては、コンパイラの出力が正しくコンソールに表示できない場合があります。 Utf8Output を使用して、コンパイラ出力をファイルにリダイレクトします。

FileAlignment

FileAlignment オプションを使用すると、出力ファイル内のセクションのサイズを指定できます。有効値は 512、1024、2048、4096、および 8192 です。これらの値はバイト単位です。

<FileAlignment>number</FileAlignment>

FileAlignment オプションは、Visual Studio でプロジェクトの [ビルド] プロパティの [詳細設定] ページから設定します。各セクションは、FileAlignment 値の倍数である境界上に配置されます。固定の既定値はありません。 FileAlignment が指定されていない場合、共通言語ランタイムによってコンパイル時に既定値が選択されます。セクションのサイズを指定すると、出力ファイルのサイズに影響します。セクションのサイズ変更は、比較的小さなデバイスで実行されるプログラムに対して有効な場合があります。出力ファイル内のセクションに関する情報を表示するには、DUMPBIN を使用します。

ErrorEndLocation

各エラーの終了位置の出力行および列をコンパイラに指示します。

<ErrorEndLocation>true</ErrorEndLocation>

既定では、コンパイラにより、すべてのエラーと警告についてソース内の開始位置が書き込まれます。このオプションが true に設定されている場合、コンパイラにより、各エラーと警告の開始と終了の両方の位置が書き込まれます。

NoStandardLib

NoStandardLib では、System 名前空間全体を定義する mscorlib.dll がインポートされないようにします。

<NoStandardLib>true</NoStandardLib>

独自の System 名前空間およびオブジェクトを定義または作成する場合は、このオプションを使用します。 NoStandardLib を指定しない場合、(<NoStandardLib>false</NoStandardLib> を指定したことと同じで) mscorlib.dll がプログラムにインポートされます。

SubsystemVersion

実行可能ファイルが実行されるサブシステムの最小バージョンを指定します。通常、このオプションを指定することで、Windows の以前のバージョンでは使用できないセキュリティ機能を実行可能ファイルで確実に利用できるようになります。

注意

サブシステム自体を指定するには、TargetType のコンパイラオプションを使用します。

<SubsystemVersion>major.minor</SubsystemVersion>

major.minor では、サブシステムに必要な最小バージョンを指定します。これは、メジャーおよびマイナーバージョンのドット表記で表されます。たとえば、Windows 7 より前のオペレーティングシステムではアプリケーションを実行できないように指定できます。このオプションの値を 6.01 に設定します (この記事の後述の表を参照)。 major と minor の値を整数として指定します。 minor バージョンでは、前に配置されるゼロによってバージョンが変更されることはありませんが、後ろにゼロが付くとバージョンが変わります。たとえば、6.1 と 6.01 は同じバージョンを示しますが、6.10 は異なるバージョンを示します。混乱を避けるため、マイナーバージョンには 2 桁の数値を使用することをお勧めします。

次の表は、Windows の一般的なサブシステムのバージョンを示しています。

Windows のバージョン	サブシステムのバージョン
Windows Server 2003	5.02
Windows Vista	6.00
Windows 7	6.01
Windows Server 2008	6.01
Windows 8	6.02

SubsystemVersion コンパイラオプションの既定値は、以下の一覧に示されている条件によって異なります。

次のコンパイラオプションのいずれかが設定されている場合、既定値は 6.02 です。
MSBuild を使用しており、.NET Framework 4.5 が対象で、さらにこの一覧で前に指定したコンパイラオプションを設定していない場合、既定値は 6.00 です。
上記の条件がどれも当てはまらない場合、既定値は 4.00 です。

ModuleAssemblyName

.netmodule でアクセスできる非パブリック型のアセンブリの名前を指定します。

<ModuleAssemblyName>assembly_name</ModuleAssemblyName>

ModuleAssemblyName は、 .netmodule をビルドするときと、次の条件に当てはまる場合に使用する必要があります。

.netmodule で、既存のアセンブリ内の非パブリック型へのアクセスが必要である。
.netmodule をビルドするアセンブリの名前を把握していること。
既存のアセンブリに、netmodule がビルドされるアセンブリへのフレンドアセンブリのアクセス権が付与されている。

.netmodule のビルドについて詳しくは、モジュールの TargetType オプションを参照してください。フレンドアセンブリの詳細については、「フレンドアセンブリ」を参照してください。

ReportIVTs

コンパイル中に検出された System.Runtime.CompilerServices.InternalsVisibleToAttribute に関する追加の診断情報を有効または無効にします。

<ReportIVTs>true</ReportIVTs>

要素の内容が true の場合は、診断が有効になります。内容が false、または存在しない場合は無効になります。

ReportIVTs を有効にすると次の情報がレポートされます。

アクセスできないメンバーの診断。現在のアセンブリと異なる場合は、ソースアセンブリが含まれます。
コンパイラが、コンパイルされるプロジェクトのアセンブリ ID、そのアセンブリ名、公開キーを出力します。
コンパイラに渡されたすべての参照に対して、次の情報が出力されます。
1. 参照のアセンブリ ID
2. 参照によって現在のプロジェクトに InternalsVisibleTo が許可されるかどうか
3. このアセンブリから InternalsVisibleTo を許可されたアセンブリの名前とすべての公開キー

次の方法で共有

高度な C# コンパイラオプション

MainEntryPoint または StartupObject

PdbFile

PathMap

ApplicationConfiguration

AdditionalLibPaths

GenerateFullPaths

PreferredUILang

BaseAddress

ChecksumAlgorithm

CodePage

Utf8Output

FileAlignment

ErrorEndLocation

NoStandardLib

SubsystemVersion

ModuleAssemblyName

ReportIVTs

その他のリソース

次の方法で共有

高度な C# コンパイラ オプション

MainEntryPoint または StartupObject

PdbFile

PathMap

ApplicationConfiguration

AdditionalLibPaths

GenerateFullPaths

PreferredUILang

BaseAddress

ChecksumAlgorithm

CodePage

Utf8Output

FileAlignment

ErrorEndLocation

NoStandardLib

SubsystemVersion

ModuleAssemblyName

ReportIVTs

その他のリソース

高度な C# コンパイラオプション