NuGet
NuGet NuSpec Fields Explained: Dos and Don’t
If you check out Microsoft’s .nuspec reference page, you’ll see there are over 25 metadata properties you could fill out in a NuGet .nuspec file. And here’s the kicker—once you publish a package, that info is locked in, you can’t edit or change it. Figuring out what to include and how to standardize it all can be a lot of extra, unnecessary work.
Sounds daunting right? The good news is if you’re creating private/internal packages, you can ignore all but five metadata fields in a NuGet package with no consequences. That metadata might help with the discoverability, usability, and— if published to nuget.org— trustworthiness of a package, but for your internal packages, it’s best to keep the .nuspec metadata simple. After all, working with first-party packages means you don’t have to “sell” people on your package and win more downloads.
In this article, we’ll go over the necessary .nuspec metadata fields for your internal projects, which fields can be ignored, and why.
Required .nuspec Metadata Fields
These fields are required to build the package—so you really can’t publish without them.
| Field | Input | Why |
| Package ID | Use company name | To be unique across organizations and possible expansions. Start with the company name and standardize by division. |
| Package Version | Use SemVer w/Prerelease labels | Our “Best Versioning Practices” goes into more detail, but in a nutshell: SemVer using the Prerelease tag is a must. |
| Author | Use company name | Set to one author (like company name or team name) to keep a standard. |
| Description | Use internal Wiki | Use to link to the company Wiki page & maintain the most up-to-date information. |
Though not required, we recommend using:
- Icon: this can be a quick visual cue for differentiating a NuGet package from others in a private repository on Visual Studio.
- Repository: the RepositoryURL and RepositoryType fields will let you Debug NuGet Packages and Libraries.
Metadata Fields to Avoid
These are the fields you don’t need to fill in and will see no negative impact from leaving blank.
| Ignorable Field | Why |
| Copyright | Not needed, since it’s an internal, private NuGet package. |
| Licensing | Not needed, since it’s an internal, private NuGet package. |
| Project URL | Redundant, since the description already links to the internal Wiki. |
| Tags | Complicates searching and is difficult to maintain consistently. |
| Release Notes | Redundant, since the description already links to the internal Wiki. |
| Title | Redundant because of the Project ID. |
| Read Me | Redundant due to the description and internal Wiki. |
| Summary | Redundant due to the description and internal Wiki. |
.nuspec Metadata Best Practices
Trimming out unnecessary metadata from your .nuspec files helps keep your NuGet packages clean and consistent across your organization. Sticking to a standard matters, especially since packages are immutable and can’t be renamed, changed or edited.
Other steps you can take to help promote NuGet standards amongst developers are encouraging versioning best practices, using filters to avoid unwanted packages, and automated scanning for your NuGet packages, giving your teams a head start when packages fall out of policy or vulnerabilities pop up. Being prepared and standardized now means less time spent firefighting down the line.
There’s a lot of info here, so make sure to bookmark this article as a reference. Or better yet, download our eBook, “NuGet at Scale”. It’s loaded with insights on using CI/CD pipelines for your NuGet packages, versioning NuGet packages in scaling organizations, and much more! Download it for free today!
