SymSrv の使用

SymSrv は、一元化されたシンボル ストアからシンボル ファイルを配信します。 これらのストアには、任意の数のプログラムまたはオペレーティング システムに対応する任意の数のシンボル ファイルを含めることができます。 ストアにはバイナリ ファイルを含めることもできます。これは、ミニダンプ ファイルをデバッグするときに特に便利です。

ストアには、実際のシンボル ファイルとバイナリ ファイルを含めたり、シンボル ファイルへのポインターを単純に格納したりできます。 ストアにポインターが含まれている場合、SymSrv はソースから直接実際のファイルを取得します。

SymSrv では、大規模なシンボル ストアを、特殊なデバッグ タスクに適した小さなサブセットに分割することもできます。

最後に、SymSrv は、オペレーティング システムによって提供されるログオン情報を使用して、HTTP または HTTPS ソースからシンボル ファイルを取得できます。 SymSrv では、スマートカード、証明書、および通常のログインとパスワードによって保護された HTTPS サイトがサポートされます。

シンボル パスを設定する

「シンボル パス」で説明されているように、シンボル パス (_NT_SYMB (メガバイト)OL_PATH環境変数) は、セミコロンで区切られた複数のパス要素で構成できます。 これらのパス要素の 1 つ以上がテキスト「srv*」で始まる場合、その要素はシンボル サーバーであり、SymSrv を使用してシンボル ファイルを検索します。

Note

「srv*」テキストが指定されていないが、実際のパス要素がシンボル サーバー ストアである場合、シンボル ハンドラーは「srv*」が指定されているかのように動作します。 シンボル ハンドラーは、指定されたパスのルート ディレクトリで「pingme.txt」というファイルの存在を検索することによってこの判断を行います。

 

シンボル パスがセミコロンで区切られたシンボル パス要素で構成されるのと同様に、シンボル サーバーはアスタリスクで区切られたシンボル ストア要素で構成されます。 「srv*」プレフィックスの後には、最大 10 個のシンボル ストアがあります。 一覧の左側にリストされているストアはダウンストリーム ストアと呼ばれ、右側のストアはアップストリーム ストアと呼ばれます。

srv\**SymbolStore* srv\**SymbolStore1*\**SymbolStoreN*

パスにシンボル ストア要素が 1 つだけ含まれている場合、SymSrv は要求されたファイルをそのストアから直接使用しようとします。

パスに 2 つのシンボル ストアがある場合、SymSrv は左端のシンボル ストア内のシンボル ファイルを検索します。 ファイルがある場合は、ファイルが使用されます。 存在しない場合、SymSrv はすぐに右側のシンボル ストアを検索します。 ファイルがある場合は、左側のストアにコピーされ、そこから開かれます。

ストアが 3 つ以上ある場合、この動作はファイルが見つかるまで、またはリストにストアがなくなるまで右に進みます。

ファイルはどのストアからも開かれることはなく、一番左のストアから開くことはありません。 ファイルがチェーン内の他の場所にある場合は、そのファイルの左側のすべてのストアにコピーされます。 このコピー プロセスは「カスケード」と呼ばれ、このドキュメントの後半で説明する特定の利点を提供します。

シンボル ストアの種類

次の表に、サポートされているシンボル ストアの種類の例を示します。

シンボル ストアの種類	説明
\\server\share	リモート サーバー上の共有への完全修飾 UNC パス。
c:\LocalCache	クライアント コンピューター上のディレクトリへのパス。
https://InternetSite	シンボルをホストしている Web サイトの URL。 リストの右端のストアである必要があり、リスト内の唯一のストアにすることはできません。
https://SecureInternetSite	シンボルをホストする安全な Web サイトの URL。 これにより、パスワード、Windows ログイン資格情報、証明書、スマートカードをサポートできます。 リストの右端のストアである必要があり、リスト内の唯一のストアにすることはできません。
<空白>	2 つのアスタリスクの間にテキストがない場合、これは既定のダウンストリーム ストアを示します。 この場所は、SymSetHomeDirectory を呼び出すことによって設定されます。 既定値は、呼び出し元アプリケーションのプログラム ディレクトリのすぐ下にある「sym」という名前のディレクトリです。 これは、既定のローカル キャッシュと呼ばれることもあります。

 

HTTP ベースのシンボル ストアは書き込むことができないため、一覧の右端のストアである必要があります。 HTTP ベースのシンボル ストアがストア リストの中央または左にある場合、見つかったファイルをそこにコピーすることはできず、チェーンが壊れてしまいます。 さらに、シンボル ハンドラーは Web サイトからファイルを開くことができないため、HTTP ベースのストアをリストの一番左または唯一のストアにすべきではありません。 SymSrv にこのシンボル パスが指定された場合、SymSrv は、シンボル パスにデフォルトのダウンストリーム ストアが指定されているかどうかに関係なく、ファイルを既定のダウンストリーム ストアにコピーし、そこから開くことで回復を試みます。

例

\\mybuilds\mysymbols のシンボル ストアで SymSrv を使用するには、次のシンボル パスを設定します。

set _NT_SYMBOL_PATH= srv*\\mybuilds\mysymbols

デバッガーが \\mybuilds\mysymbols のシンボル ストアからローカル ディレクトリ c:\localsymbols にシンボル ファイルをコピーするようにシンボル パスを設定するには、次のコマンドを使用します。

set _NT_SYMBOL_PATH=srv*c:\localsymbols*\\mybuilds\mysymbols

デバッガーが \\mybuilds\mysymbols のシンボル ストアからデフォルトのダウンストリーム ストア (通常は c:\debuggers\sym) にシンボル ファイルをコピーするようにシンボル パスを設定するには、次のコマンドを使用します。

set _NT_SYMBOL_PATH=srv**\\mybuilds\mysymbols

カスケード ストアを使用するには、次のシンボル パスを設定します。

set _NT_SYMBOL_PATH = srv*c:\localsymbols*\\NearbyServer\store*https://DistantServer

この例では、SymSrv は最初に c:\localsymbols 内のファイルを検索します。 それが見つかった場合は、ファイルへのパスを返します。 それ以外の場合、SymSrv は \\NearbyServer\store 内のファイルを検索します。 そこにファイルが見つかった場合、SymSrv はファイルを c:\localsymbols にコピーし、ファイルへのパスを返します。 見つからない場合、SymSrv は https://DistantServer でファイルを探し、そこで見つかった場合、SymSrv はファイルを \\NearbyServer\store にコピーし、次に c:\localsymbols にコピーします。

この最後の例では、シンボル パスの慎重なデザインを使用してシンボルのダウンロードを最適化する方法を示します。 作業サイトにデバッガーのグループがあり、すべてのデバッガーが離れた場所からシンボルを取得する必要がある場合は、すべてのデバッガーの近くにシンボル ストアを持つ共通サーバーをセットアップできます。 次に、上記のシンボル パスを使用して、すべてのデバッガーを設定します。 特定のバージョンの foo.pdb を必要とする最初のデバッガは、foo.pdb を https://DistantServer から \\NearbyServer\store にダウンロードし、次に c:\localsymbols にある自身のマシンにダウンロードします。 同じファイルを必要とする次のデバッガは、前のデバッガによってその場所にすでにダウンロードされているため、\\NearbyServer\store からそのファイルをダウンロードできます。 このマルチレベル キャッシュにより、時間とネットワーク帯域幅が大幅に節約されます。

Microsoft シンボル ストア

Microsoft は、Windows オペレーティング システムのさまざまなバージョンのシンボル ファイルを含むインターネット シンボル サーバーへのアクセスを提供します。 このシンボルのカタログは完全であることは保証されていませんが、内容は多岐にわたります。 その他の Microsoft 製品も表されます。

インターネット シンボル サーバーには、ホット フィックス、サービス パック、セキュリティ ロールアップ パッケージ、製品リリースなど、Microsoft Windows オペレーティング システム用のさまざまな Windows シンボルが格納されています。 Windows 製品の現在のベータ版およびリリース候補版に加えて、Microsoft Internet Explorer などの他のさまざまな Microsoft 製品のシンボルもサーバー上で利用できます。

デバッグ中にインターネットにアクセスできる場合は、デバッグ セッション前にシンボル ファイルを個別にダウンロードするのではなく、デバッグ セッション中に必要に応じてシンボルをダウンロードするようにデバッガーを構成できます。 シンボルは指定したディレクトリの場所にダウンロードされ、デバッガはそこからシンボルをロードします。

Microsoft シンボル ストアの URL は https://msdl.microsoft.com/download/symbols です。 次の例は、デバッガー シンボル パスを設定する方法を示しています (c:\DownstreamStore のダウンストリーム ストア パスに置き換えてください)。

srv*c:\DownstreamStore*https://msdl.microsoft.com/download/symbols

圧縮ファイル

SymSrv は、Windows Server 2003 リソース キットで配布された compress.exe ツールを使用して圧縮が実行されている限り、圧縮ファイルを含むシンボル ストアと互換性があります。 圧縮ファイルには、ファイル拡張子の最後の文字としてアンダースコアを付ける必要があります (たとえば、module1.pd_や module2.db_)。 詳細については、SymStore の使用に関するページを参照してください。

カスケードの場合、ターゲット ストアがパスの左端のストアでない限り、ファイルは圧縮されません。 パス内にストアが 1 つだけあり、そこに圧縮ファイルが含まれている場合、既定のダウンストリーム ストアがシンボル パスに示されていない場合でも、SymSrv はファイルを既定のダウンストリーム ストアにコピーし、そこから開きます。

DbgHelp 6.1 以前: マスター ストア内のファイルが圧縮されている場合は、ダウンストリーム ストアを使用する必要があります。 SymSrv は、ダウンストリーム ストアにコピーする前にすべてのファイルを圧縮解除します。

キャッシュの削除

ダウンストリーム ストアをキャッシュとして使用している場合は、いつでもこのディレクトリを削除してディスク領域を節約できます。

さまざまなプログラムや Windows バージョンのシンボル ファイルを含む膨大なシンボル ストアを作成できます。 ターゲット コンピューターで使用されている Windows のバージョンをアップグレードすると、キャッシュされたシンボル ファイルはすべて以前のバージョンと一致します。 キャッシュされたこれらのファイルはこれ以上使用されないため、キャッシュを削除する場合に適したタイミングになる可能性があります。

Debugging Tools for Windows には、ディレクトリ ツリーからファイルを選択的に削除し、最後に使用したファイルを残す、agestore.exe というユーティリティが付属しています。 このツールは、シンボル サーバー ストアから未使用のファイルを排除するために設計されています。 これにより、日付の切り捨てやディレクトリ サイズのアルゴリズムなど、多くのオプションを制御できます。

フラット キャッシュ ディレクトリ

既定のダウンストリーム ストアを、標準のシンボル ツリー構造ではなくフラット ディレクトリとして宣言することができます。 これを行うには、SYMOPT_FLAT_DIRECTORY を使用して SymSetOptions 関数を呼び出します (これにより、SymSrv の SSRVOPT_FLAT_DEFAULT_STORE オプションも設定されます)。 これを行う前に、SymSetHomeDirectory を必ず呼び出してください。それ以外の場合は、シンボル ファイルをプログラム ディレクトリに書き込むことができます。

ポインター ファイル

SymStore では、ターゲット ファイル自体ではなく、ターゲット ファイルを指すファイルを作成して使用できます。 シンボル ストアにこのようなポインター ファイルが含まれている場合、既定では、ポインター ファイルで示されている場所からストアにファイルをコピーします。 ポインター ファイルが指すファイルではなく、ポインター ファイルがコピーされるようにストアを構成するには、ターゲット ストアのルートに wantsptr.txt という名前のファイルを作成します。 wantsptr.txt の内容は重要ではなく、ファイルの存在だけが重要です。

シンボル リストからのファイルの除外

シンボル検索からファイルを除外するには、symsrv.ini またはレジストリでファイル名を指定します。 symsrv.ini でファイルを指定するには、Exclusions という名前のセクションを作成し、ファイルをリストします。 ファイル名には、次の例に示すように、ワイルドカードを含めることができます。

[Exclusions]
dbghelp.pdb
symsrv.*
mso*

Symsrv.iniは、symsrv.dll が存在するのと同じディレクトリに配置する必要があります。 ほとんどのインストールでは、ファイルは存在しないため、新しいファイルを作成する必要があります。

または、除外するファイルをレジストリに格納することもできます。 レジストリ キー HKEY_LOCAL_MACHINE\Software\Microsoft\Symbol Server\Exclusionsを作成します。 各ファイル名を、このキー内の文字列値 (REG_SZ) として格納します。 文字列値の名前に、除外するファイルの名前を指定します。 文字列値の内容を使用して、ファイルが除外される理由を説明するコメントを格納できます。

インストール

SymSrv (symsrv.dll) シンボル サーバーは、Windows 用デバッグ ツール パッケージに含まれています。 読み込む dbghelp.dll のコピーと同じディレクトリにインストールする必要があります。 詳細については、「DbgHelp ライブラリの呼び出し」を参照してください。