NuSpec Reference Generator
Package authoring for .NET Core based libraries (ASPNet 5, DNX, UWP) has an extra burden on the author as .NET dependencies must be listed in addition to any regular packages you depend on. This could be a long list and it's a challenge to get it right. If you use any of the meta-packages that brings "all" of .NET Core into your project as possible references, how do you know which you actually need?
This tool aims to help by reading your compiled libraries assembly metadata and determine what that list should be. It currently supports any
System.Runtime based project, including "Profile 259"+ PCL's -- that is, a PCL that targets at least .NET 4.5, Windows 8 and Windows Phone 8.
This tool uses some conventions to locate your
nuspec file and input libraries. These can be overridden in your project file. The tool looks for a
.nuspec file with the same name as your target library underneath the solution root directory. By default, it will add/update a
<dependencies> group for the
dotnet TFM, but you can have it generate others by overriding your project file value.
Using NuGet, add
NuSpec.ReferenceGenerator to your library project. On build, it will add/update your nuspec with the correct dependency data for your libraries.
If you have existing package dependencies in your nuspec in the group that aren't picked up by this tool, they'll be silently ignored. This could happen in the case where a HintPath to a Package is missing and the package could not be detected.
When you author your nuspec package, make sure that your library goes into the
dotnet and existing libraries
If you have a package that contains a
dotnet group and targets both new and old platforms, you might need an extra step in your nuspec. This depends on what packages you actually reference in your dotnet section. You might need to add some or all of the following:
<group targetFramework="net45" /> <group targetFramework="wp8" /> <group targetFramework="win8" /> <group targetFramework="wpa81" /> <group targetFramework="xamarin.ios" /> <group targetFramework="monotouch" /> <group targetFramework="monoandroid" />
Depending on the minimum platform versions you target and the minimum platforms supported by your
dotnet dependencies. NuGet will evaluate
dotnet for any "System.Runtime" based platform, so that effectively means,
monoandroid. Those platforms support System.Runtime 4.0.0. If you target a newer set of platforms, like
wpa81 (Profile 151), then it's System.Runtime is 4.0.10.
For example, if you're putting a Profile 151 library in
dotnet, then your System.Runtime is 4.0.10 and will run on .NET 4.5.1 and higher. For older platforms like .NET 4.5, you'll need to add a blank group
<group targetFramework="net45" />
to ensure that those older platforms don't try to add references to the newer dependencies specified in your
To sum this up, look at the output of the tool for the
dotnet section. If you have a System.Runtime higher than 4.0.0, and you want to to target
monoandroid, then you need to block the
dotnet dependency group by adding blank dependency groups for the other platforms.
Options and overriding default behavior
NuSpec Library Content The library files that should be checked for dependencies. Most packages should have a single assembly which the tool will detect. If you have more than one file packaged in your nupkg, then you need to to specify the following in your csproj/vbproj file. You'll also need to specify the project file for it in the next section:
<ItemGroup> <!-- output of this project --> <NuSpecLibContent Include="$(TargetPath)"> <Visible>False</Visible> </NuSpecLibContent> <!-- another library we're distributing in the same nupkg --> <NuSpecLibContent Include="$(TargetDir)AnotherLibrary.dll"> <Visible>False</Visible> </NuSpecLibContent> </ItemGroup>
NuSpec Project Files The library files that should be checked for dependencies. Most packages should have a single assembly which the tool will detect. If you have more than one file packaged in your nupkg, then you need to to specify the following in your csproj/vbproj file:
<ItemGroup> <!-- this project --> <NuSpecProjectFile Include="$(MSBuildThisFileFullPath)"> <Visible>False</Visible> </NuSpecProjectFile> <!-- another library we're distributing in the same nupkg --> <!-- Note: Order matters here; use the same order as for NuSpecLibContent --> <NuSpecProjectFile Include="$(SolutionDir)AnotherLibrary\AnotherLibrary.csproj"> <Visible>False</Visible> </NuSpecProjectFile> </ItemGroup>
NuSpec File By default, the tool will look for a .nuspec file with the same name as your library underneath your solution directory, recursively. If your .nuspec has a different filename, then you need to specify it in your csproj/vbproj file:
<ItemGroup> <!-- example NuSpec file that must be specified --> <NuSpecFile Include="$(SolutionDir)package\.nuspec"> <Visible>False</Visible> </NuSpecFile> </ItemGroup>
By default, the tool will add/update a dependency group for the
dotnet TFM for a PCL or
uap10.0 for a UWP Class Library.
In some cases, you may need to have multiple dependency groups, like having both
uap10.0. An example of this is if your package includes a
win81 library but you'd like the .NET Core-based one to be used there.
dotnet isn't enough as
win81 is more specific and would "win." Instead, just copy your
dotnet library to also be under
\lib\uap10.0 and specify an additional TFM for the tool to add/update. This should be a semi-colon joined list.
<PropertyGroup> <!-- dotnet and uap10.0 tfms --> <NuSpecTfm>dotnet;uap10.0</NuSpecTfm> </PropertyGroup>
This tool is a command line that you can call in other ways. The parameters are as follows and they are all required:
// args 0: NuGetTargetMoniker: .NETPlatform,Version=v5.0 // args 1: TFM's to generate, semi-colon joined. E.g.: dotnet;uap10.0 // args 2: nuspec file, full path // args 3: project file (csproj/vbproj, etc) full path. Used to look for packages.config/project.json and references. should match order of target files // args 4: target files, semi-colon joined, full path
- This tool does not currently run on mono if you're using an "classic PCL". The tool needs all of the PCL contracts from the
Reference Assembliesfolder for comparison; if there's an equiv on Mono, then this could be fixed. Alternatively, if you only need project.json based projects, then there's no limitation.
- 1.4.2: Add a more descriptive error message for NuSpec files that have incorrect XML namespace declarations
- 1.4.1: Issue warning and do not run RefGen on non-Windows systems until full mono compatibility is tested and verified. Prevents breaking builds.
- 1.4: Fix issue where BCL libs weren't detected correctly for PCL projects using project.json instead of packages.config
- 1.3.6: Fix TFM version parsing when running on cultures that use
- 1.3.5: Fix for pre-release number parsing so that it can work with a "number" group that is larger than
- 1.3.4: Set
NuSpec.ReferenceGeneratorfrom being seen a runtime dependency
- 1.3.3: Add backslash to NuSpecFile search path when SolutionDir isn't defined, don't define SolutionDir if it's not already defined
- 1.3.2: Check for blank
$(SolutionDir)and default to parent directory of project
- 1.3.1: Set default TFM for UWP class libraries to
- 1.3: Fix bug when using with UWP class libraries. Also include support for projectName.project.json added in NuGet 3.2.
- 1.2: Prevent included items (nuspec, project files, libraries) from showing up in Visual Studio. Changed NuSpecTfm to a
- If you were setting
NuSpecTfmyou'll need to update your settings to use
PropertyGroupfor that item.
- 1.0.1: Add
Portable-to ensure the package works for
- 1.0: Initial Release
If you find any issues, please open an issue in the tracker and/or ping me (@onovotny) on Twitter and I'll try to help.