You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is the simplest type of package. You wish to ship a portable class library in package that you intend to be consumed only in projects supporting nuget v3 and project.json. The `dotnet` target moniker represents all platforms who's .NET surface area can be represented entirely by package dependencies. For many projects using this target moniker will eliminate the need to ever list specific platforms in a package.
3
6
4
-
## .NET library ##
5
-
### pure portable on dotnet ###
6
-
This is the simplest type of package. You wish to ship a portable class library in package that you intend to be consumed only in projects supporting nuget v3 and project.json.
7
-
7
+
The below sample illustrates the dependencies of a project.json based PCL targeting .NET Framework 4.6, Windows Universal 10.0, and ASP.NET Core 5.0. The dependency section can be generated using the third party [NuSpec.ReferenceGenerator](https://www.nuget.org/packages/NuSpec.ReferenceGenerator/) package.
Now lets suppose that we want to target older platforms that don't yet support project.json. The below example changes the PCL to target .NET Framework 4.5, Windows 8, Windows Phone 8.1 and Windows Phone Silverlight 8.
24
20
25
-
### supporting nuget v2 and project types that don't yet support project.json ###
26
-
NuGet v2 and packages.config in Nuget v3 will promote any indirect references to direct references. This creates a problem for the example we have so far since the dependencies of the library cannot always be updated on platforms like .NET desktop or Windows Phone where the packages just represent the surface area in the platform.
21
+
Nuget using packages.config will promote any indirect references to direct references. Nuget will also offer upgrade of any packages directly referenced. This creates a problem for the example we have so far since the dependencies of the library cannot always be updated on platforms like .NET desktop or Windows Phone where the packages just represent the surface area inbox in the platform.
27
22
28
-
To avoid this problem we can add empty dependency groups for all of the platforms where our dependencies are included in box. This should **not** be done for platforms that rely on packages for implementation (like DNXCore, NETCore version >= 5.0, and UAP). This should also **not** be done if the version of the dependency is higher than the one inbox.
23
+
To avoid this problem we can add empty dependency groups for all of the platforms where our dependencies are included in box. This should **not** be done for platforms that rely on packages for implementation (Windows Universal 10.0 and ASP.NET Core 5.0). This should only be done for platforms which you've specifically targeted in the project.
24
+
25
+
In order to also support installation into packages.config based portable projects NuGet requires `portable-` folder and dependency group. The dependency group is needed for the same reason as above, the file is needed because NuGet does not treat any `portable-` targets as compatible with `dotnet`.
The .NET and NuGet team hope to eliminate the need to create these additional dependency groups in future releases.
61
52
62
-
The .NET and NuGet team hope to eliminate the need to do this in future releases.
63
-
64
-
### native library ###
53
+
### 1.3 Native library ###
65
54
Some libraries can benefit from using a native component within their package. This can help to provide a performance optimized native implementation of an algorithm or directly consume some other native SDK (eg: statically link it or compile against its headers).
66
55
67
-
Add native runtime entries.
56
+
To represent the native component we will use 'runtime/{rid}/native' folders. The '{rid}' used during package restore is determined by the runtimes section of the project.json. The '{rid}' used at package resolve time is determined by the NuGet client and should match one of the {rid}s in the project.json. In the case of the MSBuild client in Visual Studio, this is based on the project's properties like Platform and TargetFramework.
68
57
```
69
58
lib/dotnet/System.Banana.dll
70
-
runtimes/win7-x86/native/cherry.dll
71
-
runtimes/win7-x64/native/cherry.dll
59
+
runtimes/win-x86/native/cherry.dll
60
+
runtimes/win-x64/native/cherry.dll
72
61
runtimes/win10-arm/native/cherry.dll
73
62
```
74
63
Note that we still use `lib` for the managed assembly. This is behaving as both the compile time and runtime asset for the managed assembly. The presense of `runtime/{rid}/native` folders does not replace lib.
@@ -78,35 +67,105 @@ The .NET assembly is likely now runtime specific since it depends on the runtime
78
67
TODO: tooling to produce reference assembly.
79
68
```
80
69
ref/dotnet/System.Banana.dll
81
-
runtimes/win7/lib/dotnet/System.Banana.dll
82
-
runtimes/win7-x86/native/cherry.dll
83
-
runtimes/win7-x64/native/cherry.dll
70
+
runtimes/win/lib/dotnet/System.Banana.dll
71
+
runtimes/win-x86/native/cherry.dll
72
+
runtimes/win-x64/native/cherry.dll
84
73
runtimes/win10-arm/native/cherry.dll
85
74
```
86
75
Note that we now need a `ref` folder. This is because the `runtimes/{rid}/lib/dotnet` folder replaces `lib/dotnet` since it is more specific. Since the `runtimes` folder is only used at runtime we need a seperate definition of the compile time asset.
87
76
88
77
This will give folks the right error when they try to install the package on a new runtime (eg: Linux) instead of permitting the package to install and failing to find the DLL at runtime.
89
78
90
-
### architecture specific implementation ###
79
+
To help produce a reference assembly you can use the Microsoft.DotNet.BuildTools.GenAPI package. TODO: sample.
80
+
81
+
### 1.4 Architecture specific .NET library ###
91
82
It may be necessary to include architecture specific managed code in your package. If this is the case the implementation assembly will need to be placed in architecture specific folders.
92
83
93
84
These folders are only used for the runtime asset from your package, so we'll need to provide a compile time asset. For that we use `ref`. This has the added benefit of making your architecture specific library consumable by AnyCPU projects.
94
85
95
-
TODO: tooling to produce reference assembly.
86
+
To help produce a reference assembly you can use the Microsoft.DotNet.BuildTools.GenAPI package. TODO: sample.
96
87
```
97
88
ref/dotnet/System.Banana.dll
98
89
runtimes/win7-x86/lib/dotnet/System.Banana.dll
99
90
runtimes/win7-x64/lib/dotnet/System.Banana.dll
100
-
runtimes/win10-arm/native/System.Banana.dll
91
+
runtimes/win10-arm/lib/dotnet/System.Banana.dll
92
+
runtimes/win7-x86/native/cherry.dll
93
+
runtimes/win7-x64/native/cherry.dll
94
+
runtimes/win10-arm/native/cherry.dll
95
+
```
96
+
97
+
### 1.5 Support packages.config with `runtimes` ###
98
+
Both of the previous examples used the NuGet v3 project.json feature of `runtimes` to provide OS/architecture specific assets. To do the same for packages.config based projects we'll need to approximate this feature using msbuild targets. We'll add the targets to the 'build/dotnet' folder, matching the target moniker used by our assets and give it the same name as our package.
Note that this assumes only one `{rid}` per architecture. If a package uses multiple `{rid}`s per architcture these targets will be more involved than just `win*`.
126
+
127
+
### 1.6 Cross compiling for additional platforms ###
128
+
Expanding on the previous example, suppose that a single build of a library cannot provide the full functionality on all platforms. For example: you'd like to use the System.IO.MemoryStream.TryGetBuffer. This API is available in System.IO version 4.0.10 which is supported on .NET Framework 4.6, Windows Universal 10.0, and ASP.NET Core 5.0. The API can return the underlying byte array used by the MemoryStream without copying it. On older platforms the API is not available but a similar API ToArray() can be used which does a copy of the byte array.
129
+
130
+
The package will contain two different PCLs.
131
+
Build A targeting .NET Framework 4.5, Windows 8, Windows Phone 8.1 and Windows Phone Silverlight 8, using MemoryStream.ToArray();
132
+
Build B targeting .NET Framework 4.6, Windows Universal 10.0, and ASP.NET Core 5.0, using MemoryStream.TryGetBuffer().
133
+
134
+
```
135
+
<depenedencies>
136
+
<group targetFramework="dotnet">
137
+
<dependency id="System.IO" version="4.0.10"/>
138
+
<dependency id="System.Runtime" version="4.0.0"/>
139
+
</group>
140
+
<!-- all depdencies are inbox in netcore45 / win8 -->
141
+
<group targetFramework="netcore45"/>
142
+
<!-- netcore50 / uap10 dependencies from nuget packages -->
0 commit comments