创建旧式符号包 (.symbols.nupkg)Creating legacy symbol packages (.symbols.nupkg)

重要

符号包的新推荐格式为 .snupkg。The new recommended format for symbol packages is .snupkg. 请参阅创建符号包 (.snupkg)See Creating symbol packages (.snupkg).
.symbols.nupkg 仍受支持,但仅出于兼容性原因。.symbols.nupkg is still supported but only for compatibility reasons.

除了为 nuget.org 或其他源生成包之外,NuGet 还支持创建可发布到符号服务器的关联符号包。In addition to building packages for nuget.org or other sources, NuGet also supports creating associated symbol packages that can be published to symbol servers. 旧式符号包格式 .symbols.nupkg 可以推送到 SymbolSource 存储库。The legacy symbol package format, .symbols.nupkg, can be pushed to the SymbolSource repository.

然后,包使用者可将 https://nuget.smbsrc.net 添加到 Visual Studio 中的符号源,它允许在 Visual Studio 调试程序中单步执行包代码。Package consumers can then add https://nuget.smbsrc.net to their symbol sources in Visual Studio, which allows stepping into package code in the Visual Studio debugger. 有关该过程的详细信息,请参阅在 Visual Studio 调试程序中指定符号 (.pdb) 和源文件See Specify symbol (.pdb) and source files in the Visual Studio debugger for details on that process.

创建旧式符号包Creating a legacy symbol package

若要创建旧式符号包,请按照以下约定操作:To create a legacy symbol package, follow these conventions:

  • (使用代码)将主包命名为 {identifier}.nupkg,并包括除 .pdb 文件之外的所有文件。Name the primary package (with your code) {identifier}.nupkg and include all your files except .pdb files.
  • 将旧式符号包命名为 {identifier}.symbols.nupkg,并包括程序集 DLL、.pdb 文件、XMLDOC 文件和源文件(请参阅以下各节)。Name the legacy symbol package {identifier}.symbols.nupkg and include your assembly DLL, .pdb files, XMLDOC files, source files (see the sections that follow).

可使用 -Symbols 选项从 .nuspec 文件或项目文件中同时创建这两个包:You can create both packages with the -Symbols option, either from a .nuspec file or a project file:

nuget pack MyPackage.nuspec -Symbols

nuget pack MyProject.csproj -Symbols

请注意,pack 要求在 Mac OS X 上使用 Mono 4.4.2,但不能在 Linux 系统上使用。Note that pack requires Mono 4.4.2 on Mac OS X and does not work on Linux systems. 在 Mac 上,还必须将 .nuspec 文件中的 Windows 路径名转换为 Unix 样式的路径。On a Mac, you must also convert Windows pathnames in the .nuspec file to Unix-style paths.

旧式符号包结构Legacy symbol package structure

旧式符号包面向多个目标框架的方式可与库包的方式相同,因此 lib 文件夹的结构应与主包的结构完全相同,即仅包括 .pdb 和 DLL 文件。A legacy symbol package can target multiple target frameworks in the same way that a library package does, so the structure of the lib folder should be exactly the same as the primary package, only including .pdb files alongside the DLL.

例如,面向 .NET 4.0 和 Silverlight 4 的旧式符号包具有以下布局:For example, a legacy symbol package that targets .NET 4.0 and Silverlight 4 would have this layout:

\lib
    \net40
        \MyAssembly.dll
        \MyAssembly.pdb
    \sl40
        \MyAssembly.dll
        \MyAssembly.pdb

然后,在名为 src 的单独的特殊文件夹中放入源文件,该文件夹必须遵循源存储库的相对结构。Source files are then placed in a separate special folder named src, which must follow the relative structure of your source repository. 这是因为 PDB 包含指向用于编译匹配 DLL 的源文件的绝对路径,在发布过程中需要找到这些路径。This is because PDBs contain absolute paths to source files used to compile the matching DLL, and they need to be found during the publishing process. 可以去除基路径(通用路径前缀)。例如,假设从以下文件中生成一个库:A base path (common path prefix) can be stripped out. For example, consider a library built from these files:

C:\Projects
    \MyProject
        \Common
            \MyClass.cs
        \Full
            \Properties
                \AssemblyInfo.cs
            \MyAssembly.csproj (producing \lib\net40\MyAssembly.dll)
        \Silverlight
            \Properties
                \AssemblyInfo.cs
            \MySilverlightExtensions.cs
            \MyAssembly.csproj (producing \lib\sl4\MyAssembly.dll)

除了 lib 文件夹之外,旧式符号包需要包含以下布局:Apart from the lib folder, a legacy symbol package would need to contain this layout:

\src
    \Common
        \MyClass.cs
    \Full
        \Properties
            \AssemblyInfo.cs
    \Silverlight
        \Properties
            \AssemblyInfo.cs
        \MySilverlightExtensions.cs

引用 nuspec 中的文件Referring to files in the nuspec

可以通过约定从文件夹结构中生成旧式符号包(如上一部分所述),也可以通过在清单的 files 部分中指定内容进行生成。A legacy symbol package can be built by conventions, from a folder structure as described in the previous section, or by specifying its contents in the files section of the manifest. 例如,若要生成上一部分中显示的包,请使用 .nuspec 文件中的以下内容:For example, to build the package shown in the previous section, use the following in the .nuspec file:

<files>
    <file src="Full\bin\Debug\*.dll" target="lib\net40" />
    <file src="Full\bin\Debug\*.pdb" target="lib\net40" />
    <file src="Silverlight\bin\Debug\*.dll" target="lib\sl40" />
    <file src="Silverlight\bin\Debug\*.pdb" target="lib\sl40" />
    <file src="**\*.cs" target="src" />
</files>

发布旧式符号包Publishing a legacy symbol package

重要

若要将包推送到 nuget.org,必须使用实现所需 NuGet 协议nuget.exe v4.9.1 或更高版本To push packages to nuget.org you must use nuget.exe v4.9.1 or above, which implements the required NuGet protocols.

  1. 为方便起见,请首先保存 NuGet 的 API 密钥(请参阅发布包),它将应用于 nuget.org 和 symbolsource.org,因为 symbolsource.org 会与 nuget.org 进行核对以验证包所有者。For convenience, first save your API key with NuGet (see publish a package, which will apply to both nuget.org and symbolsource.org, because symbolsource.org will check with nuget.org to verify that you are the package owner.

    nuget SetApiKey Your-API-Key
    
  2. 将主包发布到 nuget.org 后,按照以下方式推送旧式符号包,由于文件名中的 .symbols,此步骤将 symbolsource.org 自动用作目标:After publishing your primary package to nuget.org, push the legacy symbol package as follows, which will automatically use symbolsource.org as the target because of the .symbols in the filename:

    nuget push MyPackage.symbols.nupkg
    
  3. 若要发布到另一符号存储库或推送不遵循命名约定的旧式符号包,请使用 -Source 选项:To publish to a different symbol repository, or to push a legacy symbol package that doesn't follow the naming convention, use the -Source option:

    nuget push MyPackage.symbols.nupkg -source https://nuget.smbsrc.net/
    
  4. 还可以使用以下项将主包和符号包同时推送到两个存储库:You can also push both primary and symbol packages to both repositories at the same time using the following:

    nuget push MyPackage.nupkg
    

    备注

    在 nuget.exe 4.5.0 或更高版本中,符号包不会自动推送到 symbolsource.org。需要单独推送符号包,如前面步骤所述。With nuget.exe 4.5.0 or above, the symbols packages are not automatically pushed to symbolsource.org. You would need to push the symbols packages separately as explained in the earlier steps.

在此情况下,向 nuget.org 发布主包后,NuGet 将 MyPackage.symbols.nupkg(如果存在)发布到 https://nuget.smbsrc.net/ (symbolsource.org 的推送 URL)。In this case, NuGet will publish MyPackage.symbols.nupkg, if present, to https://nuget.smbsrc.net/ (the push URL for symbolsource.org), after it publishes the primary package to nuget.org.

请参阅See also