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

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

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

[前提条件]

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

シンボル パッケージの作成

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

  • 次のプロパティを .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

    Tip

    NuGet 7.6 以降では、SetApiKeyを使用する代わりに、NUGET_API_KEYとNUGET_SYMBOL_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 デバッガーの Specify シンボル (.pdb) ファイルとソース ファイルを参照してください。

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

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

  • シンボル パッケージでは、 .pdb、 .nuspec、 .xml、 .psmdcp、 .rels、 .p7s
  • NuGet.org のシンボル サーバーでは、マネージド ポータブル PDB のみがサポートされます。
  • PDB とそれに関連付けられている .nupkg DLL は、バージョン 15.9 以降Visual Studioコンパイラでビルドする必要があります (PDB 暗号化ハッシュ)

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

Note

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

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

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

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

パッケージの検証とインデックス作成には通常、15 分以内かかります。 パッケージの発行に予想以上の時間がかかる場合は、 status.nuget.org にアクセスして、NuGet.org で中断が発生しているかどうかを確認してください。 すべてのシステムが稼働していて、パッケージが 1 時間以内に正常に発行されていない場合は、nuget.org にログインし、パッケージの詳細ページの [サポートに問い合わせる] リンクを使用して、お問い合わせください。

シンボル パッケージの構造

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

  1. .snupkg は、対応する NuGet パッケージ (.nupkg) と同じ ID とバージョンを持っています。

  2. .snupkg は、DLL または EXE ファイルの対応する .nupkg と同じフォルダー構造を持ち、DLL/EXE ではなく、対応する PDB が同じフォルダー階層に含まれるという区別があります。 PDB 以外の拡張子を持つファイルとフォルダーは、snupkg から除外されます。

  3. シンボル パッケージの .nuspec ファイルには、 SymbolsPackage パッケージの種類があります。

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

  4. 作成者がカスタム nuspec を使用して nupkg と snupkg をビルドする場合、snupkg には同じフォルダー階層と 2 で詳しく説明されているファイルが必要です。

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

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

こちらも参照ください

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

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

  • Last updated on