|
| 1 | +# Packaging |
| 2 | + |
| 3 | +Libraries can be packaged in one or more of the following ways: as part of the .NETCore shared framework, part of a transport package, or as a NuGet package. |
| 4 | + |
| 5 | +## .NETCore Shared framework |
| 6 | + |
| 7 | +To add a library to the .NETCore shared framework, that library's `AssemblyName` should be added to [NetCoreAppLibrary.props](../../src/libraries/NetCoreAppLibrary.props) |
| 8 | + |
| 9 | +The library should have both a `ref` and `src` project. Its reference assembly will be included in the ref-pack for the Microsoft.NETCore.App shared framework, and its implementation assembly will be included in the runtime pack. |
| 10 | + |
| 11 | +Including a library in the shared framework only includes the best applicable TargetFramework build of that library: `$(NetCoreAppCurrent)` if it exists, but possibly `netstandard2.1` or another if that is best. If a library has builds for other frameworks those will only be shipped if the library also produces a [Nuget package](#nuget-package). If a library ships both in the shared framework and a nuget package, it may decide to exclude its latest `$(NetCoreAppCurrent)` build from the package. This can be done by setting `ExcludeCurrentNetCoreAppFromPackage` to true. Libraries should take care when doing this to ensure that whatever asset in the package that would apply to `$(NetCoreAppCurrent)` is functionally equivalent to that which it replaces from the shared framework, to avoid breaking applications which reference a newer package than the shared framework. If possible, it's preferable to avoid this by choosing to target frameworks which can both ship in the package and shared framework. |
| 12 | + |
| 13 | +In some occasions we may want to include a library in the shared framework, but not expose it publicly. To do so, include the library in the `NetCoreAppLibraryNoReference` property in [NetCoreAppLibrary.props](../../src/libraries/NetCoreAppLibrary.props). The library should also be named in a way to discourage use at runtime, for example using the `System.Private` prefix. We should avoid hiding arbitrary public libraries as it complicates deployment and servicing, though some platform specific libraries are in this state due to historical reasons. |
| 14 | + |
| 15 | +Libraries included in the shared framework should ensure all direct and transitive assembly references are also included in the shared framework. This will be validated as part of the build and errors raised if any dependencies are unsatisfied. |
| 16 | + |
| 17 | +Removing a library from the shared framework is a breaking change and should be avoided. |
| 18 | + |
| 19 | +## Transport package |
| 20 | + |
| 21 | +Transport packages are non-shipping packages that dotnet/runtime produces in order to share binaries with other repositories. |
| 22 | + |
| 23 | +### Microsoft.AspNetCore.Internal.Transport |
| 24 | + |
| 25 | +This package represents the set of libraries which are produced in dotnet/runtime and ship in the ASP.NETCore shared framework. We produce a transport package so that we can easily share reference assemblies and implementation configurations that might not be present in NuGet packages that also ship. |
| 26 | + |
| 27 | +To add a library to the ASP.NETCore shared framework, that library should set the `IsAspNetCoreApp` property for its `ref` and `src` project. This is typically done in the library's `Directory.Build.props`, for example https://github.com/dotnet/runtime/blob/98ac23212e6017c615e7e855e676fc43c8e44cb8/src/libraries/Microsoft.Extensions.Logging.Abstractions/Directory.Build.props#L4. |
| 28 | + |
| 29 | +Libraries included in this transport package should ensure all direct and transitive assembly references are also included in either the ASP.NETCore shared framework or the .NETCore shared framework. This is not validated in dotnet/runtime at the moment: https://github.com/dotnet/runtime/issues/52562 |
| 30 | + |
| 31 | +Removing a library from this transport package is a breaking change and should be avoided. |
| 32 | + |
| 33 | +## NuGet package |
| 34 | + |
| 35 | +Libraries to be packaged must be referenced by the [traversal packaging project](../../src/libraries/libraries-packages.proj) and set `IsPackable` to true. By default, all `Libraries/*/src` projects are considered for packaging. |
| 36 | + |
| 37 | +Package versions and shipping state should be controlled using the properties defined by the [Arcade SDK](https://github.com/dotnet/arcade/blob/master/Documentation/ArcadeSdk.md#project-properties-defined-by-the-sdk). Typically libraries should not need to explicitly set any of these properties. |
| 38 | + |
| 39 | +Most metadata for packages is controlled centrally in the repository and individual projects may not need to make any changes to these. One property is required to be set in each project: `PackageDescription`. This should be set to a descriptive summary of the purpose of the package, and a list of common entry-point types for the package: to aide in search engine optimization. Example: |
| 40 | +```xml |
| 41 | +<PackageDescription>Logging abstractions for Microsoft.Extensions.Logging. |
| 42 | + |
| 43 | +Commonly Used Types: |
| 44 | +Microsoft.Extensions.Logging.ILogger |
| 45 | +Microsoft.Extensions.Logging.ILoggerFactory |
| 46 | +Microsoft.Extensions.Logging.ILogger<TCategoryName> |
| 47 | +Microsoft.Extensions.Logging.LogLevel |
| 48 | +Microsoft.Extensions.Logging.Logger<T> |
| 49 | +Microsoft.Extensions.Logging.LoggerMessage |
| 50 | +Microsoft.Extensions.Logging.Abstractions.NullLogger</PackageDescription> |
| 51 | +``` |
| 52 | + |
| 53 | +Package content can be defined using any of the publicly defined Pack inputs: https://docs.microsoft.com/en-us/nuget/reference/msbuild-targets |
| 54 | + |
| 55 | +### TargetFrameworks |
| 56 | + |
| 57 | +By default all TargetFrameworks listed in your project will be included in the package. You may exclude specific TargetFrameworks by setting `ExcludeFromPackage` on that framework. |
| 58 | +```xml |
| 59 | + <PropertyGroup> |
| 60 | + <ExcludeFromPackage Condition="'$(TargetFramework)' == 'net5.0'">true</ExcludeFromPackage> |
| 61 | + </PropertyGroup> |
| 62 | +``` |
| 63 | + |
| 64 | +A common pattern is to build for the latest .NET version, for example to include a library in the shared framework or a transport package, but then excluded this from the NuGet package. This can be done to avoid growing the NuGet package in size. To do this set |
| 65 | +```xml |
| 66 | + <PropertyGroup> |
| 67 | + <ExcludeCurrentNetCoreAppFromPackage>true</ExcludeCurrentNetCoreAppFromPackage> |
| 68 | + </PropertyGroup> |
| 69 | +``` |
| 70 | + |
| 71 | +When excluding TargetFrameworks from a package special care should be taken to ensure that the builds included are equivalent to those excluded. Avoid ifdef'ing the implementation only in an excluded TargetFramework. Doing so will result in testing something different than what we ship, or shipping a nuget package that degrades the shared framework. |
| 72 | + |
| 73 | +### Build props / targets and other content |
| 74 | + |
| 75 | +Build props and targets may be needed in NuGet packages. To define these, author a build folder in your src project and place the necessary props/targets in this subfolder. You can then add items to include these in the package by defining `Content` items and setting `PackagePath` as follows: |
| 76 | +```xml |
| 77 | + <ItemGroup> |
| 78 | + <Content Include="build\netstandard2.0\$(MSBuildProjectName).props" PackagePath="%(Identity)" /> |
| 79 | + <Content Include="build\netstandard2.0\$(MSBuildProjectName).targets" PackagePath="%(Identity)" /> |
| 80 | + </ItemGroup> |
| 81 | +``` |
| 82 | + |
| 83 | +### Analyzers / source generators |
| 84 | + |
| 85 | +Some packages may wish to include a companion analyzer or source-generator with their library. Analyzers are much different from normal library contributors: their dependencies shouldn't be treated as nuget package dependencies, their TargetFramework isn't applicable to the project they are consumed in (since they run in the compiler). To facilitate this, we've defined some common infrastructure for packaging Analyzers. |
| 86 | + |
| 87 | +To include an analyzer in a package, simply add an `AnalyzerReference` item to the project that produces the package that should contain the analyzer |
| 88 | +```xml |
| 89 | + <ItemGroup> |
| 90 | + <AnalyzerReference Include="..\gen\System.Banana.Generators.csproj" /> |
| 91 | + </ItemGroup> |
| 92 | +``` |
| 93 | + |
| 94 | +In the analyzer project make sure to do the following. Ensure it only targets `netstandard2.0` since this is a requirement of the compiler. Enable localization by setting `UsingToolXliff`. Set the `AnalyzerLanguage` property to either `cs` or `vb` if the analyzer is specific to that language. By default the analyzer will be packaged as language-agnostic. Avoid any dependencies in Analyzer projects that aren't already provided by the compiler. |
| 95 | +```xml |
| 96 | + <PropertyGroup> |
| 97 | + <TargetFrameworks>netstandard2.0</TargetFrameworks> |
| 98 | + <UsingToolXliff>true</UsingToolXliff> |
| 99 | + <AnalyzerLanguage>cs</AnalyzerLanguage> |
| 100 | + </PropertyGroup> |
| 101 | +``` |
0 commit comments