This article covers how to write libraries for .NET using the .NET CLI. The CLI provides an efficient and low-level experience that works across any supported OS. You can still build libraries with Visual Studio, and if that's your preferred experiencerefer to the Visual Studio guide.

Prerequisites

You need the.NET SDK installed on your machine.

For the sections of this document dealing with .NET Framework versions, you need the.NET Framework installed on a Windows machine.

Additionally, if you wish to support older .NET Framework targets, you need to install targeting packs or developer packs from the.NET Framework downloads page. Refer to this table:

How to target .NET 5+ or .NET Standard

You control your project's target framework by adding it to your project file (.csproj or.fsproj). For guidance on how to choose between targeting .NET 5+ or .NET Standard, see.NET 5+ and .NET Standard.

<Project Sdk="Microsoft.NET.Sdk">  <PropertyGroup>    <TargetFramework>net6.0</TargetFramework>  </PropertyGroup></Project>

<Project Sdk="Microsoft.NET.Sdk">  <PropertyGroup>    <TargetFramework>netstandard2.0</TargetFramework>  </PropertyGroup></Project>

If you want to target .NET Framework versions 4.0 or below, or you wish to use an API available in .NET Framework but not in .NET Standard (for example,System.Drawing), read the following sections and learn how to multitarget.

How to target .NET Framework

Keep in mind that some of the .NET Framework versions used here are no longer supported. Refer to the.NET Framework Support Lifecycle Policy FAQ about unsupported versions.

If you want to reach the maximum number of developers and projects, use .NET Framework 4.0 as your baseline target. To target .NET Framework, begin by using the correct Target Framework Moniker (TFM) that corresponds to the .NET Framework version you wish to support.

You then insert this TFM into theTargetFramework section of your project file. For example, here's how you would write a library that targets .NET Framework 4.0:

<Project Sdk="Microsoft.NET.Sdk">  <PropertyGroup>    <TargetFramework>net40</TargetFramework>  </PropertyGroup></Project>

And that's it! Although this compiled only for .NET Framework 4, you can use the library on newer versions of .NET Framework.

How to multitarget

You may need to target older versions of the .NET Framework when your project supports both the .NET Framework and .NET. In this scenario, if you want to use newer APIs and language constructs for the newer targets, use#if directives in your code. You also might need to add different packages and dependencies for each platform you're targeting to include the different APIs needed for each case.

For example, let's say you have a library that performs networking operations over HTTP. For .NET Standard and the .NET Framework versions 4.5 or higher, you can use theHttpClient class from theSystem.Net.Http namespace. However, earlier versions of the .NET Framework don't have theHttpClient class, so you could use theWebClient class from theSystem.Net namespace for those instead.

Your project file could look like this:

<Project Sdk="Microsoft.NET.Sdk">  <PropertyGroup>    <TargetFrameworks>netstandard2.0;net40;net45</TargetFrameworks>  </PropertyGroup>  <!-- Need to conditionally bring in references for the .NET Framework 4.0 target -->  <ItemGroup Condition="'$(TargetFramework)' == 'net40'">    <Reference Include="System.Net" />  </ItemGroup>  <!-- Need to conditionally bring in references for the .NET Framework 4.5 target -->  <ItemGroup Condition="'$(TargetFramework)' == 'net45'">    <Reference Include="System.Net.Http" />    <Reference Include="System.Threading.Tasks" />  </ItemGroup></Project>

You'll notice three major changes here:

1. TheTargetFramework node has been replaced byTargetFrameworks, and three TFMs are expressed inside.
2. There is an<ItemGroup> node for thenet40 target pulling in one .NET Framework reference.
3. There is an<ItemGroup> node for thenet45 target pulling in two .NET Framework references.

Preprocessor Symbols

The build system is aware of the following preprocessor symbols used in#if directives:

Here is an example making use of conditional compilation per-target:

using System;using System.Text.RegularExpressions;#if NET40// This only compiles for the .NET Framework 4 targetsusing System.Net;#else // This compiles for all other targetsusing System.Net.Http;using System.Threading.Tasks;#endifnamespace MultitargetLib{    public class Library    {#if NET40        private readonly WebClient _client = new WebClient();        private readonly object _locker = new object();#else        private readonly HttpClient _client = new HttpClient();#endif#if NET40        // .NET Framework 4.0 does not have async/await        public string GetDotNetCount()        {            string url = "https://www.dotnetfoundation.org/";            var uri = new Uri(url);            string result = "";            // Lock here to provide thread-safety.            lock(_locker)            {                result = _client.DownloadString(uri);            }            int dotNetCount = Regex.Matches(result, ".NET").Count;            return $"Dotnet Foundation mentions .NET {dotNetCount} times!";        }#else        // .NET Framework 4.5+ can use async/await!        public async Task<string> GetDotNetCountAsync()        {            string url = "https://www.dotnetfoundation.org/";            // HttpClient is thread-safe, so no need to explicitly lock here            var result = await _client.GetStringAsync(url);            int dotNetCount = Regex.Matches(result, ".NET").Count;            return $"dotnetfoundation.org mentions .NET {dotNetCount} times in its HTML!";        }#endif    }}

If you build this project withdotnet build, you'll notice three directories under thebin/ folder:

net40/net45/netstandard2.0/

Each of these contains the.dll files for each target.

How to test libraries on .NET

It's important to be able to test across platforms. You can use eitherxUnit or MSTest out of the box. Both are perfectly suitable for unit testing your library on .NET. How you set up your solution with test projects will depend on thestructure of your solution. The following example assumes that the test and source directories live in the same top-level directory.

1. Set up your solution. You can do so with the following commands:

   mkdir SolutionWithSrcAndTestcd SolutionWithSrcAndTestdotnet new slndotnet new classlib -o MyProjectdotnet new xunit -o MyProject.Testdotnet sln add MyProject/MyProject.csprojdotnet sln add MyProject.Test/MyProject.Test.csproj

   This will create projects and link them together in a solution. Your directory forSolutionWithSrcAndTest should look like this:

   /SolutionWithSrcAndTest|__SolutionWithSrcAndTest.sln|__MyProject/|__MyProject.Test/

2. Navigate to the test project's directory and add a reference toMyProject.Test fromMyProject.

   cd MyProject.Testdotnet reference add ../MyProject/MyProject.csproj

3. Restore packages and build projects:

   dotnet restoredotnet build

4. Verify that xUnit runs by executing thedotnet test command. If you chose to use MSTest, then the MSTest console runner should run instead.

And that's it! You can now test your library across all platforms using command-line tools. To continue testing now that you have everything set up, testing your library is very simple:

1. Make changes to your library.
2. Run tests from the command line, in your test directory, withdotnet test command.

Your code will be automatically rebuilt when you invokedotnet test command.

How to use multiple projects

A common need for larger libraries is to place functionality in different projects.

Imagine you want to build a library that could be consumed in idiomatic C# and F#. That would mean that consumers of your library consume it in ways that are natural to C# or F#. For example, in C# you might consume the library like this:

using AwesomeLibrary.CSharp;public Task DoThings(Data data){    var convertResult = await AwesomeLibrary.ConvertAsync(data);    var result = AwesomeLibrary.Process(convertResult);    // do something with result}

In F#, it might look like this:

open AwesomeLibrary.FSharplet doWork data = async {    let! result = AwesomeLibrary.AsyncConvert data // Uses an F# async function rather than C# async method    // do something with result}

Consumption scenarios like this mean that the APIs being accessed have to have a different structure for C# and F#. A common approach to accomplishing this is to factor all of the logic of a library into a core project, with C# and F# projects defining the API layers that call into that core project. The rest of the section will use the following names:

• AwesomeLibrary.Core - A core project that contains all logic for the library
• AwesomeLibrary.CSharp - A project with public APIs intended for consumption in C#
• AwesomeLibrary.FSharp - A project with public APIs intended for consumption in F#

You can run the following commands in your terminal to produce the same structure as this guide:

mkdir AwesomeLibrary && cd AwesomeLibrarydotnet new slnmkdir AwesomeLibrary.Core && cd AwesomeLibrary.Core && dotnet new classlibcd ..mkdir AwesomeLibrary.CSharp && cd AwesomeLibrary.CSharp && dotnet new classlibcd ..mkdir AwesomeLibrary.FSharp && cd AwesomeLibrary.FSharp && dotnet new classlib -lang "F#"cd ..dotnet sln add AwesomeLibrary.Core/AwesomeLibrary.Core.csprojdotnet sln add AwesomeLibrary.CSharp/AwesomeLibrary.CSharp.csprojdotnet sln add AwesomeLibrary.FSharp/AwesomeLibrary.FSharp.fsproj

This will add the three projects above and a solution file that links them together. Creating the solution file and linking projects will allow you to restore and build projects from a top level.

Project-to-project referencing

The best way to reference a project is to use the .NET CLI to add a project reference. From theAwesomeLibrary.CSharp andAwesomeLibrary.FSharp project directories, you can run the following command:

dotnet reference add ../AwesomeLibrary.Core/AwesomeLibrary.Core.csproj

The project files for bothAwesomeLibrary.CSharp andAwesomeLibrary.FSharp will now referenceAwesomeLibrary.Core as aProjectReference target. You can verify this by inspecting the project files and seeing the following in them:

<ItemGroup>  <ProjectReference Include="..\AwesomeLibrary.Core\AwesomeLibrary.Core.csproj" /></ItemGroup>

You can add this section to each project file manually if you prefer not to use the .NET CLI.

Structuring a solution

Another important aspect of multi-project solutions is establishing a good overall project structure. You can organize code however you like, and as long as you link each project to your solution file withdotnet sln add, you will be able to rundotnet restore anddotnet build at the solution level.