SymSrv の高度な使用方法

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

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

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

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

シンボル パスを設定する

このシンボル サーバーを使用するには、デバッガーと同じディレクトリに symsrv.dll インストールする必要があります。 シンボル パスは、次のコードに示すように設定できます。

set _NT_SYMBOL_PATH = symsrv*ServerDLL*DownstreamStore*\\Server\Share

set _NT_SYMBOL_PATH = symsrv*ServerDLL*\\Server\Share

set _NT_SYMBOL_PATH = srv*DownstreamStore*\\Server\Share

set _NT_SYMBOL_PATH = srv*\\Server\Share

この構文の各部分の説明は次のとおりです。

symsrv
このキーワード (keyword) は常に最初に表示する必要があります。 これは、この項目が通常のシンボル ディレクトリだけでなくシンボル サーバーであることをデバッガーに示します。

ServerDLL
シンボル サーバー DLL の名前を指定します。 SymSrv シンボル サーバーを使用している場合、これは常に symsrv.dll になります。

srv
これは symsrv*symsrv.dll の短縮形です。

DownstreamStore
ダウンストリーム ストアを指定します。 これは、個々のシンボル ファイルをキャッシュするために使用されるローカル ディレクトリまたはネットワーク共有です。

複数のダウンストリーム ストアをアスタリスクで区切って指定できます。 複数のダウンストリーム ストアについては、このページのさらに下の「カスケード ダウンストリーム ストア」で説明します。

ダウンストリーム ストアが通常指定される行に 2 つのアスタリスクを含めると、既定のダウンストリーム ストアが使用されます。 このストアは、ホーム ディレクトリの sym サブディレクトリにあります。 ホーム ディレクトリはデバッガー インストール ディレクトリに既定で設定されます。これを変更するには、!homedir 拡張コマンドを使用するか、DBGHELP_HOMEDIR 環境変数を設定します。

DownstreamStore で存在しないディレクトリが指定されている場合、SymStore はそれを作成しようとします。

DownstreamStore パラメーターが省略され、余分なアスタリスクが含まれていない場合、つまり、アスタリスクが 1 つだけの srv または 2 つのアスタリスクを持つ symsrv を使用する場合、ダウンストリーム ストアは作成されません。 デバッガーは、ローカルにキャッシュすることなく、すべてのシンボル ファイルをサーバーから直接読み込みます。

メモ HTTP または HTTPS サイトからシンボルにアクセスする場合、またはシンボル ストアで圧縮ファイルが使用されている場合は、ダウンストリーム ストアが常に使用されます。 ダウンストリーム ストアが指定されていない場合は、ホーム ディレクトリの sym サブディレクトリに作成されます。

\\Server\Share
リモート シンボル ストアのサーバーと共有を指定します。

ダウンストリーム ストアが使用されている場合、デバッガーは最初にこのストア内のシンボル ファイルを検索します。 シンボル ファイルが見つからない場合、デバッガーは指定された Server と Share からシンボル ファイルを検索し、ダウンストリーム ストアにこのファイルのコピーをキャッシュします。 ファイルは、ツリー内の \\Server\Share の下の場所に対応する DownstreamStore の下のツリー内のサブディレクトリにコピーされます。

シンボル サーバーがシンボル パス内の唯一のエントリである必要はありません。 シンボル パスが複数のエントリで構成されている場合、デバッガーは、シンボル サーバーまたは実際のディレクトリのどちらに名前が付けられているかに関係なく、必要なシンボル ファイルの各エントリを順番 (左から右) に確認します。

いくつか例を挙げます。 シンボル ストアが \\mybuilds\mysymbols にあるシンボル サーバーとして SymSrv を使用するには、次のシンボル パスを設定します。

set _NT_SYMBOL_PATH= symsrv*symsrv.dll*\\mybuilds\mysymbols

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

set _NT_SYMBOL_PATH=symsrv*symsrv.dll*c:\localsymbols*\\mybuilds\mysymbols

デバッガーがシンボル ファイルを HTTPS サイト https://www.company.com/manysymbols からローカル ネットワーク ディレクトリ \\localserver\myshare\mycache にコピーするようにシンボル パスを設定するには、次のコマンドを使用します。

set _NT_SYMBOL_PATH=symsrv*symsrv.dll*\\localserver\myshare\mycache*https://www.company.com/manysymbols

この最後の例は、次のように短縮することもできます。

set _NT_SYMBOL_PATH=srv*\\localserver\myshare\mycache*https://www.company.com/manysymbols

さらに、シンボル パスには、セミコロンで区切られた複数のディレクトリまたはシンボル サーバーを含めることができます。 これにより、複数の場所 (または複数のシンボル サーバー) からシンボルを検索できます。 バイナリにシンボル ファイルが一致しない場合、デバッガーはシンボル サーバーを使用してシンボル ファイルを見つけることができません。これは、正確なパラメーターのみをチェックするためです。 ただし、デバッガーは、従来のシンボル パスを使用して、正しい名前のシンボル ファイルが一致しない場合があり、正常に読み込まれます。 ファイルは技術的には正しいシンボル ファイルではありませんが、有用な情報を提供する可能性があります。

キャッシュの削除

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

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

カスケード ダウンストリーム ストア

任意の数のダウンストリーム ストアをアスタリスクで区切って指定できます。 これらのストアは、カスケード シンボル ストアと呼ばれます。

最初の srv* または symsrv*ServerDLL* の後、後続の各トークンはシンボルの場所を表します。 最も左側のトークンが最初にチェックされます。 空のトークン (1 行に 2 つのアスタリスク、または文字列の末尾にアスタリスクで示されます) は、既定のダウンストリーム ストアを表します。

ここでは、2 つのダウンストリーム ストアを使用して、アクセスされるメイン シンボル ストアからの情報を保持するシンボル パスの例を示します。 これらは、マスター ストア、中間レベルのストア、およびローカル キャッシュと呼ばれる場合があります。

srv*c:\localcache*\\interim\store*https://msdl.microsoft.com/download/symbols

このシナリオでは、SymSrv は最初に c:\localcache でシンボル ファイルを検索します。 それが見つかった場合は、ファイルへのパスを返します。 見つからない場合は、\\interim\store で検索します。 シンボル ファイルが見つかった場合、SymSrv は c:\localcache にコピーし、パスを返します。 見つからない場合、SymSrv は Microsoft パブリック シンボル ストア ( https://msdl.microsoft.com/download/symbols) を検索し、見つかった場合、SymSrv は \\interim\store と c:\localcache の両方にコピーします。

同様の動作は、次のパスを使用して取得されます。

srv**\\interim\store*https://internetsite

この場合、ローカル キャッシュは既定のダウンストリーム ストアであり、マスター ストアはインターネット サイトです。 \\interim\store の中間レベルのストアは、他の 2 つの間で使用するために指定されています。

SymSrv は、カスケード ストアを含むパスを処理すると、読み取りまたは書き込みができないストアをスキップします。 そのため、共有がダウンした場合、エラーが発生することなく、不足しているストアからダウンストリームのストアにファイルがコピーされます。 このエラーの優れた副作用は、マスター ストアが書き込み可能でない限り、ダウンストリーム ストアの 1 つのストリームにフィードする複数のマスター ストアをユーザーが指定できることです。

圧縮されたシンボル ファイルがマスター ストアから取得されると、そのファイルは任意の中間レベルのストアに圧縮形式で格納されます。 ファイルは、パスの一番下のストアで圧縮解除されます。

HTTP および SMB シンボル サーバー パスの操作

前述のように、チェーン (またはカスケード) は、シンボル パス内の各 "*" 区切り記号の間で発生するコピーを指します。 シンボルは、左から右の順序で検索されます。 見つからないと、ファイルが見つかるまで、次の (アップストリーム) シンボル サーバーに対してクエリが実行されます。

見つかった場合、ファイルは (アップストリーム) シンボル サーバーから前の (ダウンストリーム) シンボル サーバーにコピーされます。 これは、(ダウンストリーム) シンボル サーバーごとに繰り返されます。 このようにして、(共有) ダウンストリーム シンボル サーバーには、シンボル サーバーを使用するすべてのクライアントの集合的な作業が設定されます。

チェーンされた UNC パスは SRV* プレフィックスなしで使用できますが、symsrv.dll の高度なエラー処理を使用できるように、SRV* を指定することをお勧めします。

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

HTTP は、(symsrv.dll シンボル ハンドラーによって実装される) SRV* プレフィックスを使用する場合にのみサポートされます。

HTTP および SMB 共有シンボル サーバーのシナリオの例

一般的な UNC のみの展開には、すべてのファイル (\\MainOffice\Symbols) をホストする中央オフィス、サブセット (\\BranchOfficeA\Symbols) をキャッシュするブランチ オフィス、および参照するファイルをキャッシュするデスクトップ (C:\Symbols) が含まれます。

srv*C:\Symbols*\\BranchOfficeA\Symbols*\\MainOffice\Symbols

SMB 共有がプライマリ (アップストリーム) シンボル ストアである場合は、読み取りが必要です。

srv*C:\Symbols*\\MachineName\Symbols

SMB 共有が中間 (ダウンストリーム) シンボル ストアである場合は、読み取り/変更が必要です。 クライアントは、プライマリ シンボル ストアから SMB 共有にファイルをコピーし、次に SMB 共有からローカル フォルダーにコピーします。

srv*C:\Symbols*\\MachineName\Symbols*https://msdl.microsoft.com/download/symbols
srv*C:\Symbols*\\MachineName\Symbols*\\MainOffice\Symbols

SMB 共有が SymProxy 展開の中間 (ダウンストリーム) シンボル ストアである場合は、読み取りのみが必要です。 SymProxy ISAPI フィルターは、クライアントではなく書き込みを実行します。

srv*C:\Symbols*\\MachineName\Symbols*https://SymProxyName/Symbols

複数の HTTP と SMB 共有シンボル サーバー キャッシュのシナリオ

シンボル サーバーとキャッシュの場所の複数のチェーンをセミコロン ";" で区切って指定できます。 シンボルが最初のチェーンにある場合、2 番目のチェーンは走査されません。 シンボルが最初のチェーンに存在しない場合、2 番目のチェーンが走査され、シンボルが 2 番目のチェーンにある場合は、指定した場所にキャッシュされます。 この方法では、最初のチェーンで指定されたプライマリ シンボル サーバーでシンボルが使用できない場合、セカンダリ サーバーのみを使用してプライマリ シンボル サーバーを通常使用できます。

srv*C:\Symbols*\\Machine1\Symbols*https://SymProxyName/Symbols;srv*C:\WebSymbols*https://msdl.microsoft.com/download/symbols

cache*localsymbolcache

シンボルのローカル キャッシュを作成するには、シンボル パスで cache*localsymbolcache 文字列を使用する方法もあります。 これはシンボル サーバー要素の一部ではなく、シンボル パス内の別の要素です。 デバッガーは、指定されたディレクトリ localsymbolcache を使用して、この文字列の右側にあるシンボル パスに表示される任意の要素から読み込まれたシンボルを格納します。 これにより、シンボル サーバーによってダウンロードされたシンボルだけでなく、任意の場所からダウンロードされたシンボルにローカル キャッシュを使用できます。

たとえば、次のシンボル パスでは、\\someshare から取得されたシンボルはキャッシュされません。 \\anothershare から取得したシンボルをキャッシュするには c:\mysymbols を使用します。これは、\\anothershare で始まる要素が cache*c:\mysymbols 要素の右側に表示されるためです。 また、シンボル サーバーで使用される通常の構文 (2 つ以上のアスタリスクを含む srv) により、c:\mysymbols を使用して Microsoft パブリック シンボル ストアから取得されたシンボルをキャッシュします。 さらに、後で .sympath+ コマンドを使用してこのパスに場所を追加すると、これらの新しい要素もキャッシュされます。これは、パスの右側に追加されるためです。

_NT_SYMBOL_PATH=\\someshare\that\cachestar\ignores;srv*c:\mysymbols*https://msdl.microsoft.com/download/symbols;cache*c:\mysymbols;\\anothershare\that\gets\cached

SymSrv がファイルを検索する方法

SymSrv は、目的のシンボル ファイルへの完全修飾 UNC パスを作成します。 このパスは、_NT_SYMBOL_PATH 環境変数に記録されているシンボル ストアへのパスから始まります。 次に、SymbolServer ルーチンを使用して、目的のファイルの名前を識別します。この名前は、ディレクトリ名としてパスに追加されます。 次に、SymbolServer に渡される id、2 つ、および 3 つのパラメーターの連結で構成される別のディレクトリ名が追加されます。 これらの値のいずれかが 0 の場合は省略されます。

結果のディレクトリでシンボル ファイルまたはシンボル ストア ポインター ファイルが検索されます。

この検索が成功した場合、SymbolServer は呼び出し元にパスを渡し、TRUE を返します。 ファイルが見つからない場合、SymbolServer は FALSE を返します。

AgeStore を使用してキャッシュのサイズを小さくする

AgeStore ツールを使用すると、指定した日付より古いキャッシュされたファイルを削除したり、キャッシュの内容を指定したサイズより小さくしたりすることができます。 これは、ダウンストリーム ストアが大きすぎる場合に便利です。 詳しくは、「AgeStore」をご覧ください。