Visual Studio デバッガーでシンボル (.pdb) ファイルとソース ファイルを指定します (C#、C++、Visual Basic、F#)
プログラム データベース ( .pdb) ファイルは、シンボル ファイルとも呼ばれ、プロジェクトのソース コード内の識別子とステートメントをコンパイル済みアプリの対応する識別子と指示にマップします。 これらのマッピング ファイルによって、デバッガーがソース コードにリンクされ、デバッグが有効になります。
Visual Studio IDE で標準の [デバッグ] ビルド構成を使用してプロジェクトをビルドすると、コンパイラによって適切なシンボル ファイルが作成されます。 この記事では、IDE でシンボル ファイルを管理する方法について説明します。次に例を示します。
シンボル ファイルの詳細については、次をご覧ください。
シンボル ファイルのしくみ
.pdb ファイルには、デバッグとプロジェクトの状態情報が保持されます。この情報により、アプリのデバッグ構成のインクリメンタル リンクが可能になります。 Visual Studio デバッガーは、デバッグ中に .pdb ファイルを使用して次の 2 つの重要な情報を決定します。
- Visual Studio IDE に表示するソース ファイル名と行番号。
- ブレークポイントとして停止するアプリ内の場所。
シンボル ファイルには、ソース ファイルの場所と (必要に応じて) ソース ファイルの取得先のサーバーも示されます。
デバッガーは、アプリがビルドされたときに作成された .pdb ファイル (つまり、元の .pdb ファイルまたはコピー) と完全に一致する .pdb ファイルのみを読み込みます。 この正確な複製が必要とされるのは、コード自体が変更されていない場合でも、アプリのレイアウトが変更される可能性があるためです。 詳細については、「Why does Visual Studio require debugger symbol files to exactly match the binary files that they were built with?」 (ビルドに使用したバイナリ ファイルと完全に一致させるために、Visual Studio でデバッガー シンボル ファイルが必要な理由) を参照してください。
ヒント
プロジェクト ソース コードの外部にあるコード (プロジェクトから呼び出す Windows コードやサード パーティのコードなど) をデバッグするには、外部コードの .pdb ファイル (および必要に応じてソース ファイル) の場所を指定する必要があり、これらはアプリのビルドと完全に一致する必要があります。
デバッガーがシンボルを検索する場所
Visual Studio IDE でプロジェクトをデバッグするとき、デバッガーにより、既定で検索可能なシンボル ファイルが自動的に読み込まれます。
注意
リモート デバイスでマネージド コードをデバッグするときは、すべてのシンボル ファイルをローカル コンピューター上またはデバッガー オプションで指定した場所に配置する必要があります。
デバッガーにより、次の場所でシンボル ファイルが検索されます。
プロジェクト フォルダー。
DLL または実行可能 ( .exe) ファイル内で指定されている場所。
既定では、DLL または .exe ファイルをコンピューター上でビルドした場合、リンカーは関連する .pdb ファイルの完全なパスとファイル名を DLL または .exe ファイル内に格納します。 デバッガーは、その場所にシンボル ファイルが存在するかどうかをチェックします。
DLL または .exe ファイルと同じフォルダー。
シンボル ファイルに関するデバッガー オプションで指定された場所。 シンボルの場所を追加して有効にするには、「シンボルの場所と読み込みオプションを構成する」を参照してください。
任意のローカル シンボル キャッシュ フォルダー。
指定されたネットワーク、インターネット、またはローカルのシンボル サーバーと場所 (Microsoft シンボル サーバーを選択した場合など)。 Visual Studio では、
symsrvプロトコルを実装するシンボル サーバーからデバッグ シンボル ファイルをダウンロードできます。 Visual Studio Team Foundation Server と Debugging Tools for Windows は、シンボル サーバーを使用できる 2 つのツールです。以下のシンボル サーバーを使用できます。
パブリックの Microsoft シンボル サーバー:システム DLL やサード パーティのライブラリの呼び出し中に発生するクラッシュをデバッグするには、多くの場合、システム .pdb ファイルが必要です。 システム .pdb ファイルには、Windows DLL、 .exe ファイル、デバイス ドライバーのシンボルが含まれています。 パブリックの Microsoft シンボル サーバーからは、Windows オペレーティング システム、MDAC、IIS、ISA、.NET のシンボルを取得できます。
内部ネットワーク上またはローカル コンピューター上のシンボル サーバー:チームや会社で独自の製品用にシンボル サーバーを作成して、外部ソースのシンボルのキャッシュとして使用できます。 自分のコンピューター上にシンボル サーバーを作成することもできます。
サード パーティのシンボル サーバー:Windows アプリケーションおよびライブラリのサード パーティ プロバイダーがインターネット上のシンボル サーバーへのアクセスを用意していることがあります。
警告
パブリックの Microsoft シンボル サーバー以外のシンボル サーバーを使用する場合は、シンボル サーバーとそのパスが信頼できることを確認してください。 シンボル ファイルには任意の実行可能コードを含めることができるため、このファイルによりセキュリティ上の脅威にさらされる可能性があります。
シンボル ファイルの場所と読み込みオプションを構成する
デバッガーにより、既定でシンボルのさまざまな場所がチェックされます。 「デバッガーがシンボルを検索する場所」を参照してください。
[ツール]>[オプション]>[デバッグ]>[シンボル] ページでは、以下の操作を実行できます。
- シンボル ファイルの検索パスを指定して選択します。
- Microsoft、Windows、またはサードパーティのコンポーネントのシンボル サーバーを指定します。
- デバッガーがシンボルを自動的に読み込む (または読み込まない) モジュールを指定する。
- デバッグ中にこれらの設定を変更する。 「デバッグ中にシンボルを読み込む」を参照してください。
シンボルの場所と読み込みオプションを指定するには:
Visual Studio で、 [ツール]>[オプション]>[デバッグ]>[シンボル] (または [デバッグ]>[オプション]>[シンボル] ) を開きます。
[シンボル ファイル (.pdb) の場所] で、
[Microsoft シンボル サーバー] または [NuGet.org シンボル サーバー] を使用するには、そのチェック ボックスを選択します。
新しいシンボル サーバーの場所を追加するには、
- ツール バーの + 記号を選択します。
- テキスト フィールドに、シンボル サーバーまたはシンボルの場所の URL (http)、ネットワーク共有、またはローカル パスを入力します。 ステートメント入力候補により、正しい形式を確認できます。
Note
指定したフォルダーのみが検索されます。 検索するすべてのサブフォルダーのエントリを追加する必要があります。
新しい Azure DevOps シンボル サーバーの場所を追加するには:
ツール バーの
アイコンを選択します。[Azure DevOps シンボル サーバーへの接続] ダイアログで、使用可能なシンボル サーバーのいずれかを選択し、[接続] を選択します。
詳しくは、「Azure Artifacts シンボル サーバーの追加」を参照してください。
シンボルの場所の読み込み順序を変更するには、Ctrl+↑/Ctrl+↓キーまたは上/下矢印アイコンを使用します。
URL またはパスを編集するには、エントリをダブルクリックするか、それを選択して F2 キーを押します。
エントリを削除するには、それを選択してから - ボタンを選択します。
(オプション) シンボルの読み込みパフォーマンスを向上させるには、 [このディレクトリにシンボルをキャッシュ] に、シンボル サーバーからシンボルをコピーできるローカル フォルダーのパスを入力します。
注意
Windows フォルダーやそのサブフォルダーなどの保護されたフォルダーにローカル シンボル キャッシュを配置しないでください。 読み取り/書き込みフォルダーを使用してください。
注意
C++ プロジェクトで
_NT_SYMBOL_PATH環境変数が設定されている場合は、 [このディレクトリにシンボルをキャッシュ] に設定されている値がオーバーライドされます。デバッガーの開始時に [シンボル ファイル (.pdb) の場所] から読み込まれるモジュールを指定します。
明示的に除外したモジュールを除くすべてのモジュールのすべてのシンボルを読み込むには、 [除外されていないすべてのモジュール] を選択します (既定値)。 特定のモジュールを除外するには、 [除外されるモジュールの指定] を選択して + アイコンを選択し、除外するモジュールの名前を入力して [OK] を選択します。
シンボル ファイルの場所から指定したモジュールのみを読み込むには、 [指定したモジュールのみ] を選択します。 [モジュールの指定] を選択して + アイコンを選択し、含めるモジュールの名前を入力して [OK] を選択します。 その他のモジュールのシンボル ファイルは読み込まれません。
[OK] を選択します。
デバッグ用のその他のシンボル オプション
[ツール]>[オプション]>[デバッグ]>[全般] (または [デバッグ]>[オプション]>[全般] ) で、追加のシンボル オプションを選択できます。
dll エクスポートの読み込み (ネイティブのみ)
C/C++ 用の DLL エクスポート テーブルを読み込みます。 詳細については、「DLL エクスポート テーブル」を参照してください。 DLL エクスポート情報の読み取りにはある程度のオーバーヘッドが伴うため、エクスポート テーブルの読み込みは既定で無効になっています。 C/C++ のビルド コマンド ラインで
dumpbin /exportsを使用することもできます。[アドレス レベルのデバッグを有効にする] と [ソースがない場合は逆アセンブリの表示]
ソース ファイルまたはシンボル ファイルが見つからない場合は、常に逆アセンブリを表示します。
ソース サーバー サポートを有効にする
ローカル コンピューターにソース コードがない場合、または .pdb ファイルがソース コードと一致しない場合は、ソース サーバーを使用してアプリをデバッグできます。 ソース サーバーは、ファイルの要求を受け取り、ソース管理から実際のファイルを返します。 ソース サーバーは、srcsrv.dll という名前の DLL ファイルを使用してアプリの .pdb ファイルを読み取ることで実行されます。 .pdb ファイルには、ソース コード リポジトリへのポインターとともに、リポジトリからソース コードを取得するときに使用するコマンドも含まれています。
srcsrv.dll がアプリの .pdb ファイルから実行できるコマンドを制限するには、srcsrv.ini というファイルに許可するコマンドを列挙します。 srcsrv.ini ファイルは、srcsrv.dll および devenv.exe と同じフォルダーに配置します。
重要
アプリの .pdb ファイルには任意のコマンドを埋め込むことができるため、srcsrv.ini ファイルには実行する必要があるコマンドのみを配置するようにしてください。 srcsvr.ini ファイルにないコマンドを実行しようとすると、確認のダイアログ ボックスが表示されます。 詳細については、「セキュリティ警告: デバッガーは信頼されないコマンドを実行する必要があります。
コマンド パラメーターでは何も検証されないため、コマンドを信頼するときは注意してください。 たとえば、srcsrv.ini に cmd.exe を指定した場合、悪意のあるユーザーが cmd.exe に危険な動作を実行するようなパラメーターを指定する可能性があります。
この項目と必要な子項目を選択します。 [部分信頼アセンブリのソース サーバーを許可する (マネージドのみ)] と [信頼されていないソース サーバー コマンドを常に確認なしで実行する] は、セキュリティ リスクが高める可能性があります。
コンパイラのシンボル オプション
Visual Studio IDE で標準の [デバッグ] ビルド構成を使用してプロジェクトをビルドすると、C++ およびマネージド コンパイラによってコードの適切なシンボル ファイルが作成されます。 コードでコンパイラ オプションを設定することもできます。
Visual Studio でビルド構成のコンパイラ オプションを設定するには、「デバッグ構成とリリース構成を設定する」を参照してください。
.NET オプション
.pdb ファイルを作成するには、 /debug でビルドします。 /debug:full または /debug:pdbonlyでアプリケーションをビルドできます。 /debug:full でビルドすると、デバッグできるコードが生成されます。 /debug:pdbonly でビルドすると .pdb ファイルは生成されますが、JIT コンパイラにデバッグ情報が使用できることを示す DebuggableAttribute は生成されません。 デバッグが必要ないリリース ビルドで .pdb ファイルを生成する場合は、 /debug:pdbonly を使用します。 詳細については、「/debug (C# コンパイラ オプション)」または「/debug (Visual Basic)」を参照してください。
C/C++ オプション
VC<x>.pdb ファイルと <project>.pdb ファイル
/ZI または /Zi でビルドすると、C/C++ 用の .pdb ファイルが作成されます。 Visual C++ では、コンパイラにより作成される .pdb ファイルの名前を /Fd オプションで指定します。 Visual Studio で IDE を使ってプロジェクトを作成する場合は、<project>.pdb という名前の .pdb ファイルを作成するように /Fd オプションが設定されます。
メイクファイルを使って C/C++ アプリケーションをビルドするときに、/Fd を使わずに /ZI または /Zi を指定し、ファイル名を指定した場合は、コンパイラによって次の 2 つの .pdb ファイルが作成されます。
VC<x>.pdb。<x> は Microsoft C++ コンパイラのバージョン (VC11.pdb など) を表します
VC<x>.pdb ファイルには、個別のオブジェクト ファイルのあらゆるデバッグ情報が格納されます。このファイルは、プロジェクトのメイクファイルと同じディレクトリに配置されます。 オブジェクト ファイルが作成されるたびに、C/C++ コンパイラはデバッグ情報を VC<x>.pdb に挿入します。 このため、すべてのソース ファイルに <windows.h> などの共通ヘッダー ファイルをインクルードしている場合でも、これらのヘッダーの typedef は一度格納されるだけで、すべてのオブジェクト ファイルに格納されるわけではありません。 挿入される情報には、型情報が含まれますが、関数定義などのシンボル情報は含まれません。
<project>.pdb
<project>.pdb ファイルには、プロジェクトの .exe ファイルのあらゆるデバッグ情報が格納されます。このファイルは \debug サブディレクトリに配置されます。 <project>.pdb ファイルには、VC<x>.pdb に含まれる型情報だけでなく、関数プロトタイプなどのあらゆるデバッグ情報が含まれます。
VC<x>.pdb ファイルと <project>.pdb ファイルは、どちらもインクリメンタル更新が可能です。 リンカーも、作成する .exe ファイルや .dll ファイルに .pdb ファイルへのパスを埋め込みます。
-
DLL のエクスポート テーブル内で使用できるシンボルを確認するには、
dumpbin /exportsを使用します。 DLL エクスポート テーブルのシンボル情報は、Windows メッセージ、Windows プロシージャ (WindowProc)、COM オブジェクト、マーシャリング、または対応するシンボルのない DLL を操作する場合に役立ちます。 シンボルは、任意の 32 ビット システムの DLL に使用できます。 関数は呼び出し順に表示され、現在の関数 (入れ子の一番内側) が先頭に表示されます。dumpbin /exportsの出力を参照すると、英数字以外の文字を含む、正確な関数名を確認できます。 正確な関数名を確認すると、関数にブレークポイントを設定する際に、デバッガーの他の部分で関数名を切り詰めることができるため、便利です。 詳細については、「 dumpbin /exports」を参照してください。
Web アプリケーション
ASP.NET アプリケーションの web.config ファイルをデバッグ モードに設定します。 デバッグ モードの ASP.NET では、動的に生成されたファイル用のシンボルが生成され、デバッガーの ASP.NET アプリケーションへのアタッチが可能になります。 Visual Studio では、プロジェクトを Web プロジェクト テンプレートから作成した場合、デバッグ開始時にこの処理が自動的に実行されます。
デバッグ中にシンボルを読み込む
[モジュール] 、 [呼び出し履歴] 、 [ローカル] 、 [自動変数] 、または [ウォッチ] ウィンドウを使用して、デバッグ中にシンボルを読み込んだり、シンボル オプションを変更したりできます。 詳細については、「アプリにデバッガーをアタッチする方法について理解を深める」を参照してください。
[モジュール] ウィンドウでシンボルを操作する
デバッグ中の [モジュール] ウィンドウには、デバッガーによってユーザー コード (マイ コード) として扱われているモジュールと、そのシンボルの読み込み状態が表示されます。 [モジュール] ウィンドウでは、シンボルの読み込み状態を監視したり、シンボルを読み込んだり、シンボル オプションを変更したりすることもできます。
デバッグ中にシンボルの場所やオプションを監視または変更するには:
- [モジュール] ウィンドウを開くには、デバッグ中に [デバッグ]>[ウィンドウ]>[モジュール] の順に選択します (または、Ctrl + Alt + U キーを押します)。
- [モジュール] ウィンドウで、 [シンボル状態] ヘッダー、 [シンボル ファイル] ヘッダー、または任意のモジュールを右クリックします。
- コンテキスト メニューで、次のいずれかを選択します。
| オプション | 説明 |
|---|---|
| シンボルの読み込み | シンボルがスキップされた、見つからない、または読み込まれていないモジュールに対して表示されます。 [オプション]>[デバッグ]>[シンボル] ページで指定した場所からシンボルを読み込もうとします。 シンボル ファイルが見つからないか、読み込まれない場合は、ファイル エクスプローラーが起動され、検索する新しい場所を指定できます。 |
| シンボルの読み込み情報 | 読み込まれたシンボル ファイルの場所、またはデバッガーがファイルを見つけることができない場合は検索した場所が表示されます。 |
| シンボルの設定 | [オプション]>[デバッグ]>[シンボル] ページが開き、このページでシンボルの場所を編集したり追加したりできます。 |
| 常に自動的に読み込む | 選択したシンボル ファイルが、デバッガーによって自動的に読み込まれるファイルの一覧に追加されます。 |
[シンボルが読み込まれていません] または [ソースが読み込まれていません] ページを使用する
シンボル ファイルまたはソース ファイルを使用できないコードをデバッガーで中断するには、いくつかの方法があります。
- コードにステップ インします。
- ブレークポイントまたは例外でコードを中断します。
- 別のスレッドに切り替えます。
- [呼び出し履歴] ウィンドウでスタック フレームをダブルクリックして、スタック フレームを変更します。
この状況が発生すると、デバッガーに [シンボルが読み込まれていません] または [ソースが読み込まれていません] ページが表示され、このページで必要なシンボルまたはソースを検索して読み込むことができます。
[シンボルが読み込まれていません] ドキュメント ページを使用して、見つからないシンボルを検索して読み込むには:
- 検索パスを変更するには、選択されていないパスを選択するか、 [新しいパス] または [新しい VSTS パス] を選択して新しいパスを入力または選択します。 [読み込み] を選択してパスを再び検索します。シンボル ファイルが見つかった場合は読み込まれます。
- シンボル オプションをオーバーライドして検索パスを再び試すには、[<executable-name> を参照して探す] を選びます。 シンボル ファイルが見つかった場合は読み込まれます。そうでない場合は、ファイル エクスプローラーが開き、手動でシンボル ファイルを選択できます。
- シンボル設定ページを開いて動作を構成するには、 [シンボルの設定の変更] を選択します (あるいは、 [オプション] 、 [デバッグ] 、 [シンボル] の順に選択します)。
- (詳細) 新しいウィンドウに 1 回だけ逆アセンブリが表示されるようにするには、 [逆アセンブルの表示] を選択するか、 [オプション] ダイアログ を選択して、ソース ファイルまたはシンボル ファイルが見つからない場合は逆アセンブリを常に表示するオプションを設定します。 詳細については、逆アセンブリ コードの表示に関するページを参照してください。
- 検索された場所とその結果を表示するには、 [シンボルの読み込み情報] を展開します。
- C# コードについては、 [シンボルが読み込まれていません] または [ソースが読み込まれていません] ページからソース コードの逆コンパイルを選択することもできます。
いずれかのオプションを実行した後、 .pdb ファイルが見つかり、デバッガーが .pdb ファイル内の情報を使用してソース ファイルを取得できた場合は、そのソースが表示されます。 それ以外の場合は、 [ソースが読み込まれていません] ページが表示され、問題の説明と問題を解決できるアクションへのリンクが示されます。
ソース ファイルの検索パスをソリューションに追加するには:
デバッガーがソース ファイルを検索する場所を指定したり、検索から特定のファイルを除外したりできます。
ソリューション エクスプローラーでソリューションを選択してから、 [プロパティ] アイコンを選択するか、Alt+Enter を押すか、または右クリックして [プロパティ] を選択します。
[デバッグ ソース ファイル] を選択します。
[ソース コードを含んでいるディレクトリ] で、検索するソース コードの場所を入力または選択します。 場所を追加するには、 [新しい行] アイコンを使用します。場所の順序を変更するには、上/下矢印アイコンを使用します。場所を削除するには、X アイコンを使用します。
注意
デバッガーは指定されたディレクトリのみを検索します。 検索するすべてのサブディレクトリのエントリを追加する必要があります。
[以下のソース ファイルを探さない] に、検索から除外するソース ファイルの名前を入力します。
[OK] または [適用] を選択します。