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

  • [アーティクル]

きちんとデバッグできるには、コンパイルされたコードとソースコードの間の関連付け、ローカル変数の名前、スタック トレースなどの重要な情報を提供するデバッグ シンボルが必要です。 シンボル パッケージ (snupkg) を使用すると、これらのシンボルを配布して、お使いの NuGet パッケージのデバッグ エクスペリエンスを向上させることができます。

シンボル パッケージは、ライブラリの利用者がデバッグ シンボルを使用できるようにするための唯一の方法ではないことに注意してください。 プロジェクト プロパティ <DebugType>embedded</DebugType> を使用して、dll または exe にそれらを embed することも可能です。

前提条件

必要な NuGet プロトコルを実装する nuget.exe v4.9.0 以上 または dotnet CLI v2.2.0 以上。

シンボル パッケージを作成する

dotnet CLI または MSBuild を使用する場合は、IncludeSymbols プロパティと SymbolPackageFormat プロパティを設定し、.nupkg ファイルに加えて .snupkg ファイルを作成します。

  • 次のプロパティを .csproj ファイルに追加するか:

    <PropertyGroup>
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
</PropertyGroup>

  • または、コマンド ラインで次のプロパティを指定します:

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

    または

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

NuGet.exe を使用する場合は、次のコマンドを使用すると .nupkg ファイルに加えて .snupkg ファイルを作成できます。

nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg

nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg

SymbolPackageFormat プロパティには、symbols.nupkg (既定値) または snupkg の 2 つの値のいずれかを指定できます。 このプロパティが指定されていない場合は、レガシ シンボル パッケージが作成されます。

Note

従来の形式 .symbols.nupkg は引き続きサポートされますが、これはネイティブ パッケージなどの互換性のみを目的としています (レガシ シンボル パッケージに関する記事を参照)。 NuGet.org のシンボル サーバーは、新しいシンボル パッケージ形式 .snupkg のみを受け入れます。

シンボル パッケージを公開する

Note

Azure Devops Artifacts では、現在のところ、.snupkg ファイルを介したデバッグはサポートされていません。

  1. 便宜上、最初に NuGet で API キーを保存してください (「パッケージを公開する」を参照)。

    nuget SetApiKey Your-API-Key

  2. nuget.org にプライマリ パッケージを公開した後は、次のようにしてシンボル パッケージをプッシュします。

    nuget push MyPackage.snupkg

  3. 以下のコマンドを使用して、プライマリ パッケージとシンボル パッケージの両方を同時にプッシュすることもできます。 .nupkg および .snupkg ファイルの両方が、現在のフォルダーに存在する必要があります。

    nuget push MyPackage.nupkg

NuGet では、両方のパッケージが nuget.org に公開されます。最初に MyPackage.nupkg が、次に MyPackage.snupkg が公開されます。

Note

シンボル パッケージが公開されていない場合は、NuGet.org のソースを https://api.nuget.org/v3/index.json として構成したことを確認します。 シンボル パッケージの公開は、NuGet V3 API によってのみサポートされています。

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

NuGet.org は独自のシンボル サーバー リポジトリをサポートし、新しいシンボル パッケージ形式 .snupkg のみを受け入れます。 パッケージ コンシューマーは Visual Studio で自分のシンボル ソースに https://symbols.nuget.org/download/symbols を追加することで、nuget.org シンボル サーバーに公開されたシンボルを使用できます。それにより、Visual Studio デバッガーでパッケージ コードに入ることができます。 このプロセスの詳細については、「Visual Studio デバッガーでのシンボル (.pdb) ファイルとソース ファイルの指定」を参照してください。

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

NuGet.org には、シンボル パッケージに対して次の制約があります。

  • シンボル パッケージでは、次のファイル拡張子のみが許可されます: .pdb、.nuspec、.xml、.psmdcp、.rels、.p7s
  • NuGet.org のシンボル サーバーでは管理対象のポータブル PDB のみがサポートされています。
  • PDB と関連付けられている .nupkg DLL は、Visual Studio バージョン 15.9 以上のコンパイラでビルドする必要があります (「PDB 暗号化ハッシュ」を参照)

これらの制約が満たされない場合、NuGet.org に発行されたシンボル パッケージは検証に失敗します。

Note

C++ プロジェクトなどのネイティブ プロジェクトでは、ポータブル PDB ではなく Windows PDB が生成されます。 これらは、NuGet.org のシンボル サーバーではサポートされていません。 代わりに レガシ シンボル パッケージを使用してください。

シンボル パッケージの検証とインデックスの作成

NuGet.org に発行されたシンボル パッケージは、マルウェアのスキャンなど、いくつかの検証を受けます。 パッケージが検証チェックに失敗した場合、そのパッケージの詳細ページにエラー メッセージが表示されます。 さらに、パッケージの所有者は、特定された問題の修正方法を示す電子メールを受信します。

シンボル パッケージがすべての検証に合格すると、そのシンボルは NuGet. org のシンボル サーバーによってインデックス付けされ、使用可能になります。

パッケージの検証とインデックスの作成は、通常、15 以内で完了します。 パッケージの公開に予想以上の時間がかかる場合、status.nuget.org にアクセスし、Nuget.org に中断が発生していないか確認してください。 すべてのシステムが動作しているとき、1 時間以内にパッケージが正常に公開されない場合、nuget.org にログインし、パッケージの詳細ページの [Contact Support] リンクからお問い合わせください。

シンボル パッケージ構造

シンボル パッケージ (.snupkg) には、次の特徴があります。

  1. .snupkg の ID とバージョンは、対応する NuGet パッケージ (.nupkg) のものと同じです。

  2. .snupkg のすべての DLL や EXE ファイルのファイル構造は、DLL および EXE ではなくそれに対応する PDB が同じフォルダ構造に含まれることを除き、それと対応する nupkg と全く同じです。 PDB 以外の拡張子のファイルとフォルダーは snupkg から除外されたままになります。

  3. シンボル パッケージの .nuspec ファイルのパッケージの種類は、SymbolsPackage です。

    <packageTypes>
   <packageType name="SymbolsPackage"/>
</packageTypes>

  4. 作成者が nupkg と snupkg のビルドにカスタムの nuspec を使用した場合、snupkg には 2) で説明したものと同じフォルダ階層とファイルが含まれます。

  5. 次のフィールドは snupkg の nuspec から除外されます: authors、owners、requireLicenseAcceptance、license type、licenseUrl、icon。

  6. <license> 要素は使用しないでください。 .snupkg には、対応する .nupkg と同じライセンスが適用されます。

関連項目

ソース リンクを使用して、.NET アセンブリのソース コードのデバッグを有効にすることを検討してください。 詳細については、「ソース リンクのガイダンス」を参照してください。

シンボル パッケージの詳細については、「NuGet パッケージのデバッグとシンボルの機能強化」の設計仕様を参照してください。