使用 SymSrv

项目
03/12/2024

SymSrv 从中央符号存储中传送符号文件。这些存储可以包含任意数量的符号文件，对应任意数量的程序或操作系统。存储还可以包含二进制文件，这些二进制文件在调试小型转储文件时特别有用。

存储可以包含实际符号和二进制文件，或只包含指向符号文件的指针。如果存储包含指针，SymSrv 将直接从文件源检索实际文件。

SymSrv 还会将大型符号存储区分隔为适合专用调试任务的较小子集。

最后，SymSrv 可以使用操作系统提供的登录信息从 HTTP 或 HTTPS 源获取符号文件。 SymSrv 支持受智能卡、证书以及常规登录名和密码保护的 HTTPS 站点。

设置符号路径

如符号路径中所述，符号路径（_NT_SYMBOL_PATH 环境变量）可以由多个由分号分隔的路径元素组成。如果其中任意一个或多个路径元素以文本“srv*”开头，则该元素是符号服务器，并将使用 SymSrv 查找符号文件。

注意

如果未指定“srv*”文本，但实际路径元素是符号服务器存储，则符号处理程序的行为方式就像指定了“srv*”一样。符号处理程序通过在指定路径的根目录中搜索名为“pingme.txt”的文件的存在性来做出此决定。

正如符号路径由分号分隔的符号路径元素组成一样，符号服务器由星号分隔的符号存储元素组成。 “srv*”前缀后最多可以有 10 个符号存储。列表左侧列出的存储称为下游存储，右侧的存储称为上游存储。

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

如果路径中仅包含一个符号存储元素，则 SymSrv 将尝试直接从该存储使用任何请求的文件。

如果路径中有两个符号存储，SymSrv 将在最左侧的符号存储中查找符号文件。如果文件存在，则使用该文件。如果不存在，则 SymSrv 会在紧靠右侧的符号存储中查找。如果文件存在，则会将其复制到左侧存储中，并从该处打开。

如果存在两个以上的存储，则此行为会一直持续到找到文件或列表中没有更多存储为止。

文件永远不会从除最左侧存储之外的任何其他存储中打开。如果在链中的其他任何位置找到该文件，则会将其复制到它左侧的每个存储中。此复制过程称为“级联”，可提供一些好处，将在本文档后面的部分得到证实。

符号存储的类型

下表显示了支持的符号存储类型的示例。

符号存储类型	说明
\\server\share	远程服务器上共享的完全限定 UNC 路径。
c:\LocalCache	客户端计算机上目录的路径。
https://InternetSite	托管符号的网站的 URL。必须是列表中最右侧的存储，不应是列表中的唯一存储。
https://SecureInternetSite	托管符号的安全网站的 URL。这可以支持密码、Windows 登录凭据、证书和智能卡。必须是列表中最右侧的存储，不应是列表中的唯一存储。
<空白>	如果两个星号之间没有文本，则这表示默认的下游存储。位置是通过调用 SymSetHomeDirectory 设置的。默认值是调用应用程序的程序目录正下方名为“sym”的目录。这有时称为默认本地缓存。

由于无法将基于 HTTP 的符号存储写入其中，因此它必须是列表中最右侧的存储。如果基于 HTTP 的符号存储位于存储列表的中间或左侧，则无法将任何找到的文件复制到其中，并且链将断开。此外，由于符号处理程序无法从网站打开文件，因此基于 HTTP 的存储不应是列表最左侧或唯一的存储。如果 SymSrv 曾出现过此符号路径，它将尝试通过将文件复制到默认的下游存储并将其从该位置打开来恢复，无论符号路径中是否指示默认下游存储。

示例

要将 SymSrv 与 \\mybuilds\mysymbols 上的符号存储结合使用，请设置以下符号路径：

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 的第一个调试器会从 https://DistantServer 中将该版本下载到 \\NearbyServer\store，然后下载到自己计算机上的 c:\localsymbols。需要同一文件的下一个调试器将能够从 \\NearbyServer\store 中下载它，因为它已由上一个调试器下载到该位置。此多级缓存可节省大量时间和网络带宽。

Microsoft 符号存储

Microsoft 提供对 Internet 符号服务器的访问权限，该服务器包含许多版本的 Windows 操作系统的符号文件。此符号目录不能保证完整，但它很广泛。也可以表示其他 Microsoft 产品。

Internet 符号服务器填充了 Microsoft Windows 操作系统的各种 Windows 符号，包括修补程序、Service Packs、安全更新汇总包和零售版本。符号还可用于当前 Beta 版和适用于 Windows 产品的候选发布版本以及各种其他 Microsoft 产品（如 Microsoft Internet Explorer）。

如果你在调试期间有权访问 Internet，则可以将调试器配置为在调试会话期间根据需要下载符号，而不是在调试会话之前单独下载符号文件。符号将下载到指定的目录位置，然后调试器从那里加载它们。

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。

级联时，除非目标存储是路径中最左侧的存储，否则不会解压缩文件。如果路径中只有一个存储并且它包含压缩文件，则 SymSrv 会将该文件复制到默认的下游存储，并从那里打开它，即使未在符号路径中指示默认的下游存储也不例外。

DbgHelp 6.1 及更早版本：如果主存储中的文件已压缩，则必须使用下游存储。 SymSrv 会在将文件复制到下游存储之前解压缩所有文件。

删除缓存

如果使用下游存储作为缓存，可以随时删除此目录以节省磁盘空间。

可以拥有一个庞大的符号存储区，其中包含许多不同程序或 Windows 版本的符号文件。如果升级目标计算机上使用的 Windows 版本，则缓存的符号文件将全部与早期版本匹配。这些缓存的文件不会再使用，因此这可能是删除缓存的好时机。

Windows 调试工具附带一个名为 agestore.exe 的实用程序，此实用程序将有选择性地从目录树中删除文件，保留最近使用的文件。此工具旨在从符号服务器存储中清除未使用的文件。它允许你控制许多选项，包括截止日期和目录大小算法。

平面缓存目录

可以将默认下游存储声明为平面目录，而不是标准符号树结构。为此，请使用 SYMOPT_FLAT_DIRECTORY 调用 SymSetOptions 函数（这还会在 SymSrv 中设置 SSRVOPT_FLAT_DEFAULT_STORE 选项）。在执行此操作之前，请务必调用 SymSetHomeDirectory；否则，符号文件可以写入程序目录。

指针文件

SymStore 可以创建和使用指向目标文件的文件，而不是目标文件本身。如果符号存储包含此类指针文件，则默认值是将文件从指针文件中指示的位置复制到存储区。若要配置存储区，以便复制指针文件而不是它指向的文件，请在目标存储的根目录中创建一个名为 wantsptr.txt 的文件。 wantsptr.txt 的内容并不重要，只有文件存在即可。

从符号列表中排除文件

若要从符号搜索中排除文件，可以在 symsrv.ini 或注册表中指定其名称。若要在 symsrv.ini 中指定文件，请创建一个名为“排除”的部分并列出文件。文件名可以包含通配符，如以下示例所示：

[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 库。

通过