I’ve previously done posts on how to setup both .NET Core 2.1 and .NET Core 2.2. The reason for these posts was because it was still a little shaky exactly which version of the SDK you needed to actually build for these platforms. e.x. If you had .NET Core SDK 2.1, it didn’t actually mean you could build .NET Core 2.1 projects (How infuriating is that?!).

But things have gotten better and now it’s usually just a matter of installing the latest SDK and away you go, so there isn’t really much I could normally write for each version bump. However! .NET Core 3 includes a couple of really important updates that I want to talk about in the future. Windows Forms/WPF development on top of .NET Core, and C# 8. Because of this, I wanted to have a post all written up on setting up your machine for .NET Core 3 development while things are in preview so I don’t have to repeat myself every future post!

Installing the .NET Core 3 Preview SDK

Installing the .NET Core 3 SDK is fairly straight forward. Just head to the download page and grab the SDK (Not the runtime) and install! You do want to ensure you are on the .NET Core 3 page and not the general download page of .NET Core as the current “live” version is 2.2 not 3.

Once installed, you should be able to open a command prompt and run  dotnet --info with the output being something close to :

Of course as long as the version is 3+, you should be good to go.

It’s also important to note that your default SDK on your machine will now be 3 and not 2.2 (Or the previous version you had installed). If you have existing projects that are using this SDK version, you will need to create a new global.json file to be able to run different SDK’s side by side. Luckily there is a great guide on how to do this right here!

Using VS Code

If you like programming in VS Code, then you’re actually good to write .NET Core 3 code right from the get go (Since it’s just a text editor). Obviously you will want to install the “C#” extension if you want all the good intellisense (Including for C# 8 new types), but other than that because builds are all from the command line there isn’t too much to it.

If you want to use C# 8 features in VS Code, see that section of this article below (It’s the same for Visual Studio or VS Code).

Using Visual Studio

A preview version of .NET Core also has a preview version of Visual Studio to accompany it. This can be a little annoying because it’s not just jumping on the “preview” update track for your existing Visual Studio installation, you actually need to download and install a completely new version of Visual Studio. This means another ~6GB of space taken up with a VS version you may use once or twice to try out new features.

I feel the need to point this out because it caught me out initially. The first version of Visual Studio to support .NET Core 3.0 is Visual Studio 2019 Preview 1. Emphasise on the 2019 part because I was wondering why my 2017 preview Visual Studio wasn’t working at first!

You can grab the preview version of Visual Studio here : https://visualstudio.microsoft.com/vs/preview/

I have actually dabbled with a solo installation of the preview version only and not bothered with the current release version. Theoretically it could have a few more bugs in it than the current supported release, but so far so good!

Enabling C# 8 Features

We can enable C# 8 on a project by project basis by editing our .csproj files. Simply open up your project file, and add the following anywhere within your <Project> node :

And that’s literally it (Too easy!).

Some people get trapped thinking that the following will enable C# 8 features :

But remember, version 8 of the language is in preview too. Latest refers to the latest minor version that has actually been released (So at this time, 7.3). If you try and use new features of C# 8, for example the “Range” type, you will get an error like so :

error CS8370: Feature ‘range operator’ is not available in C# 7.3. Please use language version 8.0 or greater.

But other than that, everything is pretty straight forward! Now go ahead and start using Range, AsyncEnumerable, Indices and Nullable Reference Types!

Recently while upgrading a couple of projects to .NET Core 2.2, I came across this error.

A quick google revealed that actually people had the same issue when their projects were going from 2.0 to 2.1 too. And all the fixes seemed kinda flaky and typically involved “Try this and pray” type steps.

To be honest, I know how to fix diagnose and fix the issue, but I don’t really know why that particular error message is the one that comes up.

First thing I noticed is that this error will only ever happen when you’ve tried opening a project in Visual Studio and tried to build. In some cases I’ve been able to build using the dotnet CLI, but not inside Visual Studio. If after building in Visual Studio, I then try and build from the dotnet CLI tool, I then start getting this error too. However if I delete the bin folder and rebuild from the CLI, we are all clear.

Next, in all cases the version of .NET Core I want to target is not available and not selected for my project inside VS. So if I right click my project and view properties, the Target Framework is blank :

This is because the version of Visual Studio that I’m using doesn’t actually support the version of .NET Core I am trying to run. It’s sort of this weird situation where even if you have the correct .NET Core SDK installed, that really only sets you up for using the dotnet CLI and writing code in something like VSCode.

All you need to do is update Visual Studio. Let me put that in big bold letters so people coming from Google can get their answer fast :

You Need To Update Visual Studio

Hopefully that’s clear enough!

Even once you update Visual Studio, you will likely need to delete the bin and obj folders of your project and then rebuild again from VS. Now there may be one very edge case that this doesn’t resolve your issues. And that’s if you are using the very latest preview builds for .NET Core SDK that Visual Studio either doesn’t support yet, or only supports in the Pre-Release version of VS. Rare, but it does happen.

There is some pretty nifty stuff making it’s way into .NET Core 2.2 such as a new route “dispatcher” and inbuilt support for healthchecks. But you’re going to need to set up your workstation (And your project) to handle .NET Core 2.2 first! In previous articles where we’ve updated from 2.0 to 2.1, it’s been a right headache, but slowly Microsoft are getting better at handling this whole version bump thing.

If You Want Preview – Use The Command Line

Just to kick us off, I need to point out that in almost all cases, if you are intending to use the preview SDK’s for .NET Core. You are going to need to be creating, building, and publishing projects from the command line. There is support for Visual Studio for preview SDK’s in some cases, but even opening a preview project in the wrong version of Visual Studio can completely break the project by dumping junk in the bin folder etc.

So again, try and do all of the following without Visual Studio atleast so you know it works. Then you can deal with the headache of Visual Studio!

Installing The .NET Core 2.2 SDK

So remember that there is really two parts to .NET Core. There is the SDK which is how your project is built, and the runtime which is what your application actually runs on.

Let’s first sort out the SDK part of this equation.

We want to go to specifically the .NET Core 2.2 download page and download the latest SDK (Not runtime) for our operating system. Note that this isn’t the general .NET Core download page, the current LTS version of .NET Core is currently 2.1. So that’s the version that gets thrust upon you. You specifically need to skip that, go direct to the 2.2 download page, and install the latest SDK.

After installing, open a command prompt and run the following :

This tells us what it thinks the latest (Or to be more correct, the default) version of the .NET Core SDK we are running.

In this example, I’m currently running version 2.2.100-preview3, which is the latest at the time of writing. Anything 2.2.*** should be fine. It’s also interesting to note that this is a big departure from .NET Core 2.1, where you could have version 2.1.*** of the SDK, and it actually couldn’t build 2.1 projects… So it’s nice Microsoft have tidied that up.

Now if you create a new project using the command line, by default it’s going to be using 2.2 as it’s SDK, but if you want to modify an existing project to use the latest build tools (And remember, the SDK is different to the runtime as we will see later), then you need to modify your global.json.

In the root of your project, you should either already have a global.json or create a new one. The contents of which should look like :

Where the version should match your SDK you just installed.

Without a global.json, you will actually use the default anyway. But it’s good to try and be explicit with what version of the SDK you know everything builds fine with. This is especially true if later you install a new version of the SDK with breaking changes, and all your old projects “automatically” update and break.

Updating A Project Runtime To .NET Core 2.2

Changing the project runtime is actually super easy. Just open up your csproj and bump up your TargetFramework.

Go ahead and build your project using dotnet build  from the command line, and all going well you should be good to go.

If you see an error such as :

Then you currently aren’t running on the latest SDK. Either you have not installed the latest SDK or your global.json in the project/solution folder is pointing to an older version.

Visual Studio Support

.NET Core 2.2 does have support inside Visual Studio but only from version 15.9 Preview 3 onwards. At the time of writing, this means you need to download the pre-release version of Visual Studio here to get access to that specific version.

The installation itself is some 5GB, so unless you really need the full development experience for preview SDK’s, you should probably try and go without!

If you are able to upgrade non pre-release version of Visual Studio to atleast 15.9, then you should be able to open .NET Core 2.2 projects.

There is some pretty nifty new features making their way into .NET Core 2.1, many of which I’ll be blogging about in the near future. One of the not so nifty features is actually being able to target .NET Core 2.1. There is one or two headaches along the way that’s for sure.

Installing And Targeting .NET Core 2.1 SDK

Remember that .NET Core comes in two “parts” as it were. The “SDK” which is essentially the thing that does the “building” of your application, and the actual runtime which does the… running… of the application. The versions of these don’t always match up, but generally speaking when we are talking about .NET Core 2.1, we are talking about a specific version of the runtime. The versions might not always line up because there might be improvements to the “build” tools that don’t actually need a version bump of the runtime. This has caused a real stupid overlap of the versions as we will soon see…

Head over to the “all downloads” page and grab the latest SDK. It’s super important to download the latest SDK from this page, and not from the .NET Core homepage. The one on the homepage is the latest “stable” version that may not support 2.1 (Atleast it doesn’t at the time of writing).  The SDK also comes with the runtime that is vaguely matching (e.g. if you download the latest SDK, you’ll get the latest runtime). Because the version numbers don’t always line up, mostly be looking for the final screen that should atleast tell you you’ve installed a 2.1.0 runtime :

Once installed, from a command prompt run : dotnet --list-sdks . Which should in turn print something like :

Don’t worry about earlier versions for the most part. Just make sure the last one is the one you just installed (It should be!). I just want to point out a major headache at this point. You’ll notice I have three versions of SDKs above 2.1.* And an interesting point about that is that only 2.1.300 actually supports building 2.1. If you try and build using the SDK version 2.1.105, it says it cannot build .NET Core 2.1 projects. Now I know that the versions won’t always line up… But it’s a hell of an annoyance.

Now in the root of your solution you want to “.NET Core 2.1-ify”. You want to add a global.json file to the solution folder or edit the existing one there. Inside this file, the contents should be similar to :

Where version is the very latest .NET Core SDK you downloaded. This actually becomes pretty important when you upgrade because you may have projects you want to use the “old” tooling. I actually already wrote a pretty indepth article on working with two different versions of an SDK side by side here. So if you want to know more about this global.json file does, head over there.

You can run dotnet --version  in your solution directory which will print out the SDK version it’s about to run. If all looks good (e.g. it’s the latest SDK version that you just installed), enter dotnet build . All going well it will build your project!

OK that’s cool, but so far we are just building a .NET Core 2.0 projects with a 2.1 SDK. So let’s change that.

Targeting Core 2.1 Runtime

Targeting the 2.1 runtime is as easy as opening up your projects .csproj file. And changing the TargetFramework tag.

Head to your command prompt and run dotnet build  in your solution directory again. Everything should build fine. If instead you get :

C:\Program Files\dotnet\sdk\2.1.105\Sdks\Microsoft.NET.Sdk\build\Microsoft.NET.TargetFrameworkInference.targets(135,5): error : The current .NET SDK does not support targeting .NET Core 2.1.

Then it is *highly* likely you are building with the wrong SDK. The most likely scenario that I’ve found is that you’ve downloaded a “2.1 SDK” that doesn’t actually build 2.1 projects… As stupid as that sounds. Remember, the first SDK to actually be able to build 2.1 projects is 2.1.300-preview2-008533 . Anything earlier and it’s not gonna happen. The first part of the error actually tells you which SDK you are attempting to use, so make sure it’s the right one.

If you are a command line/notepad/VSCode kinda guy, then you should be all ready to go at this point. If you prefer using Visual Studio, read on!

Dealing With Visual Studio Messiness…

Now the interesting thing about using .NET Core 2.1 in Visual Studio is that VS kind of has it’s own way of doing things sometimes. And you’ll notice that if you open your project in Visual Studio you’ll be prompted with a message like so :

Visual Stdio 2017 version 15.7 or newer is recommended for .NET Core 2.1 projects.

To be honest, I tried playing around with a few of the .NET Core 2.1 specific features and I couldn’t find anything that would outright break inside Visual Studio. But better safe than sorry!

When you want to update Visual Studio, you would typically go Help -> Check for Updates and pick up the update there. In this case you would be (sort of) wrong. At the time of writing Visual Studio version 15.7 is only available as a “preview” download and not as a regular update. If you are already on the latest update of the stable builds, you just get told that you’re all good and you can go away now.

Instead, inside Visual Studio go to Tools -> Get Tools and Features. You’ll be presented with a bunch of workloads that you can change in a sort of popup, instead hit the “X” up the top right of this window. On this screen you are left with, scroll right down to the bottom and select to install the “Preview” Visual Studio Version.

Unfortunately this installs an entirely new version of Visual Studio on your PC. Complete with taking up 5.65GB of your precious SSD space.

For this reason, you may want to wait a bit until these things make it into the regular stream (Or play solely with preview stuff in something like VS Code). I’m a sucker for punishment so I did install it and can confirm the annoying warning message when opening .NET Core 2.1 projects does go away.

In a previous post I talked about building cross platform GUI applications using Eto.Forms. One thing that came up was that to run the applications on Linux, you needed to have Mono installed and to run mono with the executable as an input argument. That’s probably fine if you are building a web application and it’s going to be on limited servers, but if you are distributing a desktop application you may not want to have to guide a user into downloading and using mono themselves.

Luckily, there is actually a way of bundling mono with your application that removes the need for a user to have to download, install, and then run mono. This means you can distribute your application to a Linux machine without any worry about prerequisites.Now I know this isn’t really .NET Core, but one of the most important things about Core is the cross platform-ness. And since Core doesn’t have desktop application support, I may aswell write a little bit on how to make that happen using Mono.

Setup and Install

The craziest thing about looking up how to use Mkbundle on Windows is that there is very little information about it in the past 5 years. Everything I found was from 2013 or earlier, and it was very outdated. It often involved downloading Cygwin and fiddling with paths and environment variables until things just sort of fell into place. To be fair, there comes a time in every Windows developers life when they resign themselves to the fact they will have to install Cygwin for whatever flaky piece of software they need to use, but today is not that day!

Head over to the Mono website and download the latest version for your PC : https://www.mono-project.com/download/stable/

I personally went with the 32 bit, just because everything I read out there was using that version and I didn’t want to run into an issue that “needed” the 32 bit version after all.


This part is important so I’ve put it in bold and put it between horizontal rules just to make sure you read this part! 

After install comes an extremely important step. This might sound like a little side bar but please, if this is your first time trying mkbundle on Windows, you will thank me later. If you try and run MKBundle right away, you will get an error that likely looks like this :

ERROR: The SDK location does not contain a C:\Program Files (x86)\Mono/bin/mono runtime

I smacked my head against the wall for an age with this. Eventually I actually tracked down the source code for mkbundle on Github. And found this line here : https://github.com/mono/mono/blob/master/mcs/tools/mkbundle/mkbundle.cs#L536

What it’s trying to do is check that you have a *file* called “C:\Program Files (x86)\mono\bin\mono”. Now I bold that part about it being a file, because it’s not looking for a directory. On non Windows systems, files don’t need to have extensions (like .exe), but on Windows they typically do. So what we actually need to do is make sure that this “test” passes. And it’s simple. Go to your mono/bin folder. In there, you should find a mono.exe. Make a *copy* of this file, and remove the extension so it is simply called “mono”. And it should sit side by side with your existing exe.

Now this should satisfy the file check and mono should run fine. I have logged a ticket on Github with Mono around this issue here : https://github.com/mono/mono/issues/7731 . So if you have the same problem or you’re coming from Google after smacking your head against the desk repeatedly with this issue, jump on and add your 2 cents!


Fetching The Correct Mono Runtime

OK with that out of the way, after installing everything you should now have a “Mono Command Prompt” available to you on your machine. Just type “Mono” in your start menu and it should pop up!

This works essentially like a regular command prompt, with the Mono commands already built in.

Now the next step is a little tricky. It’s not like you can run mkbundle and suddenly you have an executable for every OS in existence. Instead you need to fetch the runtime for the particular OS you want your application to run on, and bundle it for that particular runtime. If we package an exe with mkbundle right now then the only people that can run that application are people with the same OS (In our case Windows). This is not as dumb as you might first think. If we did do this, it would mean we could distribute an application that could run on Windows without Mono (Obviously), but more importantly without .NET Framework. There is definitely times where this could come in handy, but for now, we want to build for Linux, so let’s do that.

There is supposed to be commands to fetch and download various runtimes to your machine right from the command prompt. Ofcourse, Mono being a flaky POS at times (Sorry, it’s getting irritating working through these issues), the command doesn’t work at all. Instead if we run the command that “should” fetch available runtimes we get :

System.Net.WebException: Error: TrustFailure (The authentication or decryption has failed.)

And if instead we try the command that supposedly will download the runtime we want (For example we know the runtime signature so just slam that in), we will get :

Failure to download the specified runtime from https://download.mono-project.com/runtimes/raw/

So, we have to do everything manually.

First go to this URL : https://download.mono-project.com/runtimes/raw/. You need download the runtime for the particular OS you want to compile to. Once downloaded, you need to extract this to a particular directory in your documents folder. If I downloaded mono 5.10.0 for Ubuntu, then my directory that I extract to should be :  C:\Users\myuser\Documents\.mono\targets\mono-5.10.0-ubuntu-16.04-x64/ .

Once this has been done, we should then be able to run a command within the mono command prompt :  mkbundle --local-targets . The output of this should be all “targets” we have available to us.

mkbundle Command

Navigate to your applications directory that you want to “bundle”. In my case I’ve created a simple “HelloWorldConsole” application that does nothing but print out “Hello Mono World”. Inside this directory I run the following command  mkbundle HelloWorldConsole.exe --simple -o HelloWorldBundleUbuntu --cross mono-5.10.0-ubuntu-16.04-x64  Where HelloWorldConsole.exe is my built console app, the -o flag is what I want the output filename to be, and the –cross flag tells us which runtime we want to compile for.

Looks good to me! But let’s test it. Just for comparison sake, I also run the following command :  mkbundle HelloWorldConsole.exe --simple -o HelloWorldBundleDefault . This will give us a bundled application but it will be using our default mono runtime (Which in this case is Windows). This will be important later for showing the differences.

Just quickly, I also want to show the size difference between our original application, and our bundled app.

 

So in terms of bundling, using Windows mono we add about 4mb. For the Ubuntu bundle, we added 8mb. Your guess is as good as mine when it comes to why the huge size difference, but the main thing is that adding 4 – 8mb actually isn’t that bad when you consider a user now doesn’t have to worry about download mono themselves. That’s actually a relatively small bundle when you think about other assets that may be going along with the app like sound, sprites, images etc.

Let’s go ahead and copy these two bundles to our Ubuntu machine for testing.

First we will take a look at our default bundle. Now this shouldn’t work at all because it’s been built for Windows. We even have a command that we can use to check the file type. So let’s try that.

So straight away it’s telling us this is for Windows. And when we run it…

Yep, so it ain’t happening. Let’s instead try our Ubuntu bundle. First the file command to see if it recognizes that it’s a different sort of application :

So even though under the hood it’s actually the exact same C# executable, it’s been compiled correctly for Ubuntu. And when we run it :

Yes! We did it! It only took me a day of headaches to work out every little issue with mkbundle to get a HelloWorld bundle working on Ubuntu! But we did it!

Final Notes

One final thing I want to say is Mono/mkbundle is pretty crap to work with on Windows. I know there is definitely going to be someone out there that hates me for saying that, but it truly is. Some of these issues that I ran into (Notably the fact it tries to check for an extension-less mono exe when running mkbundle) I can see stackoverflow questions from over a year ago having the exact same problem. That means that these problems are nothing new.

Even the documentation was rife with issues on Windows. Simply put, they didn’t work. In some ways I can understand that Mono is built for non Windows machines in mind, but it is shockingly bad for a product that Microsoft has now taken under it’s wing.

This article is part of a series on setting up a private nuget server. See below for links to other articles in the series.

Part 1 : Intro & Server Setup
Part 2 : Developing Nuget Packages
Part 3 : Building & Pushing Packages To Your Nuget Feed


Packaging up your nuget package and pushing it to your feed is surprisingly simple. The actual push may vary depending on whether you are using a hosted service such as MyGet/VSTS or using your own server. If you’ve gone with a third party service then it may pay to read into documentation because there may be additional security requirements when adding to your feed. Let’s get started!

Packaging

If you have gone with building your library in .NET Standard (Which you should), then the entire packaging process comes down to a single command. Inside your project folder, run  dotnet pack and that’s it! The pack command will restore package dependencies, build your project, and package it into a .nupkg.

You should see something along the lines of the following :

While in the previous article in this series, we talked about managing the version of your nuget package through a props file, you can actually override this version number on the command line. It looks a bit like this  :

I’m not a huge fan of this as it means the version will be managed by your build system which can sometimes be a bit hard to wrangle, but it’s definitely an option if you prefer it.

An issue I ran into early was that many tutorials talk about using nuget.exe from the command line to package things up. The dotnet pack command is actually supposed to run the same nuget command under the hood, but I continually got the following exception :

After a quick google it seemed like I wasn’t the only one with this issue. Switching to the dotnet pack command seemed to resolve it.

Publishing

Publishing might depend on whether you ended up going with a third party hosted nuget service or the official nuget server. A third party service might have it’s own way of publishing packages to a feed (All the way to manually uploading them), but many will still allow the ability to do a “nuget push” command.

The push command looks like the following :

Again this command is supposed to map directly to the underlying nuget.exe command (And it actually worked for me), but it’s better to just use the dotnet command instead.

If you are using a build server like VSTS, Team City, or Jenkins, they likely have a step for publishing a nuget package that means you don’t have to worry about the format of the push command.

Working With VSTS

For my actual nuget server, I ended up going with Microsoft VSTS as the company I am working with already had their builds/releases and source control using this service. At first i was kinda apprehensive because other VSTS services I’ve used in the past have been pretty half assed. So color me completely surprised when their package hosting service was super easy to use and had some really nifty features.

Once a feed has been created in VSTS, publishing to it is as easy as selecting it from a drop down list in your build.

After publishing packages, you can then set them to be prerelease or general release too. In a small dev shop this may seem overkill, but in large distributed teams being able to manage this release process in a more granular way is pretty nifty.

You can even unlist packages (So that they can’t be seen in the feed, but they aren’t completely deleted) see a complete history of publishes to the feed, and how many times the package has been downloaded. Without sounding like a complete shill, Microsoft definitely got this addon right.

Summary

So that’s it. From setting up the server (Or hosted service as it turned out), developing the packages (Including wrangling version numbers), and putting everything together with our build server, it’s been surprisingly easy to get a nuget server up and running. If you’ve followed along and setup your own server, or you’ve already got one up and running (Possibly on a third party service), drop a comment and let me know how it’s working out!

This article is part of a series on setting up a private nuget server. See below for links to other articles in the series.

Part 1 : Intro & Server Setup
Part 2 : Developing Nuget Packages
Part 3 : Building & Pushing Packages To Your Nuget Feed


In our previous article in this series, we looked at how we might go about setting up a nuget server. With that all done and dusted, it’s on to actually creating the libraries ourselves. Through trial and error and a bit of playing around, this article will dive into how best to go about developing the packages themselves. It will include how we version packages, how we go about limiting dependencies, and in general a few best practices to play with.

Use .NET Standard

An obvious place to begin is what framework to target. In nearly all circumstances, you are going to want to target .NET Standard (See here to know what .NET Standard actually is). This will allow you to target .NET Core, Full Framework and other smaller runtimes like UWP or Mono.

The only exception to the rule is going to come when you are building something especially specific for those runtimes. For example a windows form library that will have to target full framework.

Limit Dependencies

Your libraries should be built in such a way that someone consuming the library can use as little or as much as they want. Often this shows up when you add in dependencies to your library that only a select people need to use. Remember that regardless of whether someone uses that feature or not, they will need to drag that dependency along with them (And it may also cause versioning issues on top of that).

Let’s look at a real world example. Let’s say I’m building a logging library. Somewhere along the way I think that it would be handy to tie everything up using Autofac dependency injection as that’s what I mostly use in my projects. The question becomes, do I add Autofac to the main library? If I do this, anyone who wants to use my library needs to either also use Autofac, or just have a dependency against it even though they don’t use the feature. Annoying!

The solution is to create a second project within the solution that holds all our Autofac code and generate a secondary package from this project. It would end up looking something like this :

Doing this means that anyone who wants to also use Autofac can reference the secondary package (Which also has a dependency on the core package), and anyone who wants to roll their own dependency injection (Or none at all) doesn’t need to reference it at all.

I used to think it was annoying when you searched for a nuget package and found all these tiny granular packages. It did look confusing. But any trip to DLL Hell will make you thankful that you can pick and choose what you reference.

Semantic Versioning

It’s worth noting that while many Microsoft products use a 4 point versioning system (<major>.<minor>.<build>.<revision>), Nuget packages work off whats called “Semantic Versioning” or SemVer for short. It’s a 3 point versioning system that looks like <major>.<minor>.<patch>. And it’s actually really simple and makes sense when you look at how version points are incremented.

<major> is updated when a new feature is released that breaks backwards compatibility. For example if someone upgrades from version 1.2.0 to 2.0.0, they will know that their code very likely will have to change to accommodate the upgrade.

<minor> is updated when a new feature is released that is backwards compatible. A user upgrade a minor version should not have to touch their existing code for things to continue working as per normal.

<patch> is updated for bug fixes. Bug fixes should always be backwards compatible. If they aren’t able to be, then you will be required to update the major version number instead.

We’ll take a look at how we set this in the next section, but it’s also important to point out that there will essentially be 3 version numbers to set. I found it’s easier to just set them all to exactly the same value unless there is a really specific reason to not do so. This means that for things like the “Assembly Version” where it uses the Microsoft 4 point system, the last point is always just zero.

Package Information

In Visual Studio if you right click on a project and select properties, then select “Package” on the left hand menu. You will be given a list of properties that your package will take on. These include versions, the company name, authors and descriptions.

You can set them here, but they actually then get written to the csproj. I personally found it easier to edit the project file directly. It ends up looking a bit like this :

If you edit the csproj directly, then head back to Visual Studio properties pane to take a look, you’ll see that they have now been updated.

The most important thing here is going to be all the different versions seen here. Again, it’s best if these all match with “Version” being a SemVer with 3 points of versioning.

For a full list of what can be set here, check the official MS Documentation for csproj here.

Shared Package Information/Version Bumping

If we use the example solution above in the section for “Limit Dependencies” where we have multiple projects that we want to publish nuget packages for. Then we will likely want to be able to share various metadata like Company, Copyright etc among all projects from a single source file rather than having to update each one by one. This might extend to version bumping too, where for simplicity sake when we release a new version of any package in our solution, we want to bump the version of everything.

My initial thought was to use a linked “AssemblyInfo.cs” file. It’s where you see things like this :

Look familar? The only issue was that there seemed to be quite a few properties that couldn’t be set using this, for example the “Author” metadata. And secondly when publishing a .NET Standard nuget package, it seemed to completely ignore all “version” attributes in the AssemblyInfo.cs. Meaning that every package was labelled as version 1.0.0

By chance I had heard about a feature of “importing” shared csproj fields from an external file. And as it turned out, there was a way to place a file in the “root” directory of your solution, and have all csproj files automatically read from this.

The first step is to create a file called “Directory.Build.props” in the root of your solution. Note that the name actually is “Directory”, do not replace this for the actual directory name (For some stupid reason I thought this was the case).

Inside this file, add in the following :

And by magic, all projects underneath this directory will overwrite their metadata with the data from this file. Using this, we can bump versions or change the copyright notice of all child projects without having to go one by one. And ontop of that, it still allows us to put a description in each individual csproj too!

Summary

The hardest part about all of this was probably the shared assembly info and package information. It took me quite a bit of trial and error with the AssemblyInfo.cs file to work out it wasn’t going to happen, and surprisingly there was very little documentation about using a .props file to solve the issue.

The final article in the series will look into how we package and publish to our nuget feed. Check it out here!

I’ve been having a bit of fun setting up a Nuget Server as of late, and learning the nuances of versioning a .NET Standard library. With that in mind, I thought I would document my approach to how I got things going and all the pitfalls and dead ends I ended up running into. This series will read a bit less like a stock standard tutorial and more about a brain dump of what I’ve learnt over the past few days. I should also note that in some cases, we aren’t able to go all out .NET Core mode. For example the official Nuget Server web application is full framework only – not a whole lot we can do about that.

The series will be broken into three parts. The server setup and the different options you have for actually hosting your nuget feed, different ways you can go about structuring your project and code for ease of use when packaging into a nuget feed, and how to go about actually building your package and pushing it to your server.

Part 1 : Intro & Server Setup
Part 2 : Developing Nuget Packages
Part 3 : Building & Pushing Packages To Your Nuget Feed

Why?

The first question you may ask is why? Why have a private nuget server? It may seem like a bit overkill but there are two scenarios where a private nuget feed will come in handy.

  1. If you or your company work on multiple projects and end up copying and pasting the same boilerplate code into every project. That’s a good reason to setup a nuget server. The actual impetuous for me to go ahead and set one up was having to copy in our custom “logging” code for the *nth* time into a project. This is pretty common in services companies where projects last 3-6 months before moving onto the next client.
  2. The second reason is similar, but it’s more around your architecture. If you have an architecture focused on microservices either by way of API’s or ESBs, then it’s likely that you are working on lots of smaller standalone projects. These projects will likely share similar code bases for logging, data access etc. Being able to plug in a custom nuget feed and grab the latest version of this shared code is a huge time saver and avoids costly mistakes.

Hosted Services

There are a number of services that will host your nuget feed for you. These usually have the bonus of added security, a nice GUI to manage things, and the added benefit of a bit of support when things go wrong. Obviously the downsides are that they aren’t free, and it also means that your packages are off-premises which could be a deal breaker for some folks.

An important thing to note is that almost all hosted solutions I looked at offered other package manager types included in your subscription. So for example hosted NPM feeds if you also want to publish NPM packages. This is something else to keep in mind if you are looking to go down this route.

I looked into two different services.

MyGet

MyGet seems to be the consensus best hosted solution out there if you are looking for something outside the Microsoft eco-system. Pricing seemed extremely cheap with only limited contributors but unlimited “readers” – let me know if I got that wrong because I re-read the FAQ over and over trying to understand it. They do offer things like ADFS integration for enterprise customers, but that’s when things start to get a tad expensive.

I had a quick play around with MyGet but nothing too indepth and honestly it seemed pretty solid. There wasn’t any major feature that I was wow’d by, but then again I was only publishing a few packages there trying things out, nothing too massive.

Something that was interesting to me was that MyGet will actually build your nuget packages for you, all you need to do is give it access to your source control.

This seems like a pretty helpful service at first, but then again, they aren’t going to be running your pipeline with unit tests and the like, so maybe not too useful. But it’s pretty nifty none the less.

Visual Studio Team Services

Microsoft VSTS also offer a hosted package manager solution (Get started here). I think as with most things in the VSTS/TFS world, it only makes sense if you are already in that eco-system or looking to dive in.

The pricing for VSTS works in two ways. It’s free for the first 5 users and every user from there costs approx $4 each. Users count as readers too so you can’t even consume a nuget package without a license (Which is pretty annoying). OR If a user has an “Enterprise” license (Basically an MSDN Subscription which most companies in the Microsoft eco-system already have), then they can use the VSTS package manager for free. As I say, this really only makes sense if you are already using VSTS already.

Now obviously when you use VSTS Package Manager, it’s also integrated into builds so it’s super easy to push new packages to the feed with a handy little drop down showing feeds already in VSTS Package Manager. I mean it’s not rocket science but it was kinda nice none the less.

The GUI for managing packages is also really slick with the ability to search, promote and unlist packages all from within VSTS.

Official Nuget Server

The alternative to using a hosted solution is to have an on-premises private nuget feed (Or possibly on a VM). There are actually a few different open source versions out there, but for now I’ll focus on the official nuget server package from Microsoft. You can check out instructions to get it up and running here.

Now this was actually my preferred option at first. To keep control of the packages and have complete control of the hosting seemed like the best option. But that quickly changes for a few reasons…

Firstly, there is zero privacy/authorization on consuming packages from the nuget server. This means you either have to run with an IP whitelist (Which IMO is a huge pain in the ass), host locally, or just pray that no one finds the URL/IP of your server. This seemed like a pretty big deal breaker.

There is an API Key authorization that you can set in the web.config, but this only restricts publishing packages, not consuming them. This in itself seemed like an annoyance because it meant that the keys to the kingdom was an API Key and with that you could essentially do what you liked with it. Because there are no “promoting” of packages in the feed (Everything published is automatically the latest version in the feed), this seemed like it could lead to trouble.

The packages themselves are actually stored on the server disk with no ability to offload them to something like Blob/S3. This seemed alright at first (Disk space is pretty cheap), but it also means you can’t use a hosted solution like Azure Websites because when deploying to these, it blows away the entire previous running instance – with your packages getting the treatment at the same time. This means you had to use actual hardware like a VM or host it locally on a machine.

So the obvious thought was, let’s just host it locally in the office in a closet. This gives us complete control and means no one from the outside can access it. But, what if we do want someone from the outside world to access it? Like if someone is working from home? Well then we could setup a VPN and th…. you know what. Forget it. Let’s use VSTS.

Not to mention there is no GUI to speak of :

There is a package called “Nuget Gallery” that seems to add a facelift to everything, but by this point it was a lost cause.

Summary

In the end I went with VSTS. Mostly because the company I am working with already has VSTS built into their eco-system for both builds and source control, it just made sense. If they didn’t, I would have certainly gone with MyGet over trying to host my own. Hosted solutions just seemed be much more feature rich and often for pennies.

Next up we will be talking about how I structured the code when building my libraries, and some tricks I learnt about .NET Standard versioning (Seriously – so much harder than I thought). Check it out here!

Swagger is an auto-magically generated API documenting tool. It takes any standard Web API project and can generate amazing looking (And functioning) docs without a user having to write a single additional line of documentation. Best of all, it can be as simple as a 2 line setup, or as complex as adding additional info to every single API endpoint to explode the level of info inside Swagger.

Getting Started

For the purpose of this guide, I’m just going to be using the standard ASP.net Core Web API template when you create a new project from Visual Studio. But any existing API will work just fine too!

First off, install the following Nuget package from your package manager console.

Next in the ConfigureServices method of your startup.cs, add the following code to add the Swagger services to your application.

A couple of things to note here, firstly that inside the SwaggerGen lambda you can actually specify a few more details. As an example :

Here we have said for any enum instead of using the integer value, use the string. And for all parameters can we please use CamelCase. The defaults usually suit most, but if there are specific things you are looking for your docs, you can probably find the setting here.

Secondly is obviously the Info object. Here you can specify things like the documentation author, title, and license among other things.

Head down to the Configure method of your Startup.cs.Add a call to “UseSwagger” and a call to “UseSwaggerUI” Both of these should come before the call to UseMVC.

And that’s it! Navigate your browser to https://localhost:{yourport}/swagger  to view your new API documentation.

If you don’t see anything, or it looks a bit odd, jump to the end of this article for a quick trouble shooting session!

XML Comments

The documentation that is auto generated is usually pretty damn good and if you are building a restful API, is usually enough to explain the functions of your API on their own. But there are times when the API needs a bit more explaining. For that, you can use XML Comments on your API action. For example :

If you are using Visual Studio, you can type three forward slashes in a row and it will auto generate a skeleton set of comments for you. Most importantly is the summary and parameter descriptions that are free text. They are invaluable for being able to explain what an endpoint does and what input it expects.

Next you need to force your application to actually generate the XML data that Swagger can then read. Right click on your project in Visual Studio and select Properties. On the panel that opens up, select “Build” on the left hand side. You should see an option for “Output”, and a checkbox for “Xml documentation file”. Tick this box and the setting will be auto filled out for you.

Note that this setting is per build configuration. If you intend to use Swagger remotely (And therefore likely be built in Release mode before deploying), then you should change the Configuration setting up top on this panel to “Release” and then retick the documentation tickbox.

If you are not using Visual Studio, or you are just interested in how things work behind the scenes. Doing all of this just adds the following line to your csproj file.

Next you need to head back to the ConfigureServices method of your startup.cs and add a call to IncludeXmlComments in your Swagger configuration.

Where SwaggerExample.xml is the xml file you set in your csproj/project configuration.

When you view Swagger again you should now see your XML comments displayed inside the documentation.

Up the top right is our description of our endpoint. And in the id row for our parameters, we also have a description value.

Describing API Response Codes

There may be times where your API returns a non “200” response code that you want to provide documentation for. For example an error of 400 if a particular parameter doesn’t fit certain requirements.

The first step is to decorate your actions with a “Produces” attribute that describes all the possible return codes your endpoint will give out. At the same time you can describe that for a given code, what model you will be returning at the same time. So for example if when you return an error 400, you return a particular class that describes the error, you can define that here.

A quick note that you don’t need to specify the return of 200, that is implied, but it’s nice to add anyway. When you view this endpoint in swagger, the non 200 return codes are displayed at the bottom of the endpoint description.

While this lets you know that certain responses are expected, it doesn’t actually give you the reason why they would be returned. For that, we turn again to XML comments.

Now when we view this endpoint in Swagger again we have the descriptions next to the response codes.

Troubleshooting

I can’t see anything

Check that the nuget package  Microsoft.AspNetCore.StaticFiles is installed in the project. This is required by Swagger to run. If you are unsure, just try installing the package again, this has seriously fixed the issue for me before.

I’m using MVC Core

If you are use the “MVCCore” service rather than just plain MVC. Then you need to explicitly add the API Explorer services. Confused? Head to your ConfigureServices method in your startup.cs. If you see this :

Then you are fine. However if you see this :

Then you need to manually add the ApiExplorer service.

I’m not using “Attribute Routing”

Then Swagger won’t work for you. You must be using attribute routing to use Swagger.

This will be the third and last part of our series that will help you to get up and running to do F# development with .NET Core on Linux.

We’ve made this far and all we’re missing are just the finishing touches.

As promised we’ll be looking at how we can link our build, run and debug workflow into vscode.

The editor expects the project’s configuration to be located on a folder called .vscode  at the project’s root folder, containing to 2 files called launch.json  and tasks.json . We’ll be looking at how we can create and update them both manually and automatically.

Build

Let’s start with an easy one, the build task.

Anywhere in the editor just run the default build command ( ctrl+shift+b ) and vscode will let you know that it couldn’t find a build task for the project and it’ll offer you to create one.

We’re going to select ‘Configure Build Task’ and choose ‘.NET Core’

That’s going to create a tasks.json file inside your .vscode folder (which it’ll get created automatically if it didn’t existed). If the .NET Core option doesn’t show up for you, don’t worry, manually create the tasks.json file and paste the following.

Now we’re ready to build our project! Run the build command again ( ctrl+shift+b ) and this time you’ll see the following output.

Run

Now that we’ve set up our build task, adding one for running our project is trivial. Jump again into the tasks.json file and just add another task to the “tasks” array that looks like the following.

Save the file and fire up vscode ‘Quick Open’ ( ctrl+shift+p ), select ‘Tasks: Run Task’ and you’ll see your newly created ‘run’ task. Once you’ve selected it, vscode ‘output’ panel should show something like

Debug

This will be the last thing we add and it is as easy as the other two with a small caveat.

Remember how I mentioned there were going to be two configuration files ? We’ll make use of the other one now. It order to debug, we will not be creating a task but a launch configuration. Automatically creating the configuration file is as simple as pressing F5  and selecting  .NET Core  as our environment. By default this will create the launch.json file with three default configurations, of which we’ll be only focusing on one for this article.

Right now, you might be tempted to re run debug (F5) because you created the configuration but you’ll quickly be prompted with an error message that reads something like

launch: launch.json must be configured. Change ‘program’ to the path to the executable file that you would like to debug

Don’t worry, we’ll sort it out in seconds.

Once you open up your launch.json, you’ll realize that while vscode created the configuration it hasn’t really specified which program it should debug and instead the path for the program contains two placeholders but because we’ve already built our project we can see what values it is expecting, so go ahead and replace <target-framework>  with netcoreapp1.1  and <project-name.dll>  with fsharp_tutorial.dll .

Your “.NET Core Launch (console)” should now look like this

All that is missing now is giving it a try, so just place a break point and hit debug (F5)

And we’re done! We’ve covered the basic setup to get your F# on linux journey started.

You can find the finished project here