Creazione di pacchetti di simboli (estensione snupkg)

Un'esperienza di debug ottimale si basa sulla presenza di simboli di debug perché forniscono informazioni critiche come l'associazione tra il codice compilato e il codice sorgente, i nomi delle variabili locali, le tracce dello stack e altro ancora. È possibile usare i pacchetti di simboli (.snupkg) per distribuire questi simboli e migliorare l'esperienza di debug dei pacchetti NuGet.

Si noti che il pacchetto di simboli non è l'unica strategia per rendere i simboli di debug disponibili per gli utenti della libreria. È anche possibile inserirli embed in dll o exe con la proprietà di progetto seguente: <DebugType>embedded</DebugType>

Prerequisiti

nuget.exe v4.9.0 o versione successiva o dotnet cli v2.2.0 o successiva, che implementano i protocolli NuGet necessari.

Creazione di un pacchetto di simboli

Se si usa l'interfaccia della riga di comando dotnet o MSBuild, è necessario impostare le IncludeSymbols proprietà e SymbolPackageFormat per creare un file snupkg oltre al file con estensione nupkg.

• Aggiungere le proprietà seguenti al file con estensione csproj:

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

• In alternativa, specificare queste proprietà nella riga di comando:

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

  or

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

Se si usa NuGet.exe, è possibile usare i comandi seguenti per creare un file con estensione snupkg oltre al file con estensione nupkg:

nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg

nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg

La proprietà SymbolPackageFormat può avere uno dei due valori seguenti: symbols.nupkg (predefinito) o snupkg. Se questa proprietà non è specificata, verrà creato un pacchetto di simboli legacy.

Nota

Il formato .symbols.nupkg legacy è ancora supportato, ma solo per motivi di compatibilità come i pacchetti nativi (vedere Pacchetti di simboli legacy). Il server di simboli di NuGet.org accetta solo il nuovo formato di pacchetto di simboli .snupkg.

Pubblicazione di un pacchetto di simboli

Nota

Azure Devops Artifacts attualmente non supporta il debug tramite .snupkg file.

1. Per praticità, salvare prima la chiave API con NuGet (vedere Pubblicazione di pacchetti).

   nuget SetApiKey Your-API-Key
   

2. Dopo la pubblicazione del pacchetto principale su nuget.org, eseguire il push del pacchetto di simboli come indicato di seguito.

   nuget push MyPackage.snupkg
   

3. È anche possibile eseguire il push sia dei pacchetti di simboli che di quelli principali contemporaneamente usando il comando seguente. Nella cartella corrente devono essere presenti sia i file con estensione nupkg sia quelli con estensione snupkg.

   nuget push MyPackage.nupkg
   

NuGet pubblicherà entrambi i pacchetti in nuget.org. MyPackage.nupkg verrà pubblicato per primo, seguito da MyPackage.snupkg.

Nota

Se il pacchetto di simboli non viene pubblicato, verificare di aver configurato l'origine di NuGet.org come https://api.nuget.org/v3/index.json. La pubblicazione del pacchetto di simboli è supportata solo dall'API NuGet V3.

Server di simboli NuGet.org

NuGet.org supporta il proprio repository del server di simboli e accetta solo il nuovo formato di pacchetto di simboli .snupkg. I consumer di pacchetti possono usare i simboli pubblicati nel server di simboli nuget.org aggiungendo https://symbols.nuget.org/download/symbols alle loro origini dei simboli in Visual Studio, in modo da consentire l'esecuzione delle istruzioni nel codice del pacchetto nel debugger di Visual Studio. Vedere Specifica di file di simboli (con estensione pdb) e di file di origine nel debugger di Visual Studio per informazioni dettagliate su questo processo.

vincoli del pacchetto di simboli NuGet.org

NuGet.org ha i vincoli seguenti per i pacchetti di simboli:

• Nei pacchetti di simboli sono consentite solo le estensioni di file seguenti: .pdb, .nuspec, .xml.psmdcp, .rels,.p7s
• Nel server dei simboli di NuGet.org sono supportati solo i PDB portabili gestiti.
• I PDB e le DLL con estensione nupkg associate devono essere compilati con il compilatore in Visual Studio versione 15.9 o successiva (vedere Hash di crittografia PDB)

I pacchetti di simboli pubblicati in NuGet.org avranno esito negativo se questi vincoli non vengono soddisfatti.

Nota

I progetti nativi, ad esempio i progetti C++, producono PDB Windows invece dei PDF portabili. Non sono supportati dal server dei simboli di NuGet.org. Usare invece pacchetti di simboli legacy.

Convalida e indicizzazione dei pacchetti di simboli

I pacchetti di simboli pubblicati in NuGet.org subiscono diverse convalide, tra cui l'analisi malware. Se un pacchetto non riesce un controllo di convalida, nella relativa pagina dei dettagli del pacchetto verrà visualizzato un messaggio di errore. Inoltre, i proprietari del pacchetto riceveranno un messaggio di posta elettronica con istruzioni su come risolvere i problemi identificati.

Quando il pacchetto di simboli ha superato tutte le convalide, i simboli verranno indicizzati dai server di simboli di NuGet.org e saranno disponibili per l'utilizzo.

La convalida e l'indicizzazione del pacchetto richiedono in genere meno di 15 minuti. Se la pubblicazione del pacchetto richiede più tempo del previsto, visitare status.nuget.org per verificare se NuGet.org si verificano interruzioni. Se tutti i sistemi sono operativi e il pacchetto non viene pubblicato entro un'ora, accedere a nuget.org e usare il collegamento per contattare il supporto tecnico nella pagina dei dettagli del pacchetto.

Struttura di un pacchetto di simboli

Il pacchetto di simboli (.snupkg) presenta le caratteristiche seguenti:

1. .snupkg ha lo stesso ID e la stessa versione del pacchetto NuGet corrispondente (.nupkg).

2. Il file snupkg ha la stessa struttura di cartelle del corrispondente file con estensione nupkg per qualsiasi FILE DLL o EXE con la distinzione che invece di DLL/EXEs, i file PDF corrispondenti verranno inclusi nella stessa gerarchia di cartelle. I file e le cartelle con estensioni diverse da PDB verranno lasciati fuori dal file con estensione snupkg.

3. Il file con estensione nuspec del pacchetto di simboli ha il SymbolsPackage tipo di pacchetto:

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

4. Se un autore decide di usare un file con estensione nuspec personalizzato per compilare i propri file con estensione nupkg e snupkg, il file con estensione snupkg deve avere la stessa gerarchia di cartelle e gli stessi file descritti in dettaglio al punto 2).

5. I campi seguenti verranno esclusi dal nuspec di snupkg: authors, requireLicenseAcceptanceowners, license type, licenseUrl, e icon.

6. Non usare l'elemento <license>. Un file con estensione snupkg è coperto dalla stessa licenza del file con estensione nupkg corrispondente.

Vedi anche

Prendere in considerazione l'uso del collegamento di origine per abilitare il debug del codice sorgente degli assembly .NET. Per altre informazioni, vedere le linee guida sul collegamento all'origine.

Per altre informazioni sui pacchetti di simboli, vedere la specifica di progettazione Del debug dei pacchetti NuGet e miglioramenti dei simboli.