{"id":229040,"date":"2020-04-22T12:06:50","date_gmt":"2020-04-22T19:06:50","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/visualstudio\/?p=229040"},"modified":"2022-06-09T11:35:55","modified_gmt":"2022-06-09T18:35:55","slug":"creating-and-packaging-net-standard-library","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/visualstudio\/creating-and-packaging-net-standard-library\/","title":{"rendered":"Creating and Packaging a .NET Standard library"},"content":{"rendered":"

In this post we will cover how you can create a .NET Standard library and then share that with other developers via NuGet. We will be demonstrating this with Visual Studio for Mac<\/a>, but you can also follow along with Visual Studio, or Visual Studio Code when using the dotnet CLI. If you are on macOS, and haven\u2019t already download Visual Studio for Mac you can download it here<\/a>. We will create a new .NET Standard library from scratch, configure it for NuGet and then publish to nuget.org<\/a>. The sample library will be a logging package.<\/p>\n

When developing your applications, it is common to create some code that you\u2019d like to share with other applications. In cases where the consuming code is near the library code (e.g. in the same repo) you can share the project with a Project Reference<\/a>. In cases where the consuming code is not near the library or a different team\/org needs to consume it, a Project Reference may not be the correct choice. In these cases you can package your library as a NuGet package and then share it using that.<\/p>\n

When using NuGet there are different models of how you can share that NuGet package. You can share the library at nuget.org<\/a> to the entire community or you can create your own NuGet feed<\/a> so that you can have better control over who has access to your library. For this post we will be using nuget.org<\/a>. Most of the content of this post will be relevant no matter how you decided to distribute the package. Let\u2019s get started on creating a sample library project.<\/p>\n

Create the shared library project and add some code<\/h2>\n

The first thing you\u2019ll do when creating a library is to create a library project that will contain the code. In Visual Studio for Mac you can create a new .NET library project. To do this, after launching Visual Studio for Mac you should see the dialog below, click New to get started.<\/p>\n

\"vsmac<\/p>\n

This will launch the New Project Dialog, shown below. On the left hand side select .NET Core > Library.<\/p>\n

\"vsmac<\/p>\n

Note: the .NET Core node on the left-hand side of the New Project Dialog is changing to Web and Cloud and will be moved to the top of the list in the next release. <\/em><\/p>\n

From here you\u2019ll select the .NET Standard template.<\/p>\n

A .NET Standard Library is a class library that targets .NET Standard<\/a>. .NET Standard is a formal specification of .NET APIs that are intended to be available on all .NET implementations. The motivation behind .NET Standard is to establish greater uniformity in the .NET ecosystem.<\/p><\/blockquote>\n

Click Next to proceed. You\u2019ll be prompted to select the Target Framework. After selecting a Target Framework, or going with the default, click Next. You\u2019ll then be prompted to provide a name and location for the project. In this example I specified SayedHa.Log<\/em> as the name of the project to create. Click Create after you have supplied those values. When the project, and solution, are created you\u2019ll see the IDE editor open. It should look like the following image.<\/p>\n

\"vsmac<\/p>\n

The template will create a class named Class1. You can either rename this file, or simply delete and add a new class with the correct name. I\u2019ll take the latter approach.<\/p>\n

To add the new class, right click on the project and select Add > Add Class, give the class the name Logger<\/em>. You can also use Add > Add File, but you\u2019ll need to select the Empty Class template. Add > Add Class is a shortcut with that template pre-selected. Now we need to add some code to this logger class.<\/p>\n

Since this is just an example, the Logger class is going to be very basic. The code for it is below.<\/p>\n

using System;\r\nusing System.Net.Security;\r\n\r\nnamespace SayedHa.Log {\r\n    public class Logger {\r\n        private Logger() { }\r\n        public void Debug(object message) { LogIt(\"Debug\", message, null); }\r\n        public void Debug(object message, Exception ex) { LogIt(\"Debug\", message, ex); }\r\n\r\n        public void Info(object message) { LogIt(\"Info\", message, null); }\r\n        public void Info(object message, Exception ex) { LogIt(\"Info\", message, ex); }\r\n\r\n        public void Error(object message) { LogIt(\"Error\", message, null); }\r\n        public void Error(object message, Exception ex) { LogIt(\"Error\", message, ex); }\r\n\r\n        public void Fatal(object message) { LogIt(\"Fatal\", message, null); }\r\n        public void Fatal(object message, Exception ex) { LogIt(\"Fatal\", message, ex); }\r\n\r\n        public void Verbose(object message) { LogIt(\"Verbose\", message, null); }\r\n        public void Verbose(object message, Exception ex) { LogIt(\"Verbose\", message, ex); }\r\n\r\n        protected void LogIt(string prefix, object message, Exception ex) {\r\n            string formatstr = ex == null ? \"{0}:\\t{1}\" : \"{0}:\\t{1}\\tException:{2}\";\r\n\r\n            Console.WriteLine(string.Format(formatstr, prefix, message, ex));\r\n        }\r\n\r\n        public static Logger GetNewLogger() {\r\n            return new Logger();\r\n        }\r\n    }\r\n}<\/pre>\n
We have now created the Logger class with the methods that we would like to support. Since we are going to distribute this and it will be used by a variety of apps we should create an interface for this so that we can have more flexibility in the future. To create an interface from this class we can use the Extract Interface feature in Visual Studio for Mac. Put your cursor on the name of the class and then right click and select Quick Fix. See below.<\/p>\n
\"vsmac<\/p>\n
After selecting Quick Fix on the class you\u2019ll be prompted to select the quick fix you\u2019d like to apply. \u00a0In this case we will use Extract Interface<\/em>.<\/p>\n
\"vsmac<\/p>\n
After selecting Extract Interface<\/em> a dialog will appear in which you can name the new interface and which methods should be included. By default all methods and properties will be included in the interface, and the proposed name of the interface will be the name of your class prefixed with \u201cI\u201d. For this case we will go with the defaults.<\/p>\n
\"vsmac<\/p>\n
Now the interface has been generated, added to the project and the Logger class has been modified to implement that interface. One additional change that I made to the Logger class was to modify the GetLogger static method to return ILogger instead of Logger. We are done with the code portion, so let\u2019s move on to configure this as a NuGet package.<\/p>\n
Adding properties to support packing<\/h2>\n
Creating a NuGet package from a .NET Standard Library project is very easy. We will use Pack to create a package from this. You could do this now, but it\u2019s best to add some metadata to the project before distributing it. These properties will be shown in nuget.org, and other NuGet servers. We will add some properties to the project file, the .csproj file. To get started, right click on the project and select Edit Project File<\/em>.<\/p>\n
\"Image<\/p>\n
Note: in previous versions of Visual Studio for Mac Edit Project File was nested under Tools in the project context menu.<\/em><\/p>\n
This will open up the project file for editing. We will add several properties to this file. The final result is shown in the snippet that follows, we will explain the properties after the code.<\/p>\n
<Project Sdk=\"Microsoft.NET.Sdk\">\r\n\r\n  <PropertyGroup>\r\n    <TargetFramework>netstandard2.0<\/TargetFramework>\r\n  <\/PropertyGroup>\r\n  \r\n <PropertyGroup>\r\n    <!-- where should the nuget package be created at -->\r\n    <PackageOutputPath>.\/nupkg<\/PackageOutputPath>\r\n    \r\n    <!-- nuget related properties -->\r\n    <Authors>Sayed Ibrahim Hashimi<\/Authors>\r\n    <Description>Sample library showing how to create a .NET library.<\/Description>\r\n    <Version>1.0.0<\/Version>\r\n    <Copyright>Copyright 2020 \u00a9 Sayed Ibrahim Hashimi. All rights reserved.<\/Copyright>\r\n    <PackageLicenseExpression>Apache-2.0<\/PackageLicenseExpression>\r\n    <RepositoryUrl>https:\/\/github.com\/sayedihashimi\/sayedha.samplelibrary<\/RepositoryUrl>\r\n    <RepositoryType>git<\/RepositoryType>\r\n    <PackageIconUrl>https:\/\/raw.githubusercontent.com\/sayedihashimi\/sayedha.samplelibrary\/master\/assets\/icon-120x120.png<\/PackageIconUrl>\r\n    <PackageIcon>icon-120x120.png<\/PackageIcon>\r\n  <\/PropertyGroup>\r\n  <ItemGroup>\r\n    <None Include=\"icon-120x120.png\" Pack=\"true\" PackagePath=\"\\\"\/>\r\n  <\/ItemGroup>\r\n<\/Project><\/pre>\n
These are the properties that I typically set when creating a NuGet package. Descriptions for the properties that I used are below. You can see the full list of NuGet related properties that can be set over at NuGet metadata properties<\/a>.<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Property name<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
PackageOutputPath<\/td>\nPath to where the .nupkg file should be placed.<\/td>\n<\/tr>\n
Authors<\/td>\nName of the author(s) of the project.<\/td>\n<\/tr>\n
Description<\/td>\nDescription that will be shown in nuget.org and other places.<\/td>\n<\/tr>\n
Version<\/td>\nVersion of the NuGet package. For each release to nuget.org this must be unique.<\/td>\n<\/tr>\n
Copyright<\/td>\nCopyright declaration.<\/td>\n<\/tr>\n
PackageLicenseExpression<\/td>\nAn SPDX license identifier<\/a> or expression.<\/td>\n<\/tr>\n
RepositoryUrl<\/td>\nSpecifies the URL for the repository where the source code for the package resides and\/or from which it’s being built.<\/td>\n<\/tr>\n
RepositoryType<\/td>\nRepository type. Examples: git, tfs.<\/td>\n<\/tr>\n
PackageIconUrl<\/td>\nURL for the package icon. This property is being deprecated in favor for PackageIcon. For now it is advised to declare both properties for maximum compatibility, see \u00a0this doc<\/a>.<\/td>\n<\/tr>\n
PackageIcon<\/td>\nIcon to be shown for the package.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
In addition to these properties we also have an item for the Icon.<\/p>\n
After adding this content to your project, you can save and close that file. We are now ready to package this an upload it to nuget.org<\/a>.<\/p>\n
To create the NuGet package, right click on the project in the Solution and select Pack. This will pack your project and put it in the folder specified in the PackageOutputPath property. If you did not set this property, the .nupkg file will be located in a folder under the bin folder. If you are following along using the dotnet CLI execute the dotnet pack<\/a> command to create the NuGet package.<\/p>\n
\"vsmac<\/p>\n
 <\/p>\n
Publish to nuget.org<\/h2>\n
Now we are ready to publish this to nuget.org. We will briefly go over that here, but for more details you can read more in the docs at Publishing packages<\/a>. To publish a package to nuget.org, you\u2019ll need to create and account and sign in. After signing in, click on your profile on the top right and select Upload Package.<\/p>\n
Yes, Visual Studio for Mac uses the “Pad” term for the equivalent of what Visual Studio (Windows) calls “Tool Windows”. There’s discussion about changing that term to align with Windows, but it’s the correct term at this point.<\/p>\n
\"nuget<\/p>\n
You\u2019ll be prompted to upload the .nupkg file. You can find this file in the nupkg folder under the project. If you have customized the PackageOutputPath project property different from the sample, then the file will be located at the path you specified. After you upload the package, the metadata will be presented. It\u2019s good to carefully verify that there are no errors because you cannot change a package version which has been published. After verifying the info, scroll down to the bottom of the package and click Submit.<\/p>\n
\"nuget<\/p>\n
Your package has now been published to NuGet. After a few minutes your package will be index and ready to . Now that it has been published users can add this package to their projects to develop against the API. In Visual Studio for Mac, to add a NuGet package first right click the project in the Solution Pad and select Manage NuGet Packages<\/em>. This will open a dialog that can be used to search and install packages. See the following image.<\/p>\n
\"vsmac<\/p>\n
In this search box on the top right search for the package, sayedha.log in this case, then check the checkbox next to the package to install and finally click Add Package<\/em>. When using Visual Studio the process is similar but with a different UX. When using the command line you can use dotnet add package<\/a>. In the image below you\u2019ll find some sample code of using the package and the output when running the it.<\/p>\n
\"vsmac<\/p>\n
Summary and wrap up<\/h2>\n
In this post we have created a simple .NET Standard library, modified it to be a NuGet package and published it to nuget.org<\/a>. This was a very basic library, when creating more realistic libraries there may be additional things to consider. For example, if you want to support multiple frameworks you will need to make some changes. For more details on that see Cross-platform targeting<\/a> for how to get started with that.<\/p>\n
Make sure to follow us on Twitter at\u00a0@VisualStudioMac<\/a>\u00a0and reach out to the team. Customer feedback is important to us and we would love to hear your thoughts. Alternatively, you can head over to\u00a0Visual Studio Developer Community<\/a>\u00a0to track your issues,\u00a0suggest a feature<\/a>, ask questions, and find answers from others. We use your feedback to continue to improve Visual Studio 2019 for Mac, so thank you again on behalf of our entire team.<\/p>\n
Resources<\/h2>\n