I recently came across a peculiar issue when using the Regex type “MatchCollection” in .NET Core. Or to be more specific, in a .NET Standard library. And while the fix was simple, it actually was an interesting insight into .NET Core vs .NET Framework, and how the mini-fragmentation we have going on between the two frameworks is hard to document.


First let’s rewind. I started off writing code that was pretty similar to the following :

Regex.Matches(stringText, @"myRegex").Select(x => x.value);

When I wrote this code, I had written it inside a .NET Core project. Pretty simple and for the most part, the Regex part looks exactly the same as it did in .NET Framework. However I then had a need to move this code into a library to be shared across two different projects. Naturally I made the library .NET Standard and suddenly I got the following error.

‘MatchCollection’ does not contain a definition for ‘Select’ and no accessible extension method ‘Select’ accepting a first argument of type ‘MatchCollection’ could be found

Interesting. Same code, different platform (.NET Core vs .NET Standard), and suddenly our innocuous “framework” looking code doesn’t work. What gives?

Well, Here’s the definition of MatchCollection in .NET Core

public class MatchCollection : IList<Match>, IReadOnlyList<Match>, IList

And here’s the definition in .NET Framework.

public class MatchCollection : ICollection

So the .NET Core implementation actually implements more interfaces than that of .NET Framework. Infact because it implements IList<T>, it actually implements IEnumerable<T>. “Select”, is a LINQ method that works with IEnumerable<T>, but not ICollection. So using this in .NET Framework will not work.

But I’m using .NET Standard you say! That’s true but remember, .NET Standard enforces a “minimum” implementation – much like an interface would enforce a minimum requirement on a class. But it doesn’t mean that class can’t go over and beyond. As it so happens, the .NET Standard definition of MatchCollection only requires the implementation of ICollection, but it does not require IEnumerable<T> to be implemented. So you cannot use LINQ methods on a Regex MatchCollection if you are targeting anything other then .NET Core.

I kind of lived with this since it wasn’t such a big deal. But given I couldn’t use IEnumerable<T> methods on my MatchCollection anymore, I headed to the Microsoft Documentation for a couple of examples of how my could should work.

And here’s the actual issue.

The documentation *does not* show the differences between .NET Core and .NET Framework. The .NET Core 3.1 documentation for MatchCollection is found here : https://docs.microsoft.com/en-us/dotnet/api/system.text.regularexpressions.matchcollection?view=netcore-3.1

Note that it’s definition as per that documentation is :

public class MatchCollection : ICollection

That is wrong!

As it turns out, in 2018, this issue was raised here : https://github.com/dotnet/docs/issues/5608 which if you follow the trail of tickets, leads you to this ticket : https://github.com/MicrosoftDocs/feedback/issues/226. And right there slapped on the bottom.

Welp. Spamming Autocomplete options instead of reading documentation it is!

ENJOY THIS POST?
Join over 3.000 subscribers who are receiving our weekly post digest, a roundup of this weeks blog posts.
We hate spam. Your email address will not be sold or shared with anyone else.

In C#, there is a grand total of 6 ways to concatenate a string. Those are :

  • Using the + (plus) sign (Including +=)
  • String.Concat
  • String.Join
  • StringBuilder
  • String.Format
  • Using String Interpolation (e.x. $”My string {variable}”).

I recently got asked about performance considerations when joining two strings together. I think everyone knows by now that using the + to join up large strings is (supposedly) a no no. But it got me thinking what actually are the performance implications? If you have two strings you want to concatenate, is it actually worth spinning up an instance of StringBuilder?

I wanted to do some quick benchmarking but by the end of the post, I ended up digging into the source code to atleast begin answering “why” things perform differently.

“Your Methodology Is Wrong!”

I don’t think I’ve ever written a benchmarking post without someone jumping on Twitter, Reddit, or some social media and pointing out how wrong I am. The thing is with benchmarking, and especially C#, there is so much “compiler magic” that happens. Things get optimized out or the compiler knows you are dumb and tries to help you out in a way you never expect.

If I’ve made a misstep somewhere, please drop a comment (Hell, plug your soundcloud while you’re at it). I always come back and add in comments where people think I’ve gone wrong and redo tests where needed. Sharing is caring after all!

My Setup

So as always, your mileage may vary when running these benchmarks yourself (but please do!). I am using an AMD Ryzen CPU with the .NET Core SDK as my runtime. Full details here :

BenchmarkDotNet=v0.12.0, OS=Windows 10.0.18362
AMD Ryzen 7 2700X, 1 CPU, 16 logical and 8 physical cores
.NET Core SDK=3.1.100
  [Host]     : .NET Core 3.1.1 (CoreCLR 4.700.19.60701, CoreFX 4.700.19.60801), X64 RyuJIT
  DefaultJob : .NET Core 3.1.1 (CoreCLR 4.700.19.60701, CoreFX 4.700.19.60801), X64 RyuJIT

Initial Benchmarking

For my benchmark, I’m going to try and do “single line joins”. What I mean by “single line joins” is that I have say 5 variables that I want to all join up in a long string, with a single space between them. I’m not doing this inside a loop and I have all 5 variables on hand. For this, I’m using BenchmarkDotNet.  My benchmark looks like so :

public class SingleLineJoin
{
    public string string1 = "a";
    public string string2 = "b";
    public string string3 = "c";
    public string string4 = "d";
    public string string5 = "e";

    [Benchmark]
    public string Interpolation()
    {
        return $"{string1} {string2} {string3} {string4} {string5}";
    }

    [Benchmark]
    public string PlusOperator()
    {
        return string1 + " " + string2 + " " + string3 + " " + string4 + " " + string5;
    }

    [Benchmark]
    public string StringConcatenate()
    {
        return string.Concat(string1, " ", string2, " ", string3, " ", string4, " ", string5);
    }

    [Benchmark]
    public string StringJoin()
    {
        return string.Join(" ", string1, string2, string3, string4, string5);
    }

    [Benchmark]
    public string StringFormat()
    {
        return string.Format("{0} {1} {2} {3} {4}", string1, string2, string3, string4, string5);
    }

    [Benchmark]
    public string StringBuilderAppend()
    {
        StringBuilder builder = new StringBuilder();
        builder.Append(string1);
        builder.Append(" ");
        builder.Append(string2);
        builder.Append(" ");
        builder.Append(string3);
        builder.Append(" ");
        builder.Append(string4);
        builder.Append(" ");
        builder.Append(string5);
        return builder.ToString();
    }
}

I’d also note that StringBuilder also has methods to do things like builder.AppendJoin which is like a hybrid between appending a line to the StringBuilder object but using a string.Join to actually create the line. I’ve skipped these because if you were simply going to use the AppendJoin method, you would instead just use string.Join anyway.

And the results are here :

MethodMeanErrorStdDev
Interpolation98.58 ns1.310 ns1.225 ns
PlusOperator98.35 ns0.729 ns0.646 ns
StringConcatenate94.65 ns0.929 ns0.869 ns
StringJoin78.52 ns0.846 ns0.750 ns
StringFormat233.67 ns3.262 ns2.892 ns
StringBuilderAppend51.13 ns0.237 ns0.210 ns

Here’s the interesting thing for me. From what I can see, Interpolation, PlusOperator and Concat are roughly the same. String.Join is fast(er) with StringBuilder being the clear leader. String.Format is slowest by a mile. What’s going on here? We are going to have to do digging as to what goes on under the hood.

Digging Deeper

String.Format

Why is String.Format so slow? Well as it turns out, String.Format also uses StringBuilder behind the scenes, but it falls down to a method called “AppendFormatHelper” https://github.com/microsoft/referencesource/blob/master/mscorlib/system/text/stringbuilder.cs#L1322. Now this somewhat makes sense because you have to remember, string.Format can do things like :

String.Format("Price : {0:C2}", 14.00M);//Prints $14.00 (Formats as currency). 

So it has to do far more work in trying to format the string taking into account things like formatting a currency correctly etc. Even checking for these format types takes that little bit of extra time.

String.Join

String.Join is an interesting one because the code behind the scenes in my mind doesn’t make too much sense. If you pass in an IEnumerable or a params list of objects, then it simply uses a StringBuilder and doesn’t do much else : https://github.com/microsoft/referencesource/blob/master/mscorlib/system/string.cs#L161

But if you pass in params of string, it uses a char array and does some pretty low level stuff : https://github.com/microsoft/referencesource/blob/master/mscorlib/system/string.cs#L204

So immediately I think… Is there a difference? Well with this benchmark :

public class StringJoinComparison
{
    public string string1 = "a";
    public string string2 = "b";
    public string string3 = "c";
    public string string4 = "d";
    public string string5 = "e";

    public List<string> stringList;

    [GlobalSetup]
    public void Setup()
    {
        stringList = new List<string> { string1, string2, string3, string4, string5 };
    }


    [Benchmark]
    public string StringJoin()
    {
        return string.Join(" ", string1, string2, string3, string4, string5);
    }


    [Benchmark]
    public string StringJoinList()
    {
        return string.Join(" ", stringList);
    }
}

And the results :

MethodMeanErrorStdDev
StringJoin80.32 ns0.730 ns0.683 ns
StringJoinList141.16 ns1.109 ns1.038 ns

Big difference. Infact it’s much much slower. Every now and again when I write benchmarks here, the original creator shows up and explains either A. Why I’m doing it wrong. Or B. Why it has to be this way, even with a performance hit. I would love to know what’s going on here because this one has almost a 2x difference depending on the input. Obviously there is different code behind the scenes, but it’s like a minefield here. I don’t think anyone would have suspected this.

String.Concat

Concat is very similar to Join. For example if we pass in an IEnumerable, it uses a StringBuilder : https://github.com/microsoft/referencesource/blob/master/mscorlib/system/string.cs#L3145

But if we pass in a params list of string, it instead falls down to the method ConcatArray : https://github.com/microsoft/referencesource/blob/master/mscorlib/system/string.cs#L3292

You may start noticing that a lot of methods have a call to “FastAllocateString”. Inferring from the usage and not from special knowledge that I have, it would appear that this allocates memory for the full size of the string, that is then “filled” up later on. For example given a list of strings, you already know ahead of time how large that string will be, so you can pre-allocate that memory and then simply fill in the bytes later.

Plus Operator

This one confused me a bit. I’m pretty sure from the moment I started programming in C#, I got told not to concat strings using the plus operator. But here it wasn’t so bad… Unfortunately I tried to find the source code like I’ve done above but to no avail. So I had to go on instinct to try and diagnose the issue.. Immediately I think I found it.

My hunch was that doing the operator in one big line was optimized out. So I wrote a small benchmark to test this theory :

[MemoryDiagnoser]
public class OperatorTest
{
    public string string1 = "a";
    public string string2 = "b";
    public string string3 = "c";
    public string string4 = "d";
    public string string5 = "e";


    [Benchmark]
    public string PlusOperatorWithResult()
    {
        var result = string1 + " ";
        result += string2 + " ";
        result += string3 + " ";
        result += string4 + " ";
        result += string5 + " ";
        return result;
    }


    [Benchmark]
    public string PlusOperator()
    {
        var result = string1 + " " + string2 + " " + string3 + " " + string4 + " " + string5;
        return result;
    }
}

If I’m being honest, I think there could still be some optimizer shenanigans going on here. But the idea is that with each string concat being on it’s own line, in theory it should have to create a new string each time. And the results :

MethodMeanErrorStdDevGen 0Gen 1Gen 2Allocated
PlusOperatorWithResult106.52 ns0.560 ns0.497 ns0.0459192 B
PlusOperator95.10 ns1.818 ns1.701 ns0.0324136 B

So, a little bit of a slow down which is expected, but maybe not as much as I was expecting. Obviously over time, with larger strings and more joins, this could become more problematic which I think is what people try and point out when they scream “use StringBuilder for everything!”.

Also notice that I added the MemoryDiagnoser to this benchmark to show that yes, more memory is allocated when you are mucking using the += operator as it has to create a brand new string in memory to handle this.

StringBuilder

StringBuilder’s source code can be found here : https://github.com/microsoft/referencesource/blob/master/mscorlib/system/text/stringbuilder.cs. It’s relatively simply in that it holds a char array until the final moment and then joins everything up right at the end. The reason it’s so fast is because you are not allocating strings until you really need it.

What surprised me most about the use of StringBuilder is that even at 5 appends (Or I guess more if we count the spaces), it’s much much faster than just using the + operator. I thought there would be some sort of breakpoint in the tens, maybe hundreds of concats that the overhead of a StringBuilder becomes more viable. But it seems “worth it”, even if you are only doing a few concats (but more on that below).

Interpolation

I actually can’t find the source code for what does Interpolation in C#. Infact I wasn’t even sure what to search. Because it’s similar to the plus operator, I assume that it’s maybe just sugar around the same piece of code that joins strings deep in the code.

Summary

So where does that leave us? Well we came in with the knowledge that StringBuilder was best practice for building strings, and we left with that still intact. We also found that even when building smaller strings, StringBuilder out performs the rest. Does that mean immediately rewrite your code to use StringBuilder everywhere? I personally doubt it. Based on readability alone, a few nano seconds might not be worth it for you.

We also walk away with the knowledge that string.Format performs extremely poorly even when we aren’t doing any special formatting. Infact we could use literally any other method to join strings together and have it be faster.

And finally, we also found that string concatenation is still a strange beast. With things like string.Concat and string.Join doing every different things depending on what you pass in. 9 times out of 10 you probably don’t even think there is a difference between passing in a IEnumerable vs Params, but there is.

ENJOY THIS POST?
Join over 3.000 subscribers who are receiving our weekly post digest, a roundup of this weeks blog posts.
We hate spam. Your email address will not be sold or shared with anyone else.

A graduate developer asked a simple question the other day.

Grad : “What type should I return from this method?”
Me : “Make it a list”

Seemed simple enough. I took a look at his code and was confounded on just what had gone wrong. Instead of using List<T>, they had used the type “ArrayList”. I honestly can’t even remember the last time I used ArrayList. I think maybe right when I started programming in .NET 2, I couldn’t understand generics quick enough and the ArrayList seemed like a drop in replacement. It’s not!

What’s The Difference?

The key difference between the two is that an ArrayList holds only types of “objects”. That means theoretically it’s a box of anything you want it to be. For example this code compiles just fine :

ArrayList arrayList = new ArrayList();
arrayList.Add(123);
arrayList.Add("abc");
arrayList.Add(new object());

It’s then on the code grabbing things out of the array list to “check” that it’s the correct type. In practice it’s not going to be so haphazard that you are throwing all sorts of types in an array list so really it’s more of a compile time “looseness”. If we compare it to a List :

List<int> list = new List<int>();
list.Add(123);
list.Add("abc"); //Compile time error

No bueno. It knows that we only want to be storing integers and trying to jam anything else in there isn’t going to fly.

But what about this?

List<object> list = new List<object>();
list.Add(123);
list.Add("abc");

That works right? A list of objects is almost the same thing as an ArrayList. Almost.

If we look at the interfaces implemented by ArrayList :

public class ArrayList : ICollection, IEnumerable, IList, ICloneable

List is basically the same with a few generic interfaces thrown in. However when you check these, they don’t add anything except generic methods of things like “Add” etc that use the type :

public class List<T> : ICollection<T>, IEnumerable<T>, IEnumerable, IList<T>, IReadOnlyCollection<T>, IReadOnlyList<T>, ICollection, IList

But where things change is using LINQ. Almost all methods (I say almost but I think it’s all) are built upon IEnumerable<T> and not IEnumerable. For example the Where clause in LINQ looks like :

public static IEnumerable<TSource> Where<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate)

That means you cannot use LINQ on an ArrayList. In some use cases it’s no biggie, but you do get LINQ for free… So picking a type that doesn’t support it is really shooting yourself in the foot for no reason.

Performance Implications

In some cases, there are large performance implications when picking an ArrayList over a List<T>. That comes down to the act of “boxing” and “unboxing”. In simple terms, boxing is taking a value type (such as an integer) and wrapping it in an object and storing it on the heap instead of the stack. Microsoft actually have a great article on the subject here : https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/types/boxing-and-unboxing

But how does that affect the List vs ArrayList conversation? When we store an item in an ArrayList it must be of type object (Or a type of). If we are storing a value type in our ArrayList, then before it can be stored, it must first “box” the object and wrap it. A List<int> does not have the same boxing cost (Although a List<object> would).

To test this, I created a benchmark using BenchmarkDotNet

public class ArrayListVsListWrite
{
    int itemCount = 10000000;
    public ArrayList arrayList;
    public List<int> list;
    public List<object> listObject;

    [IterationSetup]
    public void Setup()
    {
        arrayList = new ArrayList();
        list = new List<int>();
        listObject = new List<object>();
    }

    [Benchmark]
    public ArrayList WriteArrayList()
    {
        for(int i=0; i < itemCount; i++)
        {
            arrayList.Add(i);
        }
        return arrayList;
    }

    [Benchmark]
    public List<object> WriteListObject()
    {
        for (int i = 0; i < itemCount; i++)
        {
            listObject.Add(i);
        }
        return listObject;
    }

    [Benchmark]
    public List<int> WriteList()
    {
        for (int i = 0; i < itemCount; i++)
        {
            list.Add(i);
        }
        return list;
    }
}

In simple terms. We are looping 10 million times and adding the item to the list. The results of which are :

MethodMeanErrorStdDev
WriteArrayList651.48 ms4.215 ms3.943 ms
WriteListObject641.95 ms5.129 ms4.798 ms
WriteList88.49 ms5.631 ms16.603 ms

Not hard to see the performance difference here. We can see that a List of type object also suffers the same boxing/unboxing problem.

To a lesser extent, reading would also be slower as you would be reading an object, and then “unboxing” that object and casting it to an integer. I was going to do a benchmark with that but… you get the idea.

When Should You Use ArrayList?

Honestly. Never.

The only time you should use an ArrayList is when you are using a library built before List<T> which I believe was introduced in .NET 2.0. If you are using a library (Or building code) that targets .NET 1.0 or 1.1, then I guess ArrayList is OK. It’s probably going to be the least of your problems.

ENJOY THIS POST?
Join over 3.000 subscribers who are receiving our weekly post digest, a roundup of this weeks blog posts.
We hate spam. Your email address will not be sold or shared with anyone else.

Are there new .NET Core API projects that don’t use Swagger? It’s one of the first things I install on a new project and even if I end up testing an API with something like Postman, the fact that I can quickly show a GUI to run any API endpoints for testers, other devs, hell even project managers is phenomenal.

Now I’ve actually written about using Swagger in .NET Core before, but with the release of .NET Core 3 came some real gotchas that caused some massive headaches. Suddenly my “let’s just spend 30 seconds adding Swagger” turned into a couple of hours trying to work out why things don’t work quite as seamless as before. I’ll write this as a quick walkthrough that points out the issues along the way. It should be enough to get you back up and running before too long!

Installing Swagger

The first thing is installing Swagger via Nuget. Now the annoying thing is that the actual package you want to install is not called Swagger at all. You actually want to install the Swashbuckle.AspNetCore package which then installs various swagger dependencies. Maybe this nuget browser screenshot will explain better than I can

The other frustrating thing (Although now fixed), is that upon release of .NET Core 3, the release version of Swashbuckle did not actually work with .NET Core 3 and you had to use a pre-release version. That’s hopefully fixed now, but just incase, ensure that you are using atleast version 5.0.0 of Swashbuckle. If you use a version before this you will get a really random error :

Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator': Failed to compare two elements in the array

Again, the fix is to ensure you are running version 5.0.0 or above of Swashbuckle.

Adding Swagger Services

The next step is to add the Swagger services to the ServiceCollection in .NET Core. In your ConfigureServices method of startup.cs, you want to add a line that looks like this :

services.AddSwaggerGen(swagger =>
{
    swagger.SwaggerDoc("v1", new OpenApiInfo { Title = "My API" });
});

Now pay attention to the fact that I’m creating an object called “OpenApiInfo”, this used to be called just “Swagger.Info”. So if you are copy and pasting from a previous project or an old tutorial you’re gonna run into something like :

The type or namespace name 'Info' does not exist in the namespace 'Swashbuckle.AspNetCore.Swagger'

This goes for almost all configuration with Swagger there has been a rename to prepend “OpenApi” to almost all configuration properties. If you are upgrading a project, 9 times out of 10, you will just have to tack on the “OpenApi” part.

It’s an annoying thing to do but for the most part you can guess your way through it and have everything working.

Adding Swagger Middleware

The final step is to add our Swagger middleware to actually serve up our nice HTML interface. There are two calls to add to our Configure method in our startup.cs. These are :

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API");
});

These should come *before* any call to UseMVC or similar that might try and serve the request before Swagger can get to it. So in practice, near the top.

The first call to UseSwagger is the one that adds the “JSON” serving capability to your app. The second call is what adds the actual HTML interface for Swagger. Nice and easy!

NewtonSoft.JSON Support

This one got me good and caused massive headaches. So by now we know that .NET Core 3+ will not use JSON.NET as the default JSON serializer. We can fix that with some easy code (post on that here!). But even once you change your API to use JSON.NET as the serializer, Swagger will still use the default System.Text.Json serializer anyway!

But of course, there is a nuget package for that! Run the following from your package manager console :

Install-Package Swashbuckle.AspNetCore.Newtonsoft

Then in your ConfigureServices method of your startup.cs, add the following :

services.AddSwaggerGenNewtonsoftSupport();

Now Swagger will also abide by JSON.NET serialization rules and will align with your API.

ENJOY THIS POST?
Join over 3.000 subscribers who are receiving our weekly post digest, a roundup of this weeks blog posts.
We hate spam. Your email address will not be sold or shared with anyone else.

I’ve recently been trying out the new System.Text.Json JSON Parser that is now built into .NET Core 3+, replacing NewtonSoft.Json (Sometimes called JSON.NET) as the default JSON parser in ASP.NET Core. There has been quite a few gotchas and differences between the two libraries, but none more interesting than the following piece of documentation :

During deserialization, Newtonsoft.Json does case-insensitive property name matching by default. The System.Text.Json default is case-sensitive, which gives better performance since it’s doing an exact match.

I found this interesting, especially the last line which suggests that doing exact matches by default results in much better performance.

Interestingly enough, there is also the following piece of info :

If you’re using System.Text.Json indirectly by using ASP.NET Core, you don’t need to do anything to get behavior like Newtonsoft.Json. ASP.NET Core specifies the settings for camel-casing property names and case-insensitive matching when it uses System.Text.Json.

So that essentially means when we switch to System.Text.Json in an ASP.NET Core project specifically, things will be case insensitive by default, and by extension, have slightly worse performance than forcing things to be case sensitive. By the way, for the record, I think this should be the default behaviour because in 99% of Web SPA cases, the front end will be using javascript which typically is written using camelCase, and if the backend is in C#, the properties are typically written in PascalCase.

But here’s the thing I wondered. When everyone’s out there posting benchmarks, are they benchmarking case sensitive or case insensensitive JSON parsing? In another blog post I and many others often refer back to for JSON benchmarks (https://michaelscodingspot.com/the-battle-of-c-to-json-serializers-in-net-core-3/) they are actually doing the case sensitive parsing which again, I don’t think is going to be the reality for the majority of use cases.

Let’s dig a little more!

Benchmarking

The first thing I wanted to do was create a simple benchmark to test my hypothesis. That is, does deserializing data with case insensitivity turned on slow down the deserialization process.

I’m going to use BenchmarkDotNet for this purpose. The class I want to deserialize looks like so :

public class MyClass
{
    public int MyInteger { get; set; }

    public string MyString { get; set; }

    public List<string> MyList { get; set; }
}

Now I also had an inkling of a theory this wouldn’t be as simple as first thought. I had a hunch that possibly that even when case insensitivity was turned on, if it could find an exact match first, it would attempt to use that anyway. e.g. It’s possible that the code would look something like this pseudo code :

if(propertyName == jsonProperty)
{
    //We found the property on an exact match. 
}else if(propertyName.ToLower() == jsonProperty.ToLower())
{
   //We found it after ToLowering everything. 
}

With that in mind, I wanted my benchmark to test serializing both PascalCase names (So exact match), and camelCase names. My benchmark looked like so :

public class SystemTextVsJson
{
    private readonly JsonSerializerOptions options = new JsonSerializerOptions() { PropertyNameCaseInsensitive = true };

    private const string _jsonStringPascalCase = "{\"MyString\" : \"abc\", \"MyInteger\" : 123, \"MyList\" : [\"abc\", \"123\"]}";
    private const string _jsonStringCamelCase = "{\"myString\" : \"abc\", \"myInteger\" : 123, \"myList\" : [\"abc\", \"123\"]}";

    [Benchmark]
    public MyClass SystemTextCaseSensitive_Pascal()
    {
        return JsonSerializer.Deserialize<MyClass>(_jsonStringPascalCase);
    }

    [Benchmark]
    public MyClass SystemTextCaseInsensitive_Pascal()
    {
        return JsonSerializer.Deserialize<MyClass>(_jsonStringPascalCase, options);
    }

    [Benchmark]
    public MyClass SystemTextCaseSensitive_Camel()
    {
        return JsonSerializer.Deserialize<MyClass>(_jsonStringCamelCase);
    }

    [Benchmark]
    public MyClass SystemTextCaseInsensitive_Camel()
    {
        return JsonSerializer.Deserialize<MyClass>(_jsonStringCamelCase, options);
    }
}

And just so we are all on the same page, the machine I’m running this on looks like :

BenchmarkDotNet=v0.12.0, OS=Windows 10.0.18362
AMD Ryzen 7 2700X, 1 CPU, 16 logical and 8 physical cores
.NET Core SDK=3.1.100

Now onto our results :

MethodMeanErrorStdDev
SystemTextCaseSensitive_Pascal1.511 us0.0298 us0.0279 us
SystemTextCaseInsensitive_Pascal1.538 us0.0052 us0.0049 us
SystemTextCaseSensitive_Camel1.877 us0.0297 us0.0277 us
SystemTextCaseInsensitive_Camel2.548 us0.0164 us0.0145 us

Interesting. Very interesting. So a couple of things that stick out to me immediately.

If we are using PascalCase for our property names on both ends (in the JSON and our C# class), then the case sensitivity setting doesn’t matter all too much. This proves my initial thoughts that it may try for an exact match no matter the setting as that’s likely to be faster than any string manipulation technique.

Next. Slightly of interest is that when parsing with case sensitivity turned on, when there is no match (e.g. You have screwed up the casing on one of the ends), it runs slightly slower. Not by much. But enough to be seen in the results. This is probably because it tries to do some extra “matching” if it can’t find the exact match.

Finally. Oof. Just as we thought. When we are doing case insensitive matching and our incoming data is camelCase with the class being PascalCase, the benchmark is substantially slower than exact matching. And I just want to remind you, the default for ASP.NET Core applications is case insensitive.

So, how does this actually stack up?

Benchmarking Against Newtonsoft

The interesting thing here was if we are comparing apples to apples, Newtonsoft also does case insensitive matching but it does so by default. So when we do any benchmarking against it, we should try and do so using similar settings if those settings would be considered the norm.

With that in mind, let’s do this benchmark here :

public class SystemTextVsJson
{
    private readonly JsonSerializerOptions options = new JsonSerializerOptions() { PropertyNameCaseInsensitive = true };

    private const string _jsonStringCamelCase = "{\"myString\" : \"abc\", \"myInteger\" : 123, \"myList\" : [\"abc\", \"123\"]}";

    [Benchmark]
    public MyClass SystemTextCaseInsensitive_Camel()
    {
        return JsonSerializer.Deserialize<MyClass>(_jsonStringCamelCase, options);
    }

    [Benchmark]
    public MyClass NewtonSoftJson_Camel()
    {
        return Newtonsoft.Json.JsonConvert.DeserializeObject<MyClass>(_jsonStringCamelCase);
    }
}

And the results?

MethodMeanErrorStdDev
SystemTextCaseInsensitive_Camel2.555 us0.0106 us0.0099 us
NewtonSoftJson_Camel2.852 us0.0104 us0.0087 us

Much much much closer. So now that we are comparing things on an even footing the performance of System.Text.Json to NewtonSoft actually isn’t that much better in terms of raw speed. But what about memory? I hear that touted a lot with the new parser.

Memory Footprint

BenchmarkDotNet gives us the ability to also profile memory. For our test, I’m going to keep the same benchmarking class but just add the MemoryDiagnoser attribute onto it.

[MemoryDiagnoser]
public class SystemTextVsJson
{
}

And the results

MethodAllocated
SystemTextCaseInsensitive_Camel408 B
NewtonSoftJson_Camel3104 B

Wow, credit where credit is due, that’s a very impressive drop. Now again I’m only testing with a very minimal JSON string, but I’m just looking to do a comparison between the two anyway.

Final Thoughts

Why did I make this post in the first place? Was it to crap all over System.Text.Json and be team JSON.NET all the way? Not at all. But I have to admit, there is some level of frustration when moving to using System.Text.Json when it doesn’t have the “features” that you are used to in JSON.NET, but it’s touted as being much faster. Then when you dig a little more in the majority of use cases (case insensitive), it’s not actually that much faster.

And I have to point out as well. That literally everytime I’ve written a benchmarking post for C# code, I’ve managed to get something wrong where I didn’t know the compiler would optimize things out etc and someone jumps in the Reddit comments to call me an idiot (Will probably happen with this one too! Feel free to drop a comment below!). So you can’t really blame people doing benchmarks across JSON parsers without realizing the implications of casing because the fact ASP.NET Core has specific defaults that hide away this fact means that you are unlikely to run into the issue all that often.

If you are in the same boat as me and trying to make the leap to System.Text.Json (Just so you stay up to date with what’s going on), I have a post sitting in my drafts around gotchas with the move. Case sensitivity is a big one but also a bunch of stuff on various defaults, custom converters, null handling etc which were all so great in JSON.NET and maybe a little less great in System.Text.Json. So watch this space!

ENJOY THIS POST?
Join over 3.000 subscribers who are receiving our weekly post digest, a roundup of this weeks blog posts.
We hate spam. Your email address will not be sold or shared with anyone else.

I’ve recently been using JWT Tokens as my authentication method of choice for my API’s. And with it, I’ve had to do battle with various pieces of documentation on how JWT token authentication and authorization actually work in .NET Core.

Primarily, there is a lot of documentation on using ASP.NET Identity to handle authentication/authorization. So using the big bloated UserManager  and using the packaged attributes like [Authorize]  etc. However, I always get to a point where I just need a bit more custom flexibility, that the out of the box components don’t provide. And when it comes to how to *manually* create JWT Tokens and validate them later on, the documentation is a little slim. Infact some guides show you how to manually create the token, but then tell you to use the out of the box components to validate it which creates confusion as to what you’re actually doing. So here’s hoping this article clears some things up!

Creating JWT Tokens In ASP.NET Core

Let’s first take a look at how to create JWT tokens manually. For our example, we will simply create a service that returns a token as a string. Then however you return that token (header, response body etc) is up to you. I’ll also note in the following examples, we have things like hardcoded “secrets”. I’m doing this for demonstration purposes but quite obviously you will want these to be config driven. You should take the following as a starting point, and then modify it to be production ready.

The code to generate a JWT Token looks like so :

public string GenerateToken(int userId)
{
	var mySecret = "asdv234234^&%&^%&^hjsdfb2%%%";
	var mySecurityKey = new SymmetricSecurityKey(Encoding.ASCII.GetBytes(mySecret));

	var myIssuer = "http://mysite.com";
	var myAudience = "http://myaudience.com";

	var tokenHandler = new JwtSecurityTokenHandler();
	var tokenDescriptor = new SecurityTokenDescriptor
	{
		Subject = new ClaimsIdentity(new Claim[]
		{
			new Claim(ClaimTypes.NameIdentifier, userId.ToString()),
		}),
		Expires = DateTime.UtcNow.AddDays(7),
		Issuer = myIssuer,
		Audience = myAudience,
		SigningCredentials = new SigningCredentials(mySecurityKey, SecurityAlgorithms.HmacSha256Signature)
	};

	var token = tokenHandler.CreateToken(tokenDescriptor);
	return tokenHandler.WriteToken(token);
}

Let’s walk through this bit by bit.

I have a security key which is essentially used to “sign” the token on it’s way out. We can verify this signature when we receive the token on the other end to make sure it was created by us. Tokens themselves are actually readable even if you sign them so you should never put sensitive information in them. Signing simply verifies that it was us who created the token and whether it’s been tampered with, but it does not “encrypt” the token.

The Issuer and Audience are funny things because realistically, you probably won’t have a lot of use for them. Issuer is “who” created this token, for example your website, and Audience is “who” the token is supposed to be read by. So a good example might be that when a user logs in, your authentication api (auth.mywebsite.com) would be the issuer, but your general purposes API is the expected audience (api.mywebsite.com). These are actually free text fields so they don’t have to be anything in particular, but later on when we validate the issuer/audience, we will need to know what they are.

We are creating the token for 7 days, but you can set this to anything you want (Or have it not expire it at all), and the rest of the code is just .NET Core specific token writing code. Nothing too specific to what we are doing. Except for claims…

Explaining Claims

Claims are actually a simple concept, but too many articles go into the “abstract” thought process around them. In really simply terms, a claim is a “fact” stored in the token about the user/person that holds that token. For example, if I log into my own website as an administrator role, then my token might have a “claim” that my role is administrator. Or put into a sentence “Whoever holds this token can claim they are an admin”. That’s really what it boils down to. Just like you could store arbitrary information in a cookie, you can essentially do the same thing inside a JWT Token.

For example, because a claim “type” is simply a free text field, we can do things like :

Subject = new ClaimsIdentity(new Claim[]
{
	new Claim("UserRole", "Administrator"),
})

Notice how we don’t use the “ClaimTypes” static class like we did in the first example, we simply used a string to define the claim name, and then said what the claim value was. You can basically do this for any arbitrary piece of information you want, but again remember, anyone can decode the JWT Token so you should not be storing anything sensitive inside it.

I’ll also note that a great pattern to get into is to store the claim types as static consts/readonly. For example :

public static readonly string ClaimsRole = "UserRole";

[...]

Subject = new ClaimsIdentity(new Claim[]
{
	new Claim(ClaimsRole, "Administrator"),
})

You are probably going to need that ClaimType string in multiple places, so it’s better to set it once and reuse that static variable everywhere.

Validating A Token

So once you’ve created the token, the next step would be to validate it when a user sends you one. Now personally I like sending it inside a header like x-api-token, but because it’s simply a string, you can send it any which way you like. Because of that, let’s make our example method simply accept a token as a string and validate it.

public bool ValidateCurrentToken(string token)
{
	var mySecret = "asdv234234^&%&^%&^hjsdfb2%%%";
	var mySecurityKey = new SymmetricSecurityKey(Encoding.ASCII.GetBytes(mySecret));

	var myIssuer = "http://mysite.com";
	var myAudience = "http://myaudience.com";

	var tokenHandler = new JwtSecurityTokenHandler();
	try
	{
		tokenHandler.ValidateToken(token, new TokenValidationParameters
		{
			ValidateIssuerSigningKey = true,
			ValidateIssuer = true,
			ValidateAudience = true,
			ValidIssuer = myIssuer,
			ValidAudience = myAudience,
			IssuerSigningKey = mySecurityKey
		}, out SecurityToken validatedToken);
	}
	catch
	{
		return false;
	}
	return true;
}

You’ll notice that I’ve had to copy and paste the security keys, issuer and audience into this method. As always, this would be better in a configuration class rather than being copied and pasted, but it makes the example a little easier to read.

So what’s going on here? It’s pretty simply actually. We create a TokenHandler which is a .NET Core inbuilt class for handling JWT Tokens, we pass it our token as well as our “expected” issuer, audience and our security key and call validate. This validates that the issuer and audience are what we expect, and that the token is signed with the correct key. An exception is thrown if the token is not validated so we can simply catch this and return false.

Reading Claims

So the final piece of the puzzle is reading claims. This is actually fairly easy assuming we have already validated the token itself.

public string GetClaim(string token, string claimType)
{
	var tokenHandler = new JwtSecurityTokenHandler();
	var securityToken = tokenHandler.ReadToken(token) as JwtSecurityToken;

	var stringClaimValue = securityToken.Claims.First(claim => claim.Type == claimType).Value;
	return stringClaimValue;
}

Read the token, go to the claims list, and find the claim with the matching type (remembering the claimType is simply a freetext string), and return the value.

What About AddAuthentication/AddJwtBearer?

So you might have read documentation that uses the following code :

services.AddAuthentication(x =>
{
	x.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
	x.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(x =>
{
	x.TokenValidationParameters = new TokenValidationParameters();
});

Or some variation with it that sets up the token validation parameters with signing keys, audiences and issuers. This only works if you are using the default Authorize  attribute. These settings are a way for you to configure the inbuilt ASP.NET Core authorization handlers. It does not set any global settings for JWT Tokens if you are creating/validating them yourself.

Why do I point this out? I’ve seen people manually validating tokens and *not* validating the signing key. When I ask why they are not validating that the token is signed correctly, they have assumed that if they call AddJwtBearer  with various settings that these also pass down anytime you call new JwtSecurityTokenHandler() . They do not!

ENJOY THIS POST?
Join over 3.000 subscribers who are receiving our weekly post digest, a roundup of this weeks blog posts.
We hate spam. Your email address will not be sold or shared with anyone else.

I recently had to write interview questions specifically for features that made it into C# 7. You can have a quick refresher on what made it in here : https://docs.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-7. A scan down the list reveals some interesting stuff (out variables, pattern matching, throw expressions, discards), and also some stuff that I honestly don’t seem to ever use (local functions – I honestly don’t see the use of these…). But something that sits right in the middle is Tuples. It’s a language feature that seems pretty powerful… But I rarely use dynamic or anonymous objects, preferring strongly typed classes in 99.999% of cases. For “business” development, things like this rarely override the need for the code that is extremely maintainable.  And yet, Tuples drew me in….

So here we have it. A quick crash course in Tuples (aka, What I learned about Tuples in the past week).

Tuples Before C# 7

Tuples were actually in .NET Framework before C# 7. But they were complete crap and were more of a framework construct rather than being embedded in the language.

For example, you could do something like so :

Tuple<string, int> GetData()
{
    return new Tuple<string, int>("abc", 123);
    //Alternatively. 
    return Tuple.Create("abc", 123);
}

void DoWork()
{
    Console.WriteLine(GetData().Item1);
}

But the fact you had Item1 and Item2 honestly wasn’t very appealing in most use cases. The fact you had to have the Tuple object be the return type as well made it feel like it was hardly more appealing than just returning a list, dictionary, or some other data structure that is simply a “list” of items.

Ontop of that, there was this weird (Atleast I thought so initially) limit of 8 items within the tuple. For example if I passed in 9 parameters into my Tuple.Create statement :

var myBigTuple = Tuple.Create("abc", 123, 123, 123, 123, 123, 123, 123, 123);

Things blow up. Why? Well when we decompile the .NET code :

public static Tuple<T1> Create<[NullableAttribute(2)] T1>(T1 item1);
public static Tuple<T1, T2> Create<[NullableAttribute(2)] T1, [NullableAttribute(2)] T2>(T1 item1, T2 item2);
public static Tuple<T1, T2, T3> Create<[NullableAttribute(2)] T1, [NullableAttribute(2)] T2, [NullableAttribute(2)] T3>(T1 item1, T2 item2, T3 item3);
public static Tuple<T1, T2, T3, T4> Create<[NullableAttribute(2)] T1, [NullableAttribute(2)] T2, [NullableAttribute(2)] T3, [NullableAttribute(2)] T4>(T1 item1, T2 item2, T3 item3, T4 item4);
public static Tuple<T1, T2, T3, T4, T5> Create<[NullableAttribute(2)] T1, [NullableAttribute(2)] T2, [NullableAttribute(2)] T3, [NullableAttribute(2)] T4, [NullableAttribute(2)] T5>(T1 item1, T2 item2, T3 item3, T4 item4, T5 item5);
public static Tuple<T1, T2, T3, T4, T5, T6> Create<[NullableAttribute(2)] T1, [NullableAttribute(2)] T2, [NullableAttribute(2)] T3, [NullableAttribute(2)] T4, [NullableAttribute(2)] T5, [NullableAttribute(2)] T6>(T1 item1, T2 item2, T3 item3, T4 item4, T5 item5, T6 item6);
public static Tuple<T1, T2, T3, T4, T5, T6, T7> Create<[NullableAttribute(2)] T1, [NullableAttribute(2)] T2, [NullableAttribute(2)] T3, [NullableAttribute(2)] T4, [NullableAttribute(2)] T5, [NullableAttribute(2)] T6, [NullableAttribute(2)] T7>(T1 item1, T2 item2, T3 item3, T4 item4, T5 item5, T6 item6, T7 item7);
public static Tuple<T1, T2, T3, T4, T5, T6, T7, Tuple<T8>> Create<[NullableAttribute(2)] T1, [NullableAttribute(2)] T2, [NullableAttribute(2)] T3, [NullableAttribute(2)] T4, [NullableAttribute(2)] T5, [NullableAttribute(2)] T6, [NullableAttribute(2)] T7, [NullableAttribute(2)] T8>(T1 item1, T2 item2, T3 item3, T4 item4, T5 item5, T6 item6, T7 item7, T8 item8);

So basically each create statement has been manually added up to 8. And on that 8th statement you can actually add a Tuple as the final param to have a nested Tuple. Pretty nasty stuff.

Leave a comment if you used Tuples in this initial framework version and what the use case was, because I am genuinely curious who used them like this.

ValueTuples vs Tuple Class

So you might have heard the name “ValueTuple” thrown about, but what is that exactly?

In .NET 4.0 (e.g. The old Tuple), we had a Tuple Class. It basically acts like any other C# class. However in C# 7, The ValueTuple struct type was added. The main difference being that the Tuple class, being a class, is a reference type while Value Tuple (Which we will talk about below) is a value type (struct).

Named Tuples

So the first change in C# 7 is that you can now used named tuples. So we do away with that whole Item1, Item2 business. You can now name the properties inside the tuple by either naming it on the left hand side like :

void GetData()
{
    (string stringValue, int numberValue) myTuple = ("abc", 123);
    var myNumber = myTuple.numberValue;
}

Or naming it on the right hand side like :

void GetData()
{
    var myTuple = (stringValue: "abc", numberValue :123);
    var myNumber = myTuple.numberValue;
}

This does away with the whole “Item1” business which was one of my main complaints about earlier versions of tuples. It *almost* means that if you are calling a method that returns a named tuple, your calling code can act as if it’s not a tuple at all and is instead a class. Almost.

Returning Tuples From Methods

So before we had to have the return type of “Tuple”. Well it’s a slightly different syntax now that allows us to also name the tuple on the way out. It works a bit like so :

(string stringValue, int numberValue) GetData()
{
    return ("abc", 123);
}

void DoWork()
{
    var myData = GetData();
    Console.WriteLine(myData.stringValue);
}

Note that even if the method you are calling does not name the properties of the tuple, you can chose to do so yourself like so :

(string, int) GetData()
{
    return ("abc", 123);
}

void DoWork()
{
    (string stringValue, int numberValue) myData = GetData();
    Console.WriteLine(myData.stringValue);
}

Pretty easy stuff.

Deconstruction

There’s now this concept of “deconstruction” where we can take a tuple and turn it into individual variables. So for example :

(string, int) GetData()
{
    return ("abc", 123);
}

void DoWork()
{
    var (stringValue, numberValue) = GetData();
    Console.WriteLine(stringValue);
}

This can be useful if you are calling a library that returns a tuple but you ain’t about that and want individual variables.

I can also see this being pretty useful instead of using out params. For example, imagine if int.TryParse was reworked to look like :

(int, bool) ParseInt(string input)
{
    try
    {
        return (int.Parse(input), true);
    }
    catch
    {
        return (0, false);
    }
}

void DoWork()
{
    var (output, succeeded) = ParseInt("123");
    Console.WriteLine(succeeded);
}

I mean maybe not that much of an improvement, but we can see how it could be useful if you don’t want to use Tuples at all but are forced to calling a method that does use them.

Tuples Are Sometimes Immutable

A quick note on the immutability on Tuples. Are Tuples immutable? The answer is… It depends. C# Tuples *are not* immutable, but .NET Framework Tuples (The old way) are. For example :

static (string, int) GetData()
{
    return ("abc", 123);
}

static Tuple<string, int> GetDataOld()
{
    return Tuple.Create("abc", 123);
}

static void DoWork()
{
    (string stringValue, int numberValue) myData = GetData();
    myData.stringValue = "def"; //Fine

    var myDataOld = GetDataOld();
    myDataOld.Item1 = "def"; //Error

    Console.WriteLine(myData.stringValue);
}

If we use the new construct of Tuples (Named or Unamed), you are able to set values on the resulting tuple object. In the .NET construct where you use Tuple.Create, you cannot set the value of an item. This is probably very rarely going to come up as we go forward since it’s unlikely you will use the old Tuple construct, but it’s something to be aware of.

Alternatives To Tuples

Let’s look at some alternatives to how we might return the same data from a method. I’m going to use our example of parsing an int earlier as it’s actually a good example of returning two pieces of data from a single method.

Tuple

(int, bool) ParseInt(string input)
{
    try
    {
        return (int.Parse(input), true);
    }
    catch
    {
        return (0, false);
    }
}

void DoWork()
{
    var (output, succeeded) = ParseInt("123");
    Console.WriteLine(succeeded);
}

Out Param

bool ParseInt(string input, out int result)
{
    try
    {
        result = int.Parse(input);
        return true;
    }
    catch
    {
        result = 0;
        return false;
    }
}

void DoWork()
{
    var succeeded = ParseInt("123", out int result);
    Console.WriteLine(succeeded);
}

Dynamic Object

dynamic ParseInt(string input)
{
    IDictionary<string, object> returnObject = new ExpandoObject();
    try
    {
        returnObject.Add("result", int.Parse(input));
        returnObject.Add("succeeded", true);
    }
    catch
    {
        returnObject.Add("result", 0);
        returnObject.Add("succeeded", false);
    }

    return returnObject;
}

void DoWork()
{
    var result = ParseInt("123");
    Console.WriteLine(result.succeeded);
}

Return Object

class ParseIntResult
{
    public bool Succeeded { get; set; }
    public int Result { get; set; }
}

ParseIntResult ParseInt(string input)
{
    try
    {
        return new ParseIntResult { Result = int.Parse(input), Succeeded = true };
    }
    catch
    {
        return new ParseIntResult { Result = 0, Succeeded = false };
    }
}

void DoWork()
{
    var result = ParseInt("123");
    Console.WriteLine(result.Succeeded);
}

Which one looks best do you? We can remove the dynamic object because IMO that’s easily the worse. Out param is probably the next worst.  In terms of readability and maintainability, the return object/class looks the easiest but Tuple honestly isn’t that bad. So that leads us to….

So When Should You Use Tuples?

Happy for this to lead to comments saying I’m wrong. But in most cases, the usage of a Tuple is going to be wrong. I used the example of parsing an integer above because I think it’s one of the few cases where it might be reasonable to use. If you are creating a utility library and those library methods need to return more than one result but the creation of a return object for each method is too much, then a Tuple *could* be used (But doesn’t mean it should).

In almost all cases, I would start with a return class, and only then if that doesn’t look right, try a Tuple. But adding a Tuple to start with in most cases is going to be a bad move.

 

ENJOY THIS POST?
Join over 3.000 subscribers who are receiving our weekly post digest, a roundup of this weeks blog posts.
We hate spam. Your email address will not be sold or shared with anyone else.

NOTE : This post was initially written in early 2017 (!!!) but has now been completely revamped in 2020 to be up to date with .NET Core 3+ Watch feature. The original article was written in pre 1.0 days and is no longer relevant. But this is still a killer feature and should be used far more often!

One of the most overlooked features of .NET Core CLI is the “dotnet watch” command. With it, it allows you to have a “live reload” of your ASP.NET Core site running without having to either run the “dotnet run” command, or worse do the “Stop the process in Visual Studio. Write your changes. Recompile and run again” routine. The latter can be very annoying when all you are trying to do is do a simple one line fix.

If you are used to watches in other languages/tooling (Especially task runners like Gulp), then you will know how much of a boost watches are to productivity.

The Basics

I highly recommend creating a simple ASP.NET Core project to run through this tutorial with. The tooling can be a little finicky with large projects so it’s easier to get up and running with something small, then take what you’ve learned onto something a little larger.

For this demo, I have a simple controller that has a get method that returns a string value.

[Route("api/home")]
public class HomeController : Controller
{
	[HttpGet]
	public string Get()
	{
		return "Old Value";
	} 
}

Open a command prompt in your project directory, a terminal in VS Code, or even the Package Manager Console in Visual Studio and run the following command :

dotnet watch run

Note that if you previously have had to run the “dotnet run” command with other flags (e.g. “dotnet run -f net451” to specify the framework), this will still work using the watch command. Essentially it’s saying “Do a watch, and when something changes, do ‘this’ thing” which in our case is the run command.  You should see something similar to the following :

dotnet watch run
watch : Started
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

This means you are up and running. If I go to http://localhost:5000/api/home, I should see my controller return “Old Value”.

Now I head back to my controller and I change the Get action to instead return “New Value”. As soon as I hit save on this file I see the following in my console window :

watch : Exited
watch : File changed: C:\Projects\WatchExample\Controllers\HomeController.cs
watch : Started
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: http://localhost:5000

What we see is that the watch immediately exits, and it tells us that a file has been changed in HomeController.cs and so it starts recompiling immediately. When we browse to http://localhost:5000/api/home we see our “New Value” shown and we didn’t have to do anything else in terms of manually recompiling or running a new dotnet run command.

On larger projects, the recompile process can actually be a little slow so it’s not always an instant “change code and immediately refresh the browser” moment. Especially if you have a large dependency tree that means several projects need to be rebuilt before the site is back up and running. But it’s still going to be faster than whatever manual process you are used to.

Debugging With dotnet watch

So previously, debugging while using dotnet watch was almost a fruitless exercise. Each time your watch started and ran, a new “dotnet.exe” process would spin up. But the issue was it was impossible to find the “right” process to attach your debugger to. You might have a half dozen or so dotnet.exe processes running and you sort of had to wing it and pick the one that had been created most recent and hope for the best. Then each time you made a change, a *new* dotnet.exe would be spun up and your attached debugger was useless with you having to start the attach to debugger process all over again. Ugh!

As of .NET Core 3+, this is now much much easier.

Suppose I have my project up and running on a watch. In Visual Studio I simply go  Debug -> Attach To Debugger. I then filter all processes by the actual name of my project. In my case I called my project “WatchExample”, so I just start typing that into the filter box.

I click the Attach button and I’m away! Unfortunately each time you make a change the debugger is stopped while your project recompiles, but a helpful hint is to learn the “Reattach To Process” hotkey which in default Visual Studio key bindings is “Shift + Alt + P”. This immediately attaches the debugger to the last process it was on (Which in our case, is the our project exe), and we are away debugging again!

ENJOY THIS POST?
Join over 3.000 subscribers who are receiving our weekly post digest, a roundup of this weeks blog posts.
We hate spam. Your email address will not be sold or shared with anyone else.

In a previous post we talked about setting up IIS to host a .NET Core web app, and since then, I’ve had plenty of questions regarding why does ASP.NET Core even have the Kestrel Web Server (The inbuilt web server of the .NET Core platform), if you just host it in IIS anyway? Especially now that .NET Core can now run InProcess with IIS, it’s almost like having Kestrel is redundant. In some ways that may be true and for *most* use cases, you will want to use IIS. But here’s my quick rundown of why that might be (or might not be) the case.

Kestrel Features (Or Lack Thereof)

Now Kestrel is pretty featured, but it’s actually lacking a few fundamentals that may make it a bit of a blocker. Some of which are (but not limited to) :

  • HTTP access logs aren’t collected in Kestrel. For some, this doesn’t matter. But for others that use these logs as a debugging tool (Or pump them to something like Azure Diagnostics etc), this could be an issue.
  • Multiple apps on the same port is not supported in Kestrel simply by design. So when hosting on IIS, IIS itself listens on port 80 and “binds” websites to specific URLs. Kestrel on the other hand binds to an IP (Still with a website URL if you like), but you can’t then start another .NET Core Kestrel instance on the same port.  It’s a one to one mapping.
  • Windows Authentication does not exist on Kestrel as it’s cross platform (more on that later).
  • IIS has a direct FTP integration setup if you deploy via this method (Kestrel does not)
  • Request Filtering (e.g. Blocking access to certain file extensions, folders, verbs etc) is much more fully featured in IIS (Although some of this can be “coded” in Kestrel in some cases).
  • Mime Type Mapping (e.g. A particular file extension being mapped to a particular mime type on response) is much better in IIS.

I would note that many feature comparisons floating around out there are very very dated. Things like request limits (e.g. Max file upload size/POST body size) and SSL certificates have been implemented in Kestrel for a few years now. Even the above list may slowly shrink over time, but for now, just know there there are certainly things inside Kestrel that you may be used to inside IIS.

Cross Platform

Obviously .NET Core and by extension, Kestrel, is cross platform. That means it runs on Windows, Linux and Mac. IIS on the other hand is Windows only and probably forever will be. For those not on Windows systems, the choice of even using IIS is a non existent one. In these cases, you are comparing Kestrel to things like NGINX which can act as a reverse proxy and forward requests to Kestrel.

In some of these cases, especially if you don’t have experience using NGINX or Apache, then Kestrel is super easy to run on Linux (e.g. Double click your published app).

Server Management

Just quickly anecdotally, the management of IIS is much easier than managing a range of Kestrel web services. Kestrel itself can be run from the command line, but therein lies the issue where you often have to set up your application as a Windows Service (More info here : Hosting An ASP.NET Core Web App As A Windows Service In .NET Core 3) so that it will automatically start on server restarts etc. You end up with all these individual “Windows Services” that you have to install/manage separately.  On top of that, everything being code based can be both a boon for source control and IAC, but it can also be a headache to configure features across a range of applications. If you are used to setting things up in IIS and think that it’s a good experience, then you are better at sticking with it.

Existing Setup Matters

Your existing setup may affect your decision to use Kestrel vs IIS in two very distinct ways.

If you are already using IIS, and you want to keep it that way and manage everything through one portal, then you are going to pick IIS no matter what. And it makes sense, keeping things simple is almost always the right route. And IIS has great support for hosting .NET Core web apps (Just check our guide out here : Hosting An ASP.NET Core Web Application In IIS).

But conversely, you may have IIS installed already, but it isn’t set up to host .NET Core apps and you don’t want to (or can’t) install anything on the machine. In these cases, Kestrel is great for sitting side by side with your existing web server and it running completely in isolation. It can run listening to a non standard port, leaving your entire IIS setup intact. This also goes for hosting on a machine that doesn’t currently have IIS installed, Kestrel can be stood up immediately from code with little to no configuration without modifying the machine’s features or running an installer of any kind. It’s basically completely portable.

Microsoft’s Recommendation

You’ll often find articles mentioning that Microsoft recommends using a reverse proxy, whether that be IIS, NGINX or Apache, to sit infront of Kestrel and be your public facing web server/proxy. Anecdotally, I’ve found this to be mentioned less and less as Kestrel gains more features. You will actually struggle to find mention of *not* using Kestrel on public facing websites in the official documentation nowadays (For .NET Core 3+). That’s not to say that it’s a good idea to use Kestrel for everything, just that it’s less of a security risk to these days.

My Final Take

Personally,  I use both.

I use IIS as my defacto choice as 9 times out of 10, when working in an Windows environment, there is already a web server setup hosting .NET Framework apps. It just makes things easier to setup and manage, especially for developers that are new to .NET Core, they don’t have another paradigm to learn.

I use Kestrel generally when hosting smaller API’s that either don’t have IIS setup, don’t need IIS setup (e.g. a web app that just gets run on the local machine for local use), or have IIS setup but they don’t want to install the hosting bundle. Personally, I generally don’t end up using many IIS features like Windows Auth or FTP, so I don’t miss these features.

ENJOY THIS POST?
Join over 3.000 subscribers who are receiving our weekly post digest, a roundup of this weeks blog posts.
We hate spam. Your email address will not be sold or shared with anyone else.

For the past few years I’ve been almost exclusively using Azure’s PAAS Websites to host my .NET Core applications. Whereby I set up my Azure Devops instance to point to my Azure Website, and at the click of the button my application is deployed and you don’t really have to think too hard about “how” it’s being hosted.

Well, recently I had to set up a .NET Core application to run on a fresh server behind IIS and while relatively straight forward, there were a few things I wish I knew beforehand. Nothing’s too hard, but some guides out there are waaayyy overkill and take hours to read let alone implement what they are saying. So hopefully this is a bit more of a straight forward guide.

You Need The ASP.NET Core Hosting Bundle

One thing that I got stuck on early on was that for .NET Core to work inside IIS, you actually need to do an install of a “Hosting Module” so that IIS knows how to run your app.

This actually frustrated me a bit at first because I wanted to do “Self Contained” deploys where everything the app needed to run was published to the server. So… If I’m publishing what essentially amounts to the full runtime with my app, why the hell do I still need to install stuff on the server!? But, it makes sense. IIS can’t just magically know how to forward requests to your app, it needs just a tiny bit of help. Just incase someone is skimming this post, I’m going to bold it :

Self contained .NET Core applications on IIS still need the ASP.NET Core hosting bundle

So where do you get this “bundle”. Annoyingly it’s not on the main .NET Core homepage and you need to go to the specific version to get the latest version. For example here : https://dotnet.microsoft.com/download/dotnet-core/3.1.

It can be maddening trying to find this particular download link. It will be on the right hand side buried in the runtime for Windows details.

Note that the “bundle” is the module packaged with the .NET Core runtime. So once you’ve installed this, for now atleast, self contained deployments aren’t so great because you’ve just installed the runtime anyway. Although for minor version bumps it’s handy to keep doing self contained deploys because you won’t have to always keep pace with the runtime versions on the server.

After installing the .NET Core hosting bundle you must restart the server OR run an IISReset. Do not forget to do this!

In Process vs Out Of Process

So you’ve probably heard of the term “In Process” being bandied about in relation to .NET Core hosting for a while now. I know when it first came out in .NET Core 2.2, I read a bit about it but it wasn’t the “default” so didn’t take much notice. Well now the tables have turned so to speak, so let me explain.

From .NET Core 1.X to 2.2, the default way IIS hosted a .NET Core application was by running an instance of Kestrel (The .NET Core inbuilt web server), and forwarding the requests from IIS to Kestrel. Basically IIS acted as a proxy. This works but it’s slow since you’re essentially doing a double hop from IIS to Kestrel to serve the request. This method of hosting was dubbed “Out Of Process”.

In .NET Core 2.2, a new hosting model was introduced called “In Process”. Instead of IIS forwarding the requests on to Kestrel, it serves the requests from within IIS. This is much faster at processing requests because it doesn’t have to forward on the request to Kestrel. This was an optional feature you could turn on by using your csproj file.

Then in .NET Core 3.X, nothing changed per-say in terms of how things were hosted. But the defaults were reversed so now In Process was the default and you could use the csproj flag to run everything as Out Of Process again.

Or in tabular form :

VersionSupports Out Of ProcessSupports In ProcessDefault
.NET Core <2.2YesNoN/A
.NET Core 2.2YesYesOut Of Process
.NET Core 3.XYesYesIn Process

Now to override the defaults, you can add the following to your csproj file (Picking the correct hosting model you want).

<PropertyGroup>
  <AspNetCoreHostingModel>InProcess/OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

As to which one you should use? Typically, unless there is a specific reason you don’t want to use it, InProcess will give you much better performance and is the default in .NET Core 3+ anyway.

After reading this section you are probably sitting there thinking… Well.. So I’m just going to use the default anyway so I don’t need to do anything? Which is true. But many guides spend a lot of time explaining the hosting models and so you’ll definitely be asked questions about it from a co-worker, boss, tech lead etc. So now you know!

UseIIS vs UseIISIntegration

There is one final piece to cover before we actually get to setting up our website. Now *before* we got the “CreateDefaultBuilder” method as the default template in .NET Core, you had to build your processing pipeline yourself. So in your program.cs file you would have something like :

var host = new WebHostBuilder()
	.UseKestrel()
	.UseContentRoot(Directory.GetCurrentDirectory())
	.UseIISIntegration()
	.UseStartup<Startup>()
	.Build();

So here we can actually see that there is a call to UseIISIntegration . There is actually another call you may see out in the wild called UseIIS  without the integration. What’s the difference? It’s actually quite simple. UseIISIntegration  sets up the out of process hosting model, and UseIIS  sets up the InProcess model. So in theory, you pick one or the other but in practice CreateDefaultBuilder  actually calls them both and later on the SDK works out which one you are going to use based on the default or your csproj flag described above (More on that in the section below).

So again, something that will be handled for you by default, but you may be asked a question about.

Web.Config Shenanigans

One issue we have is that for IIS to understand how to talk to .NET Core, it needs a web.config file. Now if you’re using IIS to simply host your application but not using any additional IIS features, your application probably doesn’t have a web.config to begin with. So here’s what the .NET Core SDK does.

If you do not have a web.config in your application, when you publish your application, .NET Core will add one for you. It will contain details for IIS on how to start your application and look a bit like this :

<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet" arguments=".\MyTestApplication.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

So all it’s doing is adding a handler for IIS to be able to run your application (Also notice it sets the hosting model to InProcess – which is the default as I’m running .NET Core 3.X).

If you do have a web.config, it will then append/modify your web.config to add in the the handler on publish. So for example if you are using web.config to configure.. I don’t know, mime types. Or maybe using some basic windows authorization. Then it’s basically going to append in the handler to the bottom of your own web.config.

There’s also one more piece to the puzzle. If for some reason you decide that you want to add in the handler yourself (e.g. You want to manage the arguments passed to the dotnet command), then you can actually copy and paste the above into your own web.config.

But. There is a problem. 

The .NET Core SDK will also always try and modify this web.config on publish to be what it *thinks* the handler should look like. So for example I copied the above and fudged the name of the DLL it was passing in as an argument. I published and ended up with this :

arguments=".\MyTestApplication.dll .\MyTestApplicationasd.dll"

Notice how it’s gone “OK, you are running this weird dll called MyTestApplicationasd.dll, but I think you should run MyTestApplication.dll instead so I’m just gonna add that for you”. Bleh! But there is a way to disable this!

Inside your csproj you can add a special flag like so :

<PropertyGroup>
  <TargetFramework>netcoreapp3.0</TargetFramework>
  <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

This tells the SDK don’t worry, I got this. And it won’t try and add in what it thinks your app needs to run under IIS.

Again, another section on “You may need to know this in the future”. If you don’t use web.config at all in your application then it’s unlikely you would even realize that the SDK generates it for you when publishing. It’s another piece of the puzzle that happens in the background that may just help you in the future understand what’s going on under the hood when things break down.

An earlier version of this section talked about adding your own web.config to your project so you could point IIS to your debug folder. On reflection, this was bad advice. I always had issues with projects locking and the “dotnet build” command not being quite the same as the “dotnet publish”. So for that reason, for debugging, I recommend sticking with IIS Express (F5), or Kestrel by using the dotnet run command. 

IIS Setup Process

Now you’ve read all of the above and you are ready to actually set up your website. Well that’s the easy bit!

First create your website in IIS as you would a standard .NET Framework site :

You’ll notice that I am pointing to the *publish* folder. As described in the section above about web.config, this is because my particular application does not have a web.config of it’s own and therefore I cannot just point to my regular build folder, even if I’m just testing things out. I need to point to the publish folder where the SDK has generated a web.config for me.

You’ll also notice that in my case, I’m creating a new Application Pool. This is semi-important and I’ll show you why in a second.

Once you’ve create your website. Go to your Application Pool list, select your newly created App Pool, and hit “Basic Settings”. From there, you need to ensure that .NET CLR Version is set to “No Managed Code”. This tells IIS not to kick off the .NET Framework pipeline for your .NET Core app.

Obviously if you want to use shared application pools, then you should create a .NET Core app pool that sets up No Managed Code.

And that’s it! That’s actually all you need to know to get up and running using IIS to host .NET Core! In a future post I’ll actually go through some troubleshooting steps, most notably the dreaded HTTP Error 403.14 which can mean an absolute multitude of things.

ENJOY THIS POST?
Join over 3.000 subscribers who are receiving our weekly post digest, a roundup of this weeks blog posts.
We hate spam. Your email address will not be sold or shared with anyone else.