シンボル パッケージ (.snupkg) の作成Creating symbol packages (.snupkg)

シンボル パッケージを利用すると、NuGet パッケージのデバッグがしやすくなります。Symbol packages allow you to improve the debugging experience of your NuGet packages.

必須コンポーネントPrerequisites

必要な NuGet プロトコルを実装する、nuget.exe v4.9.0 以上または dotnet.exe v2.2.0 以上nuget.exe v4.9.0 or above or dotnet.exe v2.2.0 or above, which implement the required NuGet protocols.

シンボル パッケージを作成するCreating a symbol package

dotnet.exe または MSBuild を使用する場合は、IncludeSymbols プロパティと SymbolPackageFormat プロパティを設定し、.nupkg ファイルに加えて .snupkg ファイルを作成します。If you're using dotnet.exe or MSBuild, you need to set the IncludeSymbols and SymbolPackageFormat properties to create a .snupkg file in addition to the .nupkg file.

  • 次のプロパティを .csproj ファイルに追加するか:Either add the following properties to your .csproj file:

    <PropertyGroup>
        <IncludeSymbols>true</IncludeSymbols>
        <SymbolPackageFormat>snupkg</SymbolPackageFormat>
    </PropertyGroup>
    
  • または、コマンド ラインで次のプロパティを指定します:Or specify these properties on the command-line:

    dotnet pack MyPackage.csproj -p:IncludeSymbols=true -p:SymbolPackageFormat=snupkg
    

    oror

    msbuild MyPackage.csproj /t:pack /p:IncludeSymbols=true /p:SymbolPackageFormat=snupkg
    

NuGet.exe を使用する場合は、次のコマンドを使用すると .nupkg ファイルに加えて .snupkg ファイルを作成できます。If you're using NuGet.exe, you can use the following commands to create a .snupkg file in addition to the .nupkg file:

nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg

nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg

SymbolPackageFormat プロパティには、symbols.nupkg (既定値) または snupkg の 2 つの値のいずれかを指定できます。The SymbolPackageFormat property can have one of two values: symbols.nupkg (the default) or snupkg. このプロパティが指定されていない場合は、レガシ シンボル パッケージが作成されます。If this property is not specified, a legacy symbol package will be created.

注意

従来の形式 .symbols.nupkg は引き続きサポートされますが、これは互換性のみを目的としています (レガシ シンボル パッケージに関する記事を参照)。The legacy format .symbols.nupkg is still supported but only for compatibility reasons (see Legacy Symbol Packages). NuGet.org のシンボル サーバーは、新しいシンボル パッケージ形式 .snupkg のみを受け入れます。NuGet.org's symbol server only accepts the new symbol package format - .snupkg.

シンボル パッケージを公開するPublishing a symbol package

  1. 便宜上、最初に NuGet で API キーを保存してください (「パッケージを公開する」を参照)。For convenience, first save your API key with NuGet (see publish a package).

    nuget SetApiKey Your-API-Key
    
  2. nuget.org にプライマリ パッケージを公開した後は、次のようにしてシンボル パッケージをプッシュします。After publishing your primary package to nuget.org, push the symbol package as follows.

    nuget push MyPackage.snupkg
    
  3. 以下のコマンドを使用して、プライマリ パッケージとシンボル パッケージの両方を同時にプッシュすることもできます。You can also push both primary and symbol packages at the same time using the below command. .nupkg および .snupkg ファイルの両方が、現在のフォルダーに存在する必要があります。Both .nupkg and .snupkg files need to be present in the current folder.

    nuget push MyPackage.nupkg
    

NuGet では、両方のパッケージが nuget.org に公開されます。最初に MyPackage.nupkg が、次に MyPackage.snupkg が公開されます。NuGet will publish both packages to nuget.org. MyPackage.nupkg will be published first, followed by MyPackage.snupkg.

注意

シンボル パッケージが公開されていない場合は、NuGet.org のソースを https://api.nuget.org/v3/index.json として構成したことを確認します。If the symbol package isn't published, check that you've configured the NuGet.org source as https://api.nuget.org/v3/index.json. シンボル パッケージの公開は、NuGet V3 API によってのみサポートされています。Symbol package publishing is only supported by the NuGet V3 API.

NuGet.org のシンボル サーバーNuGet.org symbol server

NuGet.org は独自のシンボル サーバー リポジトリをサポートし、新しいシンボル パッケージ形式 .snupkg のみを受け入れます。NuGet.org supports its own symbols server repository and only accepts the new symbol package format - .snupkg. パッケージ コンシューマーは Visual Studio で自分のシンボル ソースに https://symbols.nuget.org/download/symbols を追加することで、nuget.org シンボル サーバーに公開されたシンボルを使用できます。それにより、Visual Studio デバッガーでパッケージ コードに入ることができます。Package consumers can use the symbols published to nuget.org symbol server by adding https://symbols.nuget.org/download/symbols 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.

NuGet.org シンボル パッケージの制約NuGet.org symbol package constraints

NuGet.org には、シンボル パッケージに対して次の制約があります。NuGet.org has the following constraints for symbol packages:

  • シンボル パッケージでは、次のファイル拡張子のみが許可されます: .pdb.nuspec.xml.psmdcp.rels.p7sOnly the following file extensions are allowed in symbol packages: .pdb, .nuspec, .xml, .psmdcp, .rels, .p7s
  • NuGet.org のシンボル サーバーでは管理対象のポータブル PDB のみがサポートされています。Only managed Portable PDBs are supported on NuGet.org's symbol server.
  • PDB と関連付けられている .nupkg DLL は、Visual Studio バージョン 15.9 以上のコンパイラでビルドする必要があります (「PDB 暗号化ハッシュ」を参照)The PDBs and their associated .nupkg DLLs need to be built with the compiler in Visual Studio version 15.9 or above (see PDB crypto hash)

これらの制約が満たされない場合、NuGet.org に発行されたシンボル パッケージは検証に失敗します。Symbol packages published to NuGet.org will fail validation if these constraints aren't met.

シンボル パッケージの検証とインデックスの作成Symbol package validation and indexing

NuGet.org に発行されたシンボル パッケージは、マルウェアのスキャンなど、いくつかの検証を受けます。Symbol packages published to NuGet.org undergo several validations, including malware scanning. パッケージが検証チェックに失敗した場合、そのパッケージの詳細ページにエラー メッセージが表示されます。If a package fails a validation check, its package details page will display an error message. さらに、パッケージの所有者は、特定された問題の修正方法を示す電子メールを受信します。In addition, the package's owners will receive an email with instructions on how to fix the identified issues.

シンボル パッケージがすべての検証に合格すると、シンボルは NuGet. org のシンボル サーバーによってインデックスが作成されます。When the symbol package has passed all validations, the symbols will be indexed by NuGet.org's symbol servers. インデックスが作成されると、シンボルは NuGet.org シンボル サーバーから使用できるようになります。Once indexed, the symbol will be available for consumption from the NuGet.org symbol servers.

パッケージの検証とインデックスの作成は、通常、15 以内で完了します。Package validation and indexing usually takes under 15 minutes. パッケージ公開に予想以上の時間がかかる場合、status.nuget.org にアクセスし、NuGet.org に中断が発生していないか確認してください。If the package publishing is taking longer than expected, visit status.nuget.org to check if NuGet.org is experiencing any interruptions. すべてのシステムが動作しているとき、1 時間以内にパッケージが正常に公開されない場合、nuget.org にログインし、パッケージの詳細ページの [Contact Support] リンクからお問い合わせください。If all systems are operational and the package hasn't been successfully published within an hour, please login to nuget.org and contact us using the Contact Support link on the package details page.

シンボル パッケージ構造Symbol package structure

.nupkg ファイルは全く変わりませんが、.snupkg ファイルには次の特性が含まれます。The .nupkg file would be exactly the same as it is today, but the .snupkg file would have the following characteristics:

  1. .snupkg の ID とバージョンは、対応する .nupkg と同じになります。The .snupkg will have the same id and version as the corresponding .nupkg.

  2. .snupkg のファイル構造は DLL や EXE ファイルの nupkg と全く同じですが、区別されています。対応する PDB が同じフォルダ構造に含まれています。The .snupkg will have the exact folder structure as the nupkg for any DLL or EXE files with the distinction that instead of DLLs/EXEs, their corresponding PDBs will be included in the same folder hierarchy. PDB 以外の拡張子のファイルとフォルダーは snupkg から除外されたままになります。Files and folders with extensions other than PDB will be left out of the snupkg.

  3. .snupkg の .nuspec ファイルでは次に示すように新しい PackageType も指定されます。The .nuspec file in the .snupkg will also specify a new PackageType as below. 指定される PackageType は 1 つだけです。This should the only one PackageType specified.

    <packageTypes>
       <packageType name="SymbolsPackage"/>
    </packageTypes>
    
  4. 作成者が nupkg と snupkg のビルドにカスタムの nuspec を使用した場合、snupkg には 2) で説明したものと同じフォルダ階層とファイルが含まれます。If an author decides to use a custom nuspec to build their nupkg and snupkg, the snupkg should have the same folder hierarchy and files detailed in 2).

  5. authorsowners のフィールドは snupkg の nuspec から除外されます。authors and owners field will be excluded from the snupkg's nuspec.

  6. <license> 要素は使用しないでください。Do not use the <license> element. .snupkg には、対応する .nupkg と同じライセンスが適用されます。A .snupkg is covered under the same license as the corresponding .nupkg.

関連項目See also

ソース リンクを使用して、.NET アセンブリのソース コードのデバッグを有効にすることを検討してください。Consider using Source Link to enable source code debugging of .NET assemblies. 詳細については、「ソース リンクのガイダンス」を参照してください。For more information, please refer to the Source Link guidance.

シンボル パッケージの詳細については、「NuGet パッケージのデバッグとシンボルの機能強化」の設計仕様を参照してください。For more information on symbol packages, please refer to the NuGet Package Debugging & Symbols Improvements design spec.