MIT License
Package authoring for .NET Core based libraries (ASPNET Core 1.0, CoreCLR, 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.
Branch | Status |
---|---|
master |
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 \lib\netstandard1.x
directory, where x depends on your library. PCL 259's are all netstandard1.0
.
netstandard
and existing librariesIf you have a package that contains a netstandard
group and your users use packages.config
, you may want to add blank dependency groups. Note that Xamarin Studio 6.1, currently in the alpha channel, supports project.json
and that is the recommended solution.
<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 netstandard1.x
dependencies. NuGet will evaluate netstandard1.x
for any "System.Runtime" based platform, so that effectively means, net45
, wp8
, win8
, wpa81
, xamarin.ios
, monotouch
, and monoandroid
. Those platforms support System.Runtime 4.0.0. If you target a newer set of platforms, like net451
, Win81
and wpa81
(Profile 151), then it's System.Runtime is 4.0.10.
For example, if you're putting a Profile 151 library in netstandard1.1
, 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 netstandard
section.
To sum this up, look at the output of the tool for the netstandard
section. If you have a System.Runtime higher than 4.0.0, and you want to to target net45
, wp8
, win8
, xamarin.ios
, monotouch
, or monoandroid
, then you need to block the netstandard
dependency group by adding blank dependency groups for the other platforms.
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>
Target Frameworks
By default, the tool will add/update a dependency group for the netstandard1.x
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 netstandard1.x
and uap10.0
. An example of this is if your package includes a win8
or win81
library but you'd like the .NET Core-based one to be used there. netstandard1.x
isn't enough as win81
is more specific and would "win." Instead, just copy your netstandard1.x
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>
<!-- netstandard1.x and uap10.0 tfms -->
<NuSpecTfm>auto;uap10.0</NuSpecTfm>
</PropertyGroup>
This tool is a command line that you can call in other ways. The command line exposes additional features targeted at NuGet packages containing cross-compiled libraries. The general syntax for the command line is: RefGen.exe
command
options
. All of the options are required for each command but the order doesn't matter.
There are two commands
Command | Description |
---|---|
generate-single | Single library wtih a fixed set of functionality (eg. PCL 259 or netstandard1.0 ). Usable with csproj /vbproj -based projects that use either packages.config or project.json for their packages |
generate-cross | Library that's cross-compiled enabling more functionality on newer platforms (eg. netstandard1.0 and netstandard1.3 ). Only usable with xproj -based project that use project.json for cross-compiling to several target frameworks |
This is the same functionality that RefGen 1.0 had, extended with support for .NET Standard.
Switch | Description |
---|---|
-m or --moniker | NuGetTargetMonikers -- .NETStandard,Version=v1.4 |
-t or --tfm | TFM's to generate, semi-colon joined. E.g.: auto;uap10.0 |
-n or --nuspec | Full path to NuSpec file |
-p or --project | Full path to project file (csproj/vbproj) |
-f or --file | Full path target files, semi-colon joined |
This functionality is new in version 2.0 and enables the use of xproj/project.json-based cross-compiling projects. It requires use a NuSpec file as calling dotnet pack project.json
doesn't provide a way of trimming the dependencies list.
In this model, you'd typically have a project.json
dependency on NETStandard.Library
. The issue is that when creating your NuPkg, it's better to list the individual dependencies you require instead of a giant meta-package. This RefGen tool enables this scenario.
Switch | Description |
---|---|
-p or --project | Full path to project file (project.json ) |
-d or --directory | Path to base directory where the output folders are created per target framework). The output would be in <directory>\netstandard1.0\MyLib.dll for example. |
-n or --nuspec | Full path to the nuspec file |
-l or --library | Library name, including .dll. MyLibrary.dll , for example |
The 2.0 version will detect/use the 1.x command line options. Updating should not break your scripts.
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.: auto;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
Reference Assemblies
folder 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.netstandard
and .NET Core RC2,
instead of .
(#14)int.MaxValue
(#13)developmentDependency=true
to prevent NuSpec.ReferenceGenerator
from being seen a runtime dependency$(SolutionDir)
and default to parent directory of projectuap10.0
PropertyGroup
from an ItemGroup
.NuSpecTfm
you'll need to update your settings to use PropertyGroup
for that item.Portable-
to ensure the package works for packages.config
based projects.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.