In a previous post I discussed how to manage and edit solution files using the .net core CLI, in this post I will elaborate on that example and discuss how to use the .net core CLI to help manage and edit your Project and Package references wit the CLI.
What are Project and Package References
When developing a software application you will invariably need to make use of third party software libraries in order to extend or enhance functionality within your application.
Libraries and utility modules are already maintained and optimized by other developers. Rather than writing boilerplate code of our own, using a library is often recommended with respect to its use and performance efficiency.
Before you write code against an external component or connected service, your project should have a
reference to it. A
reference is essentially an entry in a project file that contains the information that you application needs to locate the component or the service.
If you have used other programming languages and frameworks such as PHP, node.js, you may be familiar with
Node Package Manager (npm) respectively.
Composer is a dependency manager for PHP enabling the management of dependencies you require on a project by project basis. This means that Composer will pull in all the required libraries, dependencies and manage them all in one place.
npm runs through the command line and manages dependencies for an application. It also allows users to install Node.js modules that are available on the npm registry.
The .net framework also has package management registries, confusingly there are 3, which ultimately do the same job but in slightly different ways.
- dotnet add package
What is Nuget
NuGet is a free and open-source package manager for the Microsoft development platform.
Since its introduction in 2010, NuGet has evolved into a larger ecosystem of tools and services. NuGet is distributed as a Visual Studio extension.
For most users of the Visual Studio IDE this the default means to add packages to your project.
What is Paket
Paket is a dependency manager for .NET and mono projects, which is designed to work well with NuGet packages and also enables referencing files directly from Git repositories or any HTTP resource.
It enables precise and predictable control over what packages the projects within your application reference.
The .NET Core command-line interface (CLI) is a new cross-platform toolchain for developing .NET applications.
The CLI is a foundation upon which higher-level tools, such as Integrated Development Environments (IDEs), editors, and build orchestrators, can rest.
dotnet add package provides a convenient option to add a package reference to a project file.
After running the command, a compatibility check is undertaken to ensure the package is compatible with the frameworks in the project. If the check passes, a
element is added to the project file and dotnet restore is run.
This is the mechanism we’ll be discussing in the remainder of this article. We’ll be using this mechanism with Visual Studio Code on Ubuntu, however the instructions are not restricted to either the tool or the operating system. As long as you have access to the CLI you can follow along on any operating system and IDE.
Add packages to your Project
Prior to .net core 2.0, the only way to add references to your project was to edit your
.csproj file. Managing dependencies with .NET Core SDK 1.0
The .net core 2.0 CLI now enables you to do all this jiggery-pokery with a neat and intuituve set of commands.
If you have created your .net project and are familiar with managing and editing your project and solution with the CLI.
In our simple example here, we will create a
POCO class library to create Domain Entities for a project. We will create a new Class Library project using
dotnet new classlib and give it a name of
Api.Domain because it is going to contain our Domain Entities. We will then add our class library to our solution file.
dotnet new classlib -n Api.Domain #Create new domain entities library
dotnet sln add "Api.Domain/Api.Domain.csproj"
cd Api.Domain # Change into the directory to add the reference
We will now add a reference to
Automapper – A convention-based object-object mapper – to our project.
AutoMapper uses a fluent configuration API to define an object-object mapping strategy. AutoMapper uses a convention-based matching algorithm to match up source to destination values. Currently, AutoMapper is designed for model projection scenarios to flatten complex object models to DTOs and other simple objects, whose design is better suited for serialization, communication, messaging, or simply an anti-corruption layer between the domain and application layer.
dotnet add package AutoMapper --version 6.1.1
.csproj in VS Code and you will see you project now has a reference to Automapper
<PackageReference Include="AutoMapper" Version="6.1.1" />
You can continue to add as many references you need using the process defined.
Add Project References
During the course of software development will now doubt require to either reference your project to other projects. For instance, in the case of our example we may want to create a Unit Test project and add a reference to our Domain project to start creating unit tests.
dotnet new xunit -n Api.Domain.Tests
dotnet sln add "Api.Domain.Tests/Api.Domain.Tests.csproj"
We have now created our Unit Test project and added it to our solution file. Now we can add a reference to our
Api.Domain project to our
dotnet add Api.Domain.Tests.csproj reference "../Api.Domain/Api.Domain.csproj"
After running that command we will be able to view the Api.Domain.Tests.csproj and confirm our reference exists.
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="15.3.0-preview-20170628-02" />
<PackageReference Include="xunit" Version="2.2.0" />
<PackageReference Include="xunit.runner.visualstudio" Version="2.2.0" />
<ProjectReference Include="..\Api.Domain\Api.Domain.csproj" />
Benefits of the CLI
If you’re accustomed to using Visual Studio you might be thinking so what are the benefits to using the CLI when all that we have done here, is just a simple matter in the IDE, all handled by simple mouse clicks. What are the advantages of doing it this way
- Cross platform – Visual Studio is a great tool, but it’s not really cross platform friendly so if you’r working on Linux & Mac, it’s handy to know CLI
- Server friendly – There may be instances when you will need to do this when working on a headless server i.e. Build Server etc.
Before the advent of the CLI all these operation were quote possible using IDE and it was possible to acheive the above by hand edit XML files, but it was clunky and fiddly.
The .net core cli eventually brings the .net framework upto speed with most other programming CLI’s.
A unique background as business owner, marketing, software development and business development ensures that he can offer the optimum business consultancy services across a wide spectrum of business challenges.