DEV Community: QuillCodes

Deep Dive on .NET Core String.Create() Performance

QuillCodes — Thu, 29 Oct 2020 15:35:53 +0000

When was the last time that an insignificant detail sparked a movement in your brain? As a software engineer, I have a habit of focusing on the one tiny detail I have never seen before in a new block of code. At that point, the gears in my brain begin turning. I love these moments. The ones where the tiniest piece of trivia sends me down a rabbit-hole of discovery.

What did that look like the last time it came to you?

It recently happened to me as I was browsing Twitter. I came upon this exchange between David Fowler and Damian Edwards, discussing the .NET Span<T> API. I have used the Span<T> API before, but I found something new and different in the tweets.

// Detect dark theme var iframe = document.getElementById('tweet-1318638349544873985-907'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1318638349544873985&theme=dark" }

It's a small thing, The item that began my dive down the rabbit-hole. The String.Create method used above was the piece I had never seen before. String.Create was a hidden gem, and I was determined to uncover its mysteries. I found myself asking the question:

"Why use this method for creating strings over others?"

I began the journey, and it took me to a few interesting places that I would like to share with you. In this article, we will delve into a few topics...

What is String.Create and how is it different from other APIs?
What does String.Create do better and how can it make my C# code faster?
How much more performance can it achieve?
What pitfalls can and should be avoided?

Definitions

To make the article a little easier, I am going to refer to a few .NET Core APIs in the following ways:

Create - Refers to using String.Create().
Concat - Refers to using String.Concat() or the plus (+) operator.
Format - Refers to using String.Format(), one of its many overloads, or string interpolation with the $"" syntax.
StringBuilder - Refers to constructing a string with the fluent StringBuilder class and API.

How Does It Work?

The .NET Core codebase is open source and developed on GitHub. This provides a great opportunity to dive in and analyze Microsoft's own practices. They provided the Create API, so seeing how they use it should provide valuable insight. Let's start with a deep dive into the String object and its relevant APIs.

To generically build a string out of raw character data, you need to use the constructor that requires a pointer to a char array. Using this API directly would require placing individual characters into specific array locations. Below is the code that runs when you allocate a string using this constructor. There are many other ways to create strings, but this is what I consider the most comparable to the Create method.

string Ctor(char[]? value)
{
    if (value == null || value.Length == 0)
        return Empty;

    string result = FastAllocateString(value.Length);

    Buffer.Memmove(
        elementCount: (uint)result.Length, // derefing Length now allows JIT to prove 'result' not null below
        destination: ref result._firstChar,
        source: ref MemoryMarshal.GetArrayDataReference(value));

    return result;
}

To summarize the important steps:
1) Inputs are validated. An empty or null array returns String.Empty.
2) We allocate memory using FastAllocateString based on the array Length. FastAllocateString is implemented within the .NET Runtime itself and underpins nearly all string allocations.
3) We call Buffer.Memmove, which copies all bytes from the original array into the newly allocated string.
4) Return the resulting string.

To use this constructor, we need to supply it with a char array. After its job is complete, we end up with both a (now unnecessary) char array and a string, each with identical data. If we were to modify the original array, then the string would remain unmodified, because it is a separate and distinct copy of the data. In a high-performance .NET environment, saving object and array allocations can be extremely valuable because it reduces the total amount of work that the .NET Garbage Collector needs to do whenever it runs. Every extra object that is left in memory increases the frequency of collections and hurts total performance.

If you would like to learn more about .NET Garbage Collection and how it can impact performance, there are many fantastic resources online:

To contrast with the constructor and to eliminate this unnecessary array allocation, we take a look at the code that runs for the Create method:

public static string Create<TState>(int length, TState state, SpanAction<char, TState> action)
{
    if (action == null)
        throw new ArgumentNullException(nameof(action));

    if (length <= 0)
    {
        if (length == 0)
            return Empty;
        throw new ArgumentOutOfRangeException(nameof(length));
    }

    string result = FastAllocateString(length);
    action(new Span<char>(ref result.GetRawStringData(), length), state);

    return result;
}

The steps are similar but contain a critical difference:
1) Inputs are validated. Invalid action or negative Length will throw an exception and Length of 0 returns Empty;
2) We allocate memory using FastAllocateString based on the length parameter.
3) Convert the newly-allocated string to a Span<char>.
4) Invoke the provided action and pass in the new Span<char> along with the provided state.
5) Return the resulting string.

This methodology avoids the extra allocation by allowing us to pass in a SpanAction, which functions as a set of instructions for how our string should be created instead of requiring a second copy of all the bytes we need put into the string.

An analogy could be drawn from graphic design. You might want to get a professional logo created for your business, and you probably decided that you wanted it created in a vector format like SVG or EPS. You create a document that has details on the theme, colors, and general look of your logo. You now have a couple of options:
1) Draw the first draft yourself as close to the professional version as possible, send it to a graphic designer, and have them create a finalized version.
2) Send your original detailed document to the graphic designer, who creates a finalized logo from the information you provided.

In the first situation, you end up with two images, but only one that you plan to use. Your original can probably be thrown away without any ceremony, as you now have your professionally designed version. In the second case, you have not produced any extra product and therefore have produced less waste.

The process for the Create method is closer to the situation where you sent your documentation to a designer. By telling them exactly what you wanted from the beginning, you only generate one final artifact in the form that you need.

How is String.Create Better?

At this point, you might be curious about the Create method, but you don't necessarily know why it's better than the methods you have used before. The Create APIs usefulness is situational, but it can be extremely powerful in the proper context.

It pre-allocates a bucket, and then gives you an interface to fill that bucket safely. Other methods that produce similar results could require writing unsafe code or managing buffer pools.
It avoids extra copy-operations of your data which often results in fewer allocations. This reduces pressure from your Garbage Collector which can speed up your overall program.
It allows you to focus your high-performance code on the business requirements of your application rather than interleaving your string-building code with complex memory management.

Use Cases for String.Create()

You can only use the Create method when you already know your final string's length. However, you can work creatively with this constraint and discover several ways to leverage Create. I performed a search through the codebases for dotnet/aspnetcore and dotnet/runtime to see where the Microsoft team decided to utilize this API. The rest of this article will dive deep into three trends that I found:

Generating IDs
Performance-Sensitive Concatenations
Formatting Complex Strings

Generating IDs

Consider this class from the ASP.NET Core repository used for generating correlation IDs on each web request. It generates a correlation ID in the format of 13 characters chosen from the numbers (0-9) and most upper-case letters (A-V).

// Copyright (c) .NET Foundation. All rights reserved.
// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.

using System;
using System.Threading;

namespace Microsoft.AspNetCore.Connections
{
    internal static class CorrelationIdGenerator
    {
        // Base32 encoding - in ascii sort order for easy text based sorting
        private static readonly char[] s_encode32Chars = "0123456789ABCDEFGHIJKLMNOPQRSTUV".ToCharArray();

        // Seed the _lastConnectionId for this application instance with
        // the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001
        // for a roughly increasing _lastId over restarts
        private static long _lastId = DateTime.UtcNow.Ticks;

        public static string GetNextId() => GenerateId(Interlocked.Increment(ref _lastId));

        private static string GenerateId(long id)
        {
            return string.Create(13, id, (buffer, value) =>
            {
                char[] encode32Chars = s_encode32Chars;

                buffer[12] = encode32Chars[value & 31];
                buffer[11] = encode32Chars[(value >> 5) & 31];
                buffer[10] = encode32Chars[(value >> 10) & 31];
                buffer[9] = encode32Chars[(value >> 15) & 31];
                buffer[8] = encode32Chars[(value >> 20) & 31];
                buffer[7] = encode32Chars[(value >> 25) & 31];
                buffer[6] = encode32Chars[(value >> 30) & 31];
                buffer[5] = encode32Chars[(value >> 35) & 31];
                buffer[4] = encode32Chars[(value >> 40) & 31];
                buffer[3] = encode32Chars[(value >> 45) & 31];
                buffer[2] = encode32Chars[(value >> 50) & 31];
                buffer[1] = encode32Chars[(value >> 55) & 31];
                buffer[0] = encode32Chars[(value >> 60) & 31];
            });
        }
    }
}

The algorithm is brief:
1) Start your correlation ID at the latest tick count for UTC. The tick count is a 64-bit integer.
2) Increment by one on each request for a new ID.
3) For each of 13 characters:
* Shift the value by 5 additional (character_index * 5) bits.
* Grab the rightmost 5 bits (shifted_value & 31) and choose a character based upon a predetermined table.

For our baseline comparison, I used a naive implementation that utilizes StringBuilder. I chose this option because StringBuilder is often recommended as a good API for performance over regular string concatenation. I wrote additional implementations that attempted to use StringBuilder (with capacity), StringBuilder (without capacity), and simple concatenation.

Execution Benchmarks

Method	Mean	Error	StdDev	StdErr	Ratio	RatioSD	Rank
StringCreate	16.58 ns	0.366 ns	0.342 ns	0.088 ns	0.26	0.02	1
StringBuilder	59.81 ns	1.555 ns	4.511 ns	0.458 ns	1.00	0.00	2
StringBuilderNoCapacity	64.04 ns	2.426 ns	7.077 ns	0.715 ns	1.08	0.15	3
StringConcatenation	342.23 ns	6.872 ns	18.579 ns	2.015 ns	5.76	0.52	4

Memory Benchmarks

Method	Gen 0	Allocated
StringCreate	0.0115	48 B
StringBuilder	0.0362	152 B
StringBuilderNoCapacity	0.0362	152 B
StringConcatenation	0.2217	928 B

The String.Create() method shows the best performance in performance (16.58 nanoseconds) and allocations (only 48 bytes!). Interestingly, the StringBuilder with no capacity specified also shows a small edge over the regular StringBuilder (it still loses to String.Create(), but that is interesting to note for future StringBuilder use).

Performance-Sensitive Concatenation

The C# Roslyn compiler is very intelligent about optimizing poor concatenations. The compiler will tend to convert multiple uses of the plus + operator into singular calls to Concat and likely has many additional tricks of which I am not aware. For these reasons, concatenation is generally a fast operation, but it still can be edged out by Create for simple scenarios.

The sample code to demonstrate concatenation with the Create method is straightforward.

public static class ConcatenationStringCreate
{
    public static string Concat(string first, string second)
    {
        first ??= string.Empty;
        second ??= String.Empty;
        bool addSpace = second.Length > 0;

        int length = first.Length + (addSpace ? 1 : 0) + second.Length;
        return string.Create(length, (first, second, addSpace),
        (dst, v) =>
        {
            ReadOnlySpan<char> prefix = v.first;
            prefix.CopyTo(dst);

            if (v.addSpace)
            {
                dst[prefix.Length] = ' ';

                ReadOnlySpan<char> detail = v.second;
                detail.CopyTo(dst.Slice(prefix.Length + 1, detail.Length));
            }
        });
    }
}

I crafted this particular case after finding only one real example in the .NET Core source code. This feels like a case that could be reasonably abstracted and sprinkled throughout a codebase that is making excessive use of the plus + operator or String.Concat very frequently. The likely reason that I did not find more cases is that the benchmarks bear this out as being a marginal gain.

Method	FirstPart	SecondPart	Mean	Error	StdDev	StdErr	Median	Ratio	RatioSD	Rank
Create	?	?	54.84 ns	2.361 ns	3.534 ns	0.645 ns	53.77 ns	0.87	0.08	1
Normal	?	?	63.69 ns	3.825 ns	5.726 ns	1.045 ns	63.50 ns	1.00	0.00	2

Create	?	Sedf(...)ctus [307]	51.11 ns	1.570 ns	2.349 ns	0.429 ns	50.43 ns	0.84	0.05	1
Normal	?	Sedf(...)ctus [307]	61.08 ns	2.601 ns	3.893 ns	0.711 ns	60.38 ns	1.00	0.00	2

Create	Lorem Ipsum	?	55.88 ns	4.070 ns	6.092 ns	1.112 ns	52.59 ns	0.95	0.09	1
Normal	Lorem Ipsum	?	58.66 ns	1.005 ns	1.505 ns	0.275 ns	58.44 ns	1.00	0.00	2

Create	Lorem Ipsum	Sedf(...)ctus [307]	50.26 ns	0.794 ns	1.188 ns	0.217 ns	50.18 ns	0.86	0.06	1
Normal	Lorem Ipsum	Sedf(...)ctus [307]	59.04 ns	3.779 ns	5.656 ns	1.033 ns	57.72 ns	1.00	0.00	2

Note: There was nothing to report for memory benchmarks as both methods generated the same amount of allocated memory.

I find these results interesting. Even for generalized Concat usage, the Create method is marginally faster by a few percentage points. However, since it would be possible to generalize a library of fast string concatenation methods, the tradeoff of maintenance vs performance would become much cleaner. You could wrap all of your concatenation methods in a static class, add your unit tests, and never touch them again. From a maintenance perspective, Concat is still cleaner due to being very recognizable to other developers on your team. However, if you are concatenating strings at the pace of millions per second (such as a high traffic ASP.NET application), these few percentage points may be worth it. Overall, I would still advise profiling your specific case to prove that your specialized method is faster.

Formatting of Complex Strings

Complex formats can also be built using Create when you know the length of all of the smaller segments involved. Usually, this will be when you have these strings encapsulated as properties of a single class or within the parameters of a single method. It may also be advantageous to use Create when dealing with rows of fixed-width or delimited data, such as a CSV file.

I found a great example in the ASP.NET Core repository in the form of the SetCookieHeaderValue class. This class contains all of the properties necessary to write out a cookie HTTP header. Conveniently, this class also included a method that used StringBuilder to accomplish the same formatting task. This gave me a great opportunity to write a fast benchmark.

Here is the table that shows the two methods up against one another:

Method	Mean	Error	StdDev	StdErr	Median	Ratio	RatioSD	Rank
Create	538.5 ns	10.80 ns	30.99 ns	3.18 ns	528.7 ns	0.67	0.05	1
StringBuilder	810.9 ns	15.75 ns	24.52 ns	4.33 ns	809.0 ns	1.00	0.00	2

For a complex string like a cookie header, Create improves performance by nearly 33%! Complex formats like this show that there is a lot to gain when using the Create method.

While the SetCookieHeaderValue class provides an ideal data point, its logic is rather long and complex. I wrote a simple class to demonstrate the same formatting principles.

public class Dog
{
    public string Name { get; set; }

    public int? Age { get; set; }

    public string Color { get; set; }

    public override string ToString()
    {
        return StringCreate();
    }

    /// <summary>
    /// Format the description string of the Dog class using String.Create()
    /// </summary>
    public string StringCreate()
    {
        var length = 0;
        // Constants
        const string dogPrefix = "[DOG] ";
        const string unknownName = "Unknown";
        const string leftAgeChunk = " (";
        const char rightAgeChunk = ')';
        const string leftColorChunk = " [";
        const char rightColorChunk = ']';
        static int integerLength(int val) => (int)Math.Floor(Math.Log10((double)val) + 1);

        /* Compute Lengths */
        length += dogPrefix.Length + (Name ?? unknownName).Length; // Prefix + Name

        if (Color is string)
        {
            length += 3 /* left + right chunk length */ + Color.Length;
        }

        if (Age.HasValue)
        {
            length += 3 /* left + right chunk length */ + integerLength(Age.Value); /* Digits in age */
        }
        /* Use State + Computed Length to Build String */
        return String.Create<Dog>(length, this, (buffer, dog) =>
        {
            var prefixSpan = dogPrefix.AsSpan();
            prefixSpan.CopyTo(buffer);
            var span = buffer.Slice(prefixSpan.Length);

            var nameSpan = (dog.Name ?? unknownName).AsSpan();
            nameSpan.CopyTo(span);
            span = span.Slice(nameSpan.Length);

            if(dog.Color is string)
            {
                leftColorChunk.AsSpan().CopyTo(span);
                span = span.Slice(2);
                var colorSpan = dog.Color.AsSpan();
                colorSpan.CopyTo(span);
                span = span.Slice(colorSpan.Length);
                span[0] = rightColorChunk;
                span = span.Slice(1);
            }

            if(dog.Age.HasValue)
            {
                leftAgeChunk.AsSpan().CopyTo(span);
                span = span.Slice(2);
                dog.Age.Value.TryFormat(span, out int written, provider: CultureInfo.InvariantCulture);
                span = span.Slice(written);
                span[0] = rightAgeChunk;
            }
        });
    }

    /// <summary>
    /// Format the description string of the Dog class using basic concatenation.
    /// </summary>
    public string Concatenation() 
    {
        var val = "[DOG] " + (Name ?? "Unknown");

        if(Color is string)
        {
            val += " [" + Color + "]";
        }

        if(Age.HasValue)
        {
            val += " (" + Age.Value + ")";
        }

        return val;
    }

    /// <summary>
    /// Format the description string of the Dog class using String.Format()
    /// </summary>
    public string StringFormat()
    {
        return String.Format("[DOG] {0}{5}{4}{6}{2}{1}{3}",
            Name ?? "Unknown",
            Age,
            Age.HasValue ? " (" : String.Empty,
            Age.HasValue ? ")" : String.Empty,
            Color,
            Color is string ? " [" : String.Empty,
            Color is string ? "]" : String.Empty);
    }
}

The Dog class above contains three methods that should produce the identical output: StringCreate, Concatenation, and StringFormat. Each method uses a formatting strategy that matches its name. Despite being much more complex, the actual strategy of StringCreate is relatively simple:
1) Preemptively calculate the length of each property of the Dog class. Some properties may require some creative logic to calculate length without materializing the full string (Int32 is a good example).
2) Invoke String.Create using the current class (this) as the state parameter along with the pre-calculated length.
3) Use the Span<T> APIs to fill the newly instantiated buffer variable and return the final string.

Overall, the StringFormat and Concatenation methods are far shorter and less complex. This exemplifies the difficulties you might encounter when properly formatting complex strings using the Create method and why it should only be used on performance-critical paths in your code. However, utilizing this method appropriately can pay significant dividends in overall performance.

Execution Time Benchmarks

Method	Dog	Mean	Error	StdDev	Ratio	Rank
StringCreate	[DOG] Fido (20) [23]	68.73 ns	1.218 ns	1.017 ns	0.18	1
Concatenation	[DOG] Fido (20) [23]	105.18 ns	2.118 ns	2.828 ns	0.27	2
StringFormat	[DOG] Fido (20) [23]	377.44 ns	7.363 ns	19.653 ns	1.00	3

Concatenation	[DOG] Fluffy	18.60 ns	0.451 ns	0.901 ns	0.06	1
StringCreate	[DOG] Fluffy	27.85 ns	0.630 ns	1.213 ns	0.09	2
StringFormat	[DOG] Fluffy	295.93 ns	5.952 ns	9.440 ns	1.00	3

StringCreate	[DOG] Pluto [Yellow]	37.60 ns	0.835 ns	1.325 ns	0.12	1
Concatenation	[DOG] Pluto [Yellow]	51.16 ns	1.437 ns	4.213 ns	0.16	2
StringFormat	[DOG] Pluto [Yellow]	318.94 ns	6.312 ns	17.595 ns	1.00	3

Memory Benchmarks

Method	Dog	Gen 0	Allocated
StringCreate	[DOG] Fido (20) [23]	0.0172	72 B
Concatenation	[DOG] Fido (20) [23]	0.0516	216 B
StringFormat	[DOG] Fido (20) [23]	0.0420	176 B

Concatenation	[DOG] Fluffy	0.0115	48 B
StringCreate	[DOG] Fluffy	0.0114	48 B
StringFormat	[DOG] Fluffy	0.0305	128 B

StringCreate	[DOG] Pluto [Yellow]	0.0153	64 B
Concatenation	[DOG] Pluto [Yellow]	0.0268	112 B
StringFormat	[DOG] Pluto [Yellow]	0.0343	144 B

For the more complex cases, formatting using the Create method is between 25% and 35% faster. The benchmark methods I chose show another reason to carefully consider this use case for the Create method. You can see that simple concatenation performs slightly better when there are fewer elements to format. In the case where the Dog has no Age or Color value, the work needed to calculate and format the string eclipses the performance gain from using Create. However, once we populate these properties, Concat quickly becomes the poorer option. This shows why it is important to understand your data before using this method as well. If 99% of your cases are simple, you simply will not need this much help. Format is consistently the slowest option, though is arguably the fastest method to write initially and likely the most maintainable in the future.

When NOT To Use String.Create()

Create shows great promise in performance-critical code, but there are many legitimate reasons to avoid it. As software engineers, we often become more tied to the metrics of our systems at the expense of the bigger picture. Generally, I think decent but maintainable code should prevail over fantastic performance. That leads me to prescribe three general cases when you should avoid using Create, even if it sacrifices performance.

1) Do Not Use When Readability is Important

Ultimately, this API is not maintenance-friendly. Your scenario should demand very high performance and your code should be well-factored and contain unit tests. When writing code that requires occasional maintenance, you can easily stick with one of these simpler formatting methods:

Format or String Interpolation when generating simple strings with dynamic values.
StringBuilder when creating strings that require a loop or many conditional elements.
Concat or a simple + when you just need to combine a small number of strings.

2) Do Not Use When Culture is Important

Format, String Interpolation, and most ToString() methods respect cultural formatting options. This gives your code the crucial ability to adapt to culture-specific date, numeral, and currency formats without having to code that logic yourself. Create does not offer any support for these APIs on its own, and attempting to mimic the behavior in your code would likely require allocating additional strings, thus removing the advantages of using the Create method.

3) (Probably) Do Not Use When the Output is for Humans

This situation is a bit subjective. The reason I would not recommend using Create for formatting for humans is that humans often want things to change. Since formatting using the Create method is extremely verbose, any changes are likely to cause increased complexity over time and thereby generate an accumulating amount of technical debt. In my opinion, the best usage of Create is on machine-readable strings or more generalized string-writing APIs that are unlikely to change in the future. As is often the case in software development, the specifics of your situation are the most important, but I think this is a good general rule to avoid this for any code you anticipate modifying frequently in the future.

Is String.Create() Right for You?

The answer to this question is definitely it depends. I began this investigation by focusing on something new to me: the String.Create method. I dove down a bit of a rabbit-hole looking for new and interesting ways to use this API. During this journey, I found three primary ways of using the method: (1) generating IDs, (2) fast concatenation, and (3) complex string formatting. Our benchmarks showed that we could, with reasonable consistency, produce a faster method using String.Create at the expense of simpler, more readable code. When answering the question above, you should always consider:

How important is this code's readability?
How likely is it to change?
How much will my program use this code and how much performance will it gain?

These all depend on your code and your team's strengths, but my hope today is that I have given you some tools to help you determine your path.

Simplify C# with Expression-Bodied Members

QuillCodes — Thu, 15 Oct 2020 22:49:44 +0000

You Can Simplify Your Syntax

C# is a fantastic language because it constantly evolves in a way that simplifies syntax and makes the your code more expressive. Expression-bodied members were released in C# 6 and further enhanced in C# 7. At the time I was still a junior developer and had not yet decided that C# and .NET were going to be my long-term focus.

I am not going to say that this feature "sealed the deal" for me and .NET, but it's definitely the feature I miss most when using any other language.

Simple Expression-bodied Members

The simplest form is just to take any existing read-only property and condense it down.

public int MyProperty
{
  get 
  {
    return _myField;
  }
}

This becomes:

public int MyProperty => _myField;

You can even use it for simple method bodies:

public decimal CalculateTax(decimal rate) => _totalPrice * rate;

It saves you time, and it saves you space on your screen. Most C# style conventions say that the opening bracket { and closing bracket } belong on new lines (with some exceptions). You could argue with the style guide, but on a larger team that is probably a losing battle. This feature solves this problem by omitting the brackets entirely.

Expression-bodied Members Can Help Reduce Boilerplate

Not impressed yet? What if I told you that you can use expression-bodied members on full properties?

private int _myField;

public int MyProperty 
{
  get => _myField; 
  set => _myField = value;  
}

That is pretty nifty, but honestly not impressive unless you have logic to call on your getter/setter.

private int _myField;

private void SetField(ref int field, int value, [CallerMemberName]string memberName =  "")
{
  field = value;
  Console.WriteLine($"{memberName} was set to {value}.");
}

public int MyProperty
{
  get => _myField;
  set => SetField(ref _myField, value);
}

// Output for "MyProperty = 5"
// MyProperty was set to 5.

Expression-Bodied Members Can be Used in Constructors

The most repetive boilerplate you tend to get with C# is setting class fields in constructors.

public class Cake
{
  private readonly IFrosting _frosting;

  public Cake(IFrosting frosting) => _frosting = frosting;
}

This simplifies your single-assignment constructors greatly. However, you can also combine this with tuple syntax in order to perform multiple assignments at once.

public class Cake
{
  private readonly ISprinkles _sprinkles;
  private readonly IFrosting _frosting;

  public Cake(ISprinkles sprinkles, IFrosting frosting)
    => (_sprinkles, _frosting) = (sprinkles, frosting);
}

This syntax will assign the fields in the order that they appear in the tuple.

Note: Keep in mind that if your parameters are all of similar types, like string, that getting them in the wrong order can be easy using this syntax. However, fields of different types will be caught by the compiles. Thus, I would only recommend it when assigning a set of varied fields.

Hope you enjoyed this quick overview of one of my favorite features of C#!

Set Class Fields Using 'out' Parameters

QuillCodes — Thu, 24 Sep 2020 03:20:43 +0000

Did You Know?

You can set class fields with 'out' method parameters

Whether you like out parameters or not in C#, they are here to stay. They decorate a number of common patterns in the .NET ecosystem.

The TryParse pattern where the return is a bool that indicates success and your parse result comes from the out parameter.

However, very often you want to set your class field with the parse result. At first you would assume that you need to declare a temporary variable to hold the value and then assign the field.

public class MyClass
{
  private int _parsedIntField;

  public MyClass(string strToParse)
  {
    if (!Int32.TryParse(strToParse, out int result))
    {
      throw new ArgumentException("Please provide a valid numerical string.", nameof(strToParse));
    }

    _parsedIntField = result;
  }
}

However, this isn't necessary. Turns out you can just set the field directly.

public class MyClass
{
  private int _parsedIntField;

  public MyClass(string strToParse)
  {
    if (!Int32.TryParse(strToParse, out _parsedIntField))
    {
      throw new ArgumentException("Please provide a valid numerical string.", nameof(strToParse));
    }
  }
}

Fast Builds: Make a Url Shortener with .NET

QuillCodes — Wed, 23 Sep 2020 15:43:44 +0000

Fast Prototyping and Learning to Code

Take a moment to think of your preferred way to learn a new language, framework, or skill. Most likely, there is a certain amount of value that you only get when learning by doing.

I had an interesting transition into development. I already knew a bit about how to code, but I had never had a programming job. At the time, I was working for a company where the dev department was willing to give me a chance, so they sent me an assignment. It was essentially a small file upload application, which I knew I could do.

The problem was that it had to be done in C#, and I had never used C# or .NET before. I had a couple nights to finish, but that had to be juggled around my current job. I tried on my own, failed, looked up docs, tried again, and shortly got to the point where I was writing code and trying to figure out the actual problem. I spent time searching for the right way to structure a class, run a build, and package up a functional project.

I got the job!

Fast forward, months later after I have been onboarded and gotten acquainted with some of the smaller dev tasks, I was sent to 'training'. There were dozens of us in a large classroom watching PowerPoint slides, listening to a lecture on proper syntax, and being given a list of 'patterns' to follow when writing our code.

It could not have been more unhelpful.

Sure, at some point during the class we were told we could write code, but overall we probably spent about three-quarters of our time listening rather than practicing.

I learned incredibly more in a couple frantic nights writing my file uploader than I did in 80 hours of carefully scripted classroom training.

Building a quick, useful app is an unbelievably useful tool when learning to code. Not only do you get to learn about the concepts employed in the app, you get to see results extremely quickly. There is a fantastic feedback loop that takes place when you get to see results.

In this tutorial we are going to focus on a fast prototype for a relatively simple service: a URL shortener.

Getting your Environment Ready

For this tutorial we have a couple tools that will be necessary.

.NET SDK
- Note: This tutorial uses some features from .NET 5, which is a Release Candidate as of this writing.
VS Code
C# Extension for VS Code

Building a URL Shortener

The plan today is to build a prototype URL shortener. While doing this we are going to explore and learn about a few concepts of .NET 5:

Setting up our project
Getting a basic webserver running requests
Serving some data using endpoint routing
Persisting our data in a simple no-frills database

Note: At this point I should emphasize that this is tutorial code and probably not ready for your full-scale production app. If you really just need a URL shortener there are many self-hosted options from which you can choose.

Setting up the Project

Our first step is to get our basic project files in place. Let's make a directory for our project and create a few files.

mkdir url-shortener-tutorial
cd url-shortener-tutorial

Within this directory we are going to create two files:

UrlShortener.csproj
Program.cs

The contents of the csproj file will be very simple:

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

This file tells .NET that we are going to be targeting .NET 5.0 and that we are going to use the Microsoft.NET.Sdk.Web SDK. This is basically the flavor of .NET that we plan on using. This might feel a bit opaque at first, but at its core this is really just a console application.

You can prove it to yourself just by adding two lines to Program.cs.

Program.cs

using System;

Console.WriteLine("Hello, World!");

And then running it with the dotnet command:

❯ dotnet run
Hello, World!

Running a Webserver

Now that we have a basic project set up and we can run code, our next step is to get a quick webserver up and running. This will let us respond to requests and start iterating on our solution.

Program.cs

using Microsoft.Extensions.Hosting;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Http;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(builder =>
    {
        builder.ConfigureServices(services =>
        {
            // Add the necessary components for HTTP routing.
            services.AddRouting();
        })
        .Configure(app =>
        {
            // Use routing in the pipeline.
            app.UseRouting();

            // Use the endpoint routing module to map URLs to functions.
            app.UseEndpoints((endpoints) =>
            {
                endpoints.MapGet("/", (ctx) =>
                {
                    return ctx.Response.WriteAsync("Hello, World!");
                });
            });
        });
    })
    .Build();

await host.RunAsync();

This setup is doing a few things for us:

1) It imports the necessary namespaces (think modules in JavaScript or Python) (see using statments) that we need to start serving HTTP requests.
2) It adds endpoint routing to our application's services.
3) It instructs our application to use endpoint routing to serve requests
4) It sets up a single route at our site's root "/" to return the text "Hello, World!".

We can now use the dotnet run command and visit our site in a browser to see some successful HTTP requests!

❯ dotnet run
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\src\url-shortener-tutorial

Serving a Simple HTML Interface

For this project, we only need a few components to properly interact with our URL shortener.

A simple HTML interface served at our site root ("/")
An HTTP POST endpoint that allows us to request a short link (we will use "/shorten")
A fallback HTTP endpoint that redirects all other requests to (for example "/bL92qf" -> https://www.google.com/")

To serve the HTML page we are going to take our existing "Hello, World" route and map to to a single file. First, we will add our index.html to the project. This can be in the same directory as Program.cs.

index.html

<!doctype html>
<html>

<head>
    <title>Simple URL Shortener</title>
    <link rel="stylesheet" href="https://unpkg.com/mvp.css">
</head>

<body>
    <main>
        <header>
            <h1>Simple URL Shortener</h1>
            <p>
                Enter your URL below to retrieve the shortened version.
            </p>
        </header>
        <section id="urlForm">
            <form enctype="application/x-www-form-urlencoded" method="POST" action="/shorten">
                <label for="url">
                    URL
                </label>
                <input type="url" name="url" />
                <button type="submit">Shorten</button>
            </form>
        </section>
    </main>
</body>

</html>

You will notice that we are just building a very basic form that will send a POST request to the "/shorten" route with a single field named url. We will have to add a little JavaScript later when we actually want to display our shortened link but for now this will suffice.

Note: You may notice a this stylesheet reference <link rel="stylesheet" href="https://unpkg.com/mvp.css"> at the top. This is a package called mvp.css by Andy Brewer and we are going to use it to give us some basic styling so we can focus on our code.

Then in our application we can instruct our endpoint to serve this file.

Program.cs

app.UseEndpoints((endpoints) =>
{
    endpoints.MapGet("/", (ctx) =>
    {
        // Serve root index.html
        return ctx.Response.SendFileAsync("index.html");
    });
});

We can now run the app again, go to our browser and see our base interface.

Time to Shorten Some Links!

Now that we have a basic interface, we can focus a bit more on our link shortening solution. For this we are going to create a new file in our directory and call is ShortLink.cs. Here we will define a new class which will hold some data and functionality for our links.

ShortLink.cs

using System;
using Microsoft.AspNetCore.WebUtilities;

public class ShortLink
{
    public string GetUrlChunk()
    {
        // Transform the "Id" property on this object into a short piece of text
        return WebEncoders.Base64UrlEncode(BitConverter.GetBytes(Id));
    }

    public static int GetId(string urlChunk)
    {
        // Reverse our short url text back into an interger Id
        return BitConverter.ToInt32(WebEncoders.Base64UrlDecode(urlChunk));
    }

    public int Id { get; set; }

    public string Url { get; set; }
}

Now we will use our ShortLink class to iterate on our endpoints and generate some fake URLs.

Program.cs - Add this to the `using` section

// Other using statements ...
using System.Threading.Tasks;

Program.cs - Modify your `UseEndpoints` call

app.UseEndpoints((endpoints) =>
{
    // Serve root index.html
    endpoints.MapGet("/", (ctx) =>
    {
        return ctx.Response.SendFileAsync("index.html");
    });

    endpoints.MapPost("/shorten", HandleShortenUrl);
});

Program.cs - Add to the end after `await host.RunAsync()`

// Endpoint Methods

static Task HandleShortenUrl(HttpContext context)
{
    // Perform basic form validation
    if (!context.Request.HasFormContentType || !context.Request.Form.ContainsKey("url"))
    {
        context.Response.StatusCode = StatusCodes.Status400BadRequest;
        return context.Response.WriteAsync("Cannot process request");
    }

    context.Request.Form.TryGetValue("url", out var formData);
    var requestedUrl = formData.ToString();

    // Test our URL
    if (!Uri.TryCreate(requestedUrl, UriKind.Absolute, out Uri result))
    {
        context.Response.StatusCode = StatusCodes.Status400BadRequest;
        return context.Response.WriteAsync("Could not understand URL.");
    }

    var url = result.ToString();

    // Temporary short link 
    var entry = new ShortLink
    {
        Id = 123_456_789,
        Url = url
    };

    var urlChunk = entry.GetUrlChunk();
    var responseUri = $"{context.Request.Scheme}://{context.Request.Host}/{urlChunk}";
    return context.Response.WriteAsync(responseUri);
}

There is a bit to unpack here, so let's go through it piece-by-piece.

We add an endpoint that receives a POST request to the "/shorten" path. This will accept the form input that we send from index.html
We map the endpoint to a method called HandleShortenUrl.
In the HandleShortenUrl method:
- We do some basic validation to ensure that we are getting HTML form data and that the form contains our url data in the request. If we do not get this information, we just write an HTTP error to the browser.
- We retrieve the URL value and use the built-in Uri.TryCreate method to validate that it parses into a usable URL. If this fails, we once again send an HTTP error to the browser.
- Create an instance of our ShortLink class and use the GetUrlChunk() method to construct our shortened link and write it back to the browser. We are hard-coding an Id for now so that we can test.

At this point, we should be able to run another test. Run the project, enter a valid URL into your form and you should see the URL in your response.

Test your form

Your test response

Congrats! You are successfully processing requests and returning data to your user. Next we will persist our generated short links to a database.

Persisting Your Short Links

Up to this point we have avoided adding dependencies to our project. For this section we have to change that by adding a database. We are going to use LiteDB, a simple, lightweight NoSQL database that will let us easily persist our short links to a file so they can be reitreved later.

Adding LiteDB to Your Project

When just using a text editor and not a full IDE, generally the easiest way to add a package is via the command line. Run the following command when in your project directory:

dotnet add package LiteDB

Functionally, this just edits your csproj file to add a Package Reference. Another option is to add the line to the project file yourself:

UrlShortener.csproj

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net5.0</TargetFramework>
  </PropertyGroup>
  <!-- Added Package Reference: -->
  <ItemGroup>
    <PackageReference Include="LiteDB" Version="5.0.9" />
  </ItemGroup>
</Project>

Now we can utilize LiteDB to persist our short links and serve them to users.

Persisting Data to LiteDB

We can now modify our Program.cs file to utilize LiteDB. To do this, the first thing we have to do is add LiteDB to our available services.

Program.cs

using LiteDB;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(builder =>
    {
        builder.ConfigureServices(services =>
        {
            // Add the necessary components for HTTP routing.
            services.AddRouting();

            // Add LiteDB
            services.AddSingleton<ILiteDatabase, LiteDatabase>(_ => new LiteDatabase("short-links.db"));
        })

This enables us to ask for the ILiteDatabase object in our request methods. ASP.NET will hold onto services for us and delivers them to us later in our program's execution. We can now go into our HandleShortenUrl method and use this service to insert our link.

Program.cs - Your HandleShortenUrl method

static Task HandleShortenUrl(HttpContext context)
{
    // Perform basic form validation
    if (!context.Request.HasFormContentType || !context.Request.Form.ContainsKey("url"))
    {
        context.Response.StatusCode = StatusCodes.Status400BadRequest;
        return context.Response.WriteAsync("Cannot process request");
    }

    context.Request.Form.TryGetValue("url", out var formData);
    var requestedUrl = formData.ToString();

    // Test our URL
    if (!Uri.TryCreate(requestedUrl, UriKind.Absolute, out Uri result))
    {
        context.Response.StatusCode = StatusCodes.Status400BadRequest;
        return context.Response.WriteAsync("Could not understand URL.");
    }

    var url = result.ToString();
    // Ask for LiteDB and persist a short link
    var liteDB = context.RequestServices.GetService<ILiteDatabase>();
    var links = liteDB.GetCollection<ShortLink>(BsonAutoId.Int32);

    // Temporary short link 
    var entry = new ShortLink
    {
        Url = url
    };

    // Insert our short-link
    links.Insert(entry);

    var urlChunk = entry.GetUrlChunk();
    var responseUri = $"{context.Request.Scheme}://{context.Request.Host}/{urlChunk}";
    return context.Response.WriteAsync(responseUri);
}

Now that we have registered our ILiteDatabase service, HandleShortenUrl is able to retrieve it using context.RequestServices.GetService<ILiteDatabase>(). From here we use the easy LiteDB API to get a ShortLink collection and Insert() it into our database. Finally, we use the same URL generation from before and send it back down to the browser.

Note: You may notice this reference to BsonAutoId.Int32. This simply tells LiteDB that this collection will use regular Integers for the Id field.

The last step to make this a 'complete product' (as in, redirect users to our short links) is to add a Fallback Route which will catch every other visitor to our app and serve up the expanded link.

We are now going to add another route method to our Program.cs file.

Program.cs - Add to `using` section

using System.Linq;

Program.cs - Add to UseEndpoints() Call

endpoints.MapFallback(HandleRedirect);

Program.cs - Add After `HandleShortenUrl`

static Task HandleRedirect(HttpContext context)
{
    var db = context.RequestServices.GetService<ILiteDatabase>();
    var collection = db.GetCollection<ShortLink>();

    var path = context.Request.Path.ToUriComponent().Trim('/');
    var id = ShortLink.GetId(path);
    var entry = collection.Find(p => p.Id == id).FirstOrDefault();

    if (entry != null)
        context.Response.Redirect(entry.Url);
    else
        context.Response.Redirect("/");

    return Task.CompletedTask;
}

In this block we are taking a few steps:

1) We set a default path where we will send people if we do not locate a short link for that path.
2) We parse our the path using data from context.Request.Path. We convert it to a string with ToUriComponent() and then Trim('/') to remove any extra slashes (the request will always come in with one initial slash).
3) We parse the URL back into an integer id using our ShortLink.GetId() method.
4) We find that id in the LiteDB collection.
5) We redirect to that URL if it exists, or to '/' if nothing was located.

When you run the app and visit a short link, you should redirect to the expanded version of the link.

Final Touches to Improve the Experience

Right now we are still just showing a plain-text url when someone requests a short link. Just a few small changes can allow us to provide a much cleaner user experience while keeping our small prototype form factor. First, we will modify our "/shorten" handler to redirect our user back to index.html with the shortened link. We will then modify index.html to display the link.

Program.cs - Bottom of HandleShortenUrl Method


var urlChunk = entry.GetUrlChunk();
var responseUri = $"{context.Request.Scheme}://{context.Request.Host}/{urlChunk}";
context.Response.Redirect($"/#{responseUri}");
return Task.CompletedTask;

That's it for Program.cs, we just replace the context.Response.WriteAsync() with context.Response.Redirect and we set the redirect URL to our root page with URL hash (#). Now with just a little bit of JavaScript we can add that URL to our page.

Index.html at the bottom of your <form>

<form enctype="application/x-www-form-urlencoded" method="POST" action="/shorten">
    <label for="url">
        URL
    </label>
    <input type="url" name="url" />
    <button type="submit">Shorten</button>
    <!-- A a place to put our resulting short link -->
    <p id="urlResult"></p>
</form>

Index.html right before the </body> tag

<!-- Add a script to grab the window's hash and display result -->
<script>
    let data = window.location.hash;
    if (data) {

        let url = new URL(data.substr(1));

        if (url.protocol === window.location.protocol
            && url.host === window.location.host) {
            let section = document.getElementById('urlResult');
            section.innerHTML = `<a id="link" href="${url}">${url}</a>`;
        }
    }

</script>

Now you can do your final run and test!

Quick Review and What's Next

I hope you enjoyed writing a quick prototype URL Shortener! We explored a few concepts in this post, and hopefully you learned a bit about how to write a minimal prototype with ASP.NET and .NET 5.

If you learned from creating this prototype, I would encourage your to experiment on your own and start filling in new features or refactoring it to a more 'production-ready' app. Here are a few suggestions based upon things you might want to learn:

Refactor the app to use the ASP.NET MVC (Model-View-Controller) pattern so that business logic and dependencies are better managed.
Refactor the app to use a remote database like MongoDB or SQL Server.
Right now putting the same URL twice will result in two separate short links. Maybe enhance the link creation logic to avoid duplicate URLs?

If you would be interested in a post that goes through any of these ideas, please Let me know!

You can also check out the full code for this solution on github.

Don't Fear the // Todo

QuillCodes — Thu, 17 Sep 2020 03:33:04 +0000

Did You Know?

Visual Studio tracks your "// TODO" comments so you can find them later.

From within Visual Studio Go to View -> Task List. This will display the Task List window and show you any area of your open Solution that has existing comments that start with // TODO. You can filter down to your Current Project, Current Document, or Open Documents. It even will allow you to search the list.

It doesn't just recognize // TODO, but will also recognize // HACK

What if I Don't Use English?

You can customize the words that trigger a Task View entry in your Visual Studio options.

Go to Tools
Go to Options
Expand the Environment options
Go to Task List
Enter any words you would like to highlight from your code comments.

How Should I Use It?

Properly leveraging the Task List window can be fantastic for your productivity. Here are a few of the ways I have personally used this window to improve my workflow.

Leaving occasional // TODO comments while prototyping when the unwritten code will not change functionality. It serves as a reminder to complete the code before delivering a milestone or making a final commit.
When writing a Web API, create the first round of CRUD endpoints using fake data and add // TODO to the top of every method. When all of the base endpoints are in there is now an easy checklist to complete.
Adding // CONSIDER to the list of words tracked by Visual Studio and using it to keep a list of places where long-term improvements can be made to a codebase. This can be set to a lower priority so that other tracked words stand out within the list.

Additional Links

Microsoft Task View Documentation

DEV Community: QuillCodes

Deep Dive on .NET Core String.Create() Performance

Definitions

How Does It Work?

How is String.Create Better?

Use Cases for String.Create()

Generating IDs

Execution Benchmarks

Memory Benchmarks

Performance-Sensitive Concatenation

Formatting of Complex Strings

Execution Time Benchmarks

Memory Benchmarks

When NOT To Use String.Create()

1) Do Not Use When Readability is Important

2) Do Not Use When Culture is Important

3) (Probably) Do Not Use When the Output is for Humans

Is String.Create() Right for You?

Simplify C# with Expression-Bodied Members

You Can Simplify Your Syntax

Simple Expression-bodied Members

Expression-bodied Members Can Help Reduce Boilerplate

Expression-Bodied Members Can be Used in Constructors

Set Class Fields Using 'out' Parameters

Did You Know?

You can set class fields with 'out' method parameters

Fast Builds: Make a Url Shortener with .NET

Fast Prototyping and Learning to Code

Getting your Environment Ready

Building a URL Shortener

Setting up the Project

Program.cs

Running a Webserver

Program.cs

Serving a Simple HTML Interface

index.html

Program.cs

Time to Shorten Some Links!

ShortLink.cs

Program.cs - Add this to the using section

Program.cs - Modify your UseEndpoints call

Program.cs - Add to the end after await host.RunAsync()

Test your form

Your test response

Persisting Your Short Links

Adding LiteDB to Your Project

UrlShortener.csproj

Persisting Data to LiteDB

Program.cs

Program.cs - Your HandleShortenUrl method

Program.cs - Add to using section

Program.cs - Add to UseEndpoints() Call

Program.cs - Add After HandleShortenUrl

Final Touches to Improve the Experience

Program.cs - Bottom of HandleShortenUrl Method

Index.html at the bottom of your <form>

Index.html right before the </body> tag

Quick Review and What's Next

Don't Fear the // Todo

Did You Know?

Visual Studio tracks your "// TODO" comments so you can find them later.

What if I Don't Use English?

How Should I Use It?

Additional Links

Program.cs - Add this to the `using` section

Program.cs - Modify your `UseEndpoints` call

Program.cs - Add to the end after `await host.RunAsync()`

Program.cs - Add to `using` section

Program.cs - Add After `HandleShortenUrl`