"You don't know you need it until you try it". Nowadays, almost everyone used computers since childhood, not excluding me.

Despite being an advanced Windows OS user, I wasn't having any idea that I might need it. I haven't asked myself the question "Maybe I need to remap FN keys to something else?" (not even once). But recently, I spilled water on my laptop's keyboard, and it stopped working. Then I started using a Bluetooth keyboard "Logitech Keys-To-Go", which I always have in my backpack. And this keyboard doesn't have FN keys at all. Instead, it has media keys, which cannot be configured as FN keys.

FN keys are often used in programming, and often it's important to see the number of FN key. For example, F5 is often used as "start debugging" key. But which keys to assign to this function to quickly find it when I need it? Obviously, below those media keys we have digit keys! Though, they only have numbers from 1 to 9, it's easy to assume that 0 is F10, "minus" is F11, and "equal" is F12.

The last thing to figure out is which modifier key to use? "Shift" isn't a good choice because it used to insert special characters; "control" and "alt" can be used in other key combinations, like Ctrl+F1. But what about "space"? Space is the easiest to press on any keyboard because of its location, so let's use it!

I can tell even more - when I started using it, I realized that it's even more convenient than the default FN1-FN12 keys on keyboards that have those keys. Because I often struggle finding a corresponding FN key when I need it - and press the wrong one. But I've noticed that when I use + as FN keys, I do less mistakes. I've get used to find those keys even without looking at them because I use them frequently. Now, even on a new laptop I use this remap instead of the original FN keys.

And here is the complete AutoHotkey configuration for such a mapping:

Space & 1::SendInput, {Blind}{F1}
Space & 2::SendInput, {Blind}{F2}
Space & 3::SendInput, {Blind}{F3}
Space & 4::SendInput, {Blind}{F4}
Space & 5::SendInput, {Blind}{F5}
Space & 6::SendInput, {Blind}{F6}
Space & 7::SendInput, {Blind}{F7}
Space & 8::SendInput, {Blind}{F8}
Space & 9::SendInput, {Blind}{F9}
Space & 0::SendInput, {Blind}{F10}
Space & -::SendInput, {Blind}{F11}
Space & =::SendInput, {Blind}{F12}
*Space::SendInput, {Blind}{Space}

Notice: "blind" is needed to trigger ALT+F4 or other key combinations, order is important: Space+Alt+4

For mac, you could probably achieve the same result using apps like Karabiner

That's it, happy coding!

The Question: How to Write a DRY Unit Test for Any Class With Any Complexity using xUnit?

Notice: this article doesn't pretend to be the holy grail and represents my personal opinion which is a result of many experiments on the subject

The Short Answer

Use custom BeforeAll class with hierarchical inheritance as xUnit class-fixture and nested classes for a test organization.

The Long Answer

The "Why" (Introduction)

In the past year, I switched from .NET/C# to TypeScript. It's dynamically-typed language (when it compiles to JS), meaning you spend less time dealing with strange compilation errors. Instead, you write your code, open the browser, and see the results almost immediately. Though,  a dynamic language has it's own benefits, as professionals we still have to write tests for our code. So, did I. I used Jest/Jasmine frameworks for testing TS/JS code, and it's fantastic. So far so good, until I've started another personal project. For it, I decided to write the logic using C#/.NET. And because I usually use TDD/BDD approaches during the development, it quickly became apparent that I miss the convenience of nested scenarios and steps from Jest/Jasmine.

Though in .NET there are BDD frameworks available - like SpecFlow, xBehave (and possibly more); but I wanted something simple to use with xUnit - with no other dependencies. xBehave depends on xUnit itself, but its repository is already archived. SpecFlow is great, but it seemed too cumbersome for a small project I was about to start. So the question arised: Can I use the same style with xUnit? And after a couple of experiments the "yes" answer appeared.

But before going further, here is a short list of requirements I kept in mind:

1. Do not introduce any attributes, reflection and other advanced concepts - keep it simple
2. Unit tests should be DRY - as less code duplication as possible
3. It should enforce a single assert per act
4. It should be open to code refactoring and modifications
5. Allow writing tests mechanically in a standardized way

The main advantage of Jasmine/Jest frameworks is that you can write tearUp/tearDown blocks which can be run before each and before all tests. Here are xUnit similar constructs:

1. beforeEach <-> class constructor
2. afterEach <-> class Disposable
3. beforeAll <-> IClassFixture

Despite having similar constructs in xUnit, Jasmine/Jest allows you to nest beforeEach/beforeAll blocks indefinitely, which allows you to reduce code duplication to a minimum. But can we achieve the same in C#/xUnit?

After experimenting, I've found a more or less satisfactory way of doing it. In C# similar results can be achieved using nested classes. I'll omit all experimental steps and show you the final result instead, after describing what I don't like in just having "Fact" inside a single test class.

"Soaking Wet" Tests - The Issue

So, coming back to C# again. I've started writing a new project in C# using BDD/TDD approach as I do normally.  But then I thought, can I write my tests in a similar way in C#?

Before that I used a special naming of test methods for xUnit:

[Fact]
void MethodUnderTest_TestCondition_ExpectedResult()
{
    ....
}

It looks some kind of OK, but a complex scenario similar to Jasmine/Jest will look like:

[Fact]
void HandleAppGlobalCommand_AndPayloadIsHandleEscapeButtonAndCloseOnEscapeEnabledAndSearchBarIsHiddenAndEditingIsNotStarted_ShouldCloseThePopup()
{
    ...
}

And it is already pretty hard to read and understand. Probably, for tests in such a style there would be a lot of code duplication. And soaking wet unit tests will probably have a negative effect on any product. Also, in such tests there is a huge amount of code duplication, which also can be hard to support.

So, how can it be improved? Using xUnit you can provide those arguments as InlineData attribute:

[Theory]
[InlineData(PayloadType.HandleEscapeButton, true, true, false, true)]
...
void HandleAppGlobalCommand(PayloadType payload, bool closeOnEscape, bool searchBarEnabled, bool editing started, bool expectClosePopup)
{
    ...
    Assert.Equal(expectedClosePopup, result);
}

It's much better, we now share the same scenario between multiple tests by parameterizing them. But then, what if I would like to test an invalid state of the method when something throws an exception in the middle?

If you put the entire test setup in this test method, then most likely you should duplicate this test method and rewrite the only last assert:

[Theory]
[InlineData(PayloadType.HandleEscapeButton, true, true, false, true)]
...
void HandleAppGlobalCommand(PayloadType payload, bool closeOnEscape, bool searchBarEnabled, bool editing started, Type expectedException)
{
    ...
    Exception exception = Record.Exception(() => act());
    Assert.Equal(expectedException, exception.GetType());
}

But it has other cons:

1. Sometimes it's cumbersome to parametrize such test methods using the "Theory" attribute.
2. Often, it requires a lot of mental energy because of the unique behaviour of classes under the test - meaning you can't write tests "mechanically".

Crispy DRY Tests - The Solution with an Example Code

Let's imagine that we are working on a game where the main hero is Mario. Nothing special except he can be possessed by the spirits of elders.

And those spirits from time to time can decide what Mario should do, and occasionally take control over Mario's body:

and this decision is made somewhere in the game's code by calling mario.DecideWhatToDo() method, which looks like this:

All this method does -it sets a new IDecision value we saw above to a private activeDecision property of the MarioPossessedHero class. This property is defined as:

Notice, this decision makes artificial intelligence, which looks like this:

The System Under Test (SUT)

Now, what we will do next - is to test how our hero jumps in different situations - to be more precise - when he possessed or not.

I'll skip the actual BDD process, and will show the final code for that method:

It's pretty straightforward, we can see, that depending on the AI decision our Mario sometimes can ignore a player's "jump" command.

And when it does not ignore it, it just calls this.bodyController.Jump() method which in turn controls the actual behaviour of Mario's body.

Here are how scenarios for the jump method may look like:

GIVEN Mario is possessed
WHEN a player presses "jump"
AND the artifitial intelligence has no control over Mario
THEN the Mario should jump

GIVEN Mario is possessed
WHEN a player presses "jump"
AND the artifitial intelligence has control over Mario 
THEN the Mario should not jump

GIVEN Mario is possessed
WHEN a player presses "jump"
AND the artifitial intelligence decision throws an error
THEN the Mario's "jump" method should also throw an error

I'll omit the complete test code - for simplicity, here is the code only for the first scenario; you can find the rest in the linked repository here:

public static class Jump
{
    public abstract class BeforeAll : Methods.BeforeAll
    {
        public Mock<IDecision> Decision { get; protected set; }
        public bool IsPlayerHasControl { get; protected set; }

        protected BeforeAll()
        {
            this.Decision = new Mock<IDecision>();
            this.Decision.SetupGet(x => x.IsPlayerHasControl).Returns(() => this.IsPlayerHasControl);
            this.ArtificialIntelligence!.Setup(x => x.NextDecision()).Returns(() => this.Decision.Object);
        }

        public override object? ActFunc()
        {
            this.Sut!.Jump();
            return null;
        }
    }

    public static class AfterAiMadeDecision
    {
        public abstract class BeforeAll : Jump.BeforeAll
        {
            protected BeforeAll()
            {
                this.Sut!.DecideWhatToDo(); // update the decision from AI
            }
        }

        public class PlayerHasControl : IClassFixture<PlayerHasControl.BeforeAll>
        {
            private readonly BeforeAll fixture;

            public class BeforeAll : AfterAiMadeDecision.BeforeAll
            {
                public BeforeAll()
                {
                    this.IsPlayerHasControl = true;
                    this.Act();
                }
            }

            public PlayerHasControl(BeforeAll fixture)
            {
                this.fixture = fixture;
            }

            [Fact]
            public void ShouldNotThrow()
            {
                Assert.Null(this.fixture.ActException);
            }

            [Fact]
            public void ShouldTriggerJumpForBodyController()
            {
                this.fixture.BodyController!.Verify(x => x.Jump(), Times.Once);
            }
        }
    }
}

Notice, how classes are nested and inherited - they use the following rules:

1. All classes that contain "BeforeAll" nested classes should be marked as static - their purpose is to logically separate test steps - similar to describe blocks in Jest/Jasmine.
   Static classes also protect from accidentally putting "Facts" into the wrong place - "Facts" should be put in non-static classes
2. All BeforeAll classes (fixtures) inside static container-classes
   1. should be marked as protected abstract - it protects them from the accidental instantiation of the wrong BeforeAll block inside xUnit class fixture
   2. the top-level BeforeAll classes for the method (e.g. inside public static class Jump) must override ActFunc - so the act is always the same for all tests
   3. non-top-level BeforeAll abstract classes should define intermediate spec steps (e.g. Jump.BeforeAll)
3. All BeforeAll classes inside non-static test classes
   1. should be marked as public (non-abstract) and also have a public constructor
   2. should call Act method inside the constructor as the last step
4. Non-static test classes
   1. Contain the actual "Facts" as well as the public non-abstract class BeforeAll which defines intermediate scenario steps
   2. Inherit from IClassFixture<T> and inject the fixture via constructor - it allows to run an "act" once for all asserts/facts
5. While inheriting from a parent BeforeAll fixture, use <ParentStaticClassName>.<BeforeAll> naming scheme to avoid ambiguity
   (e.g. BeforeAll : Jump.BeforeAll inside static AfterAiMadeDecision class)

Summary

And that's everything we need to cook crispy DRY tests in xUnit. Yammy, isn't it?

Notice, those steps aren't ambiguous, and there is almost no code duplication.

Pros:

1. No code duplication
2. Single assert per test
3. Minimal runtime overhead per assert (faster unit tests)
4. Goes nicely with refactoring
5. Unit tests are much cleaner and easier to understand

Cons:

1. A bit longer learning curve - certainly requires a shift in thinking about the structure of your tests
2. A bit harder to work with tricky inheritance - not a big deal when you understand what you are doing

Other notes:

1. Can "BeforeAll" be used to test static methods? Not without some thought and modification, but in my opinion, xUnit tests "as is" are already good for testing static methods in BDD style - using constructor and/or nested classes (no base class required).
2. Can it make your code better? No, if you do not follow best practices in software development, not a single unit test framework will help you.

P.S.: I was able to use this approach with more advanced/complex usage scenarios in integration tests, where each step involves intermediate asserts and setups. For such tests, I wrote a BeforeAllSequenceFixture which allows to have all the described above benefits for a sequence of steps. But I'll leave it for another article.

The repo containing full code for this article can be found here: psxvoid/crispy-dry-xunit-tests-article | github.com

In this blog post, you'll find a couple of useful AutoHotkey scripts to inspire, simplify and improve your daily tasks. It assumes you are already familiar with AutoHotkey. If not, then there are plenty of tutorials available on the internet, including an official one: AutoHotkey Beginner Tutorial.

Notice: AutoHotkey is only available for Windows OS.

Useful One-Liners

Let's start with easiest scripts that fit in one-line. My favourites in this list are "Hassle-free Re-mappings" because they allow to use a mouse and always have your left hand sit on top of AWSD keys. Other ones are also can be pretty useful when you have to navigate to a particular folder.

Open AppData/Roaming folder:

^#a::Run, %A_AppData%

Open AppData/Local folder:

^+#a::Run % StrReplace(A_AppData, "Roaming", "Local")

Open MyDocuments folder:

^#d::Run %A_MyDocuments%

Open Dropbox folder:

^+#d::Run, C:\Users\%A_UserName%\Dropbox

Hassle-free Re-mappings:

CapsLock & g::Send,{Enter}
CapsLock & f::Send,{Delete}
CapsLock & f::Send,{Backspace}

Tip: I recommend using it with this script:
Use Caps Lock for Hand-Friendly Text Navigation | LifeHacker

Toggle Slashes in the Clipboard

Script:

CapsLock & b::
replaceCount = 0
replacement := StrReplace(clipboard, "\", "/", replaceCount)

if replaceCount <= 0
{
    replacement := StrReplace(clipboard, "/", "\", replaceCount)
}

if replaceCount > 0
{
    clipboard := replacement
}

return

Example:

Copy this to clipboard:

C:\Program Files\AutoHotkey

Press "CapsLock + b". The content of the clipboard will be changed to:

C:/Program Files/AutoHotkey

Press the same hotkey again, and the content of the clipboard will be changed to:

C:\Program Files\AutoHotkey

Convert Windows Path to WSL Path And Wise Versa

Script:

CapsLock & w::

replaceCount = 0
wslPath := RegExReplace(clipboard, "^([a-zA-Z]):(.*)", "/mnt/$L1$2", replaceCount)

if replaceCount <= 0
{
    winPath := RegExReplace(clipboard, "^\/mnt\/([a-zA-Z])(.*)", "$U1:$2", replaceCount)

    if replaceCount >= 1
    {
        StringReplace, winPath, winPath, /, \, All
        clipboard := winPath
    }
}
else
{
    StringReplace, wslPath, wslPath, \, /, All
    clipboard := wslPath
}

return

Example 1:

Copy this to clipboard:

R:\Temp

Press CapsLock+w, this will change the content of the clipboard to:

/mnt/r/Temp

Example 2:

Copy this to clipboard:

/mnt/r/Temp

press CapsLock+w, this will be in the clipboard:

R:\Temp

Insert Date and Time (HS)

Script:

:*:]d::
FormatTime, CurrentDateTime,, dd.MM.yyyy HH:mm
SendInput %CurrentDateTime%
return

Example input:

]d

It will be replaced with:

28.01.2021 06:50

Insert UUID (GUID, HS)

Script:

:*:]uu::
newGuid := CreateUUID()
SendInput, %newGuid%
return

CreateUUID()
{
    VarSetCapacity(UUID, 16, 0)
    if (DllCall("rpcrt4.dll\UuidCreate", "ptr", &UUID) != 0)
        return (ErrorLevel := 1) & 0
    if (DllCall("rpcrt4.dll\UuidToString", "ptr", &UUID, "uint*", suuid) != 0)
        return (ErrorLevel := 2) & 0
    return StrGet(suuid), DllCall("rpcrt4.dll\RpcStringFree", "uint*", suuid)
}

Example input:

]uu

It will be replaced with:

1b1ae064-4d59-4a0a-b879-cdcbb0bc8c68

Notice, it's based on the following thread: GUID & UUID - AutoHotkey Community.

Wrap text from clipboard and paste (HS)

I use it to search a particular string in evernote intitle. But it might give you ideas for something more relevant. For example, you can wrap a piece of code, etc.

Script:

:*:]eint::
result := RegExReplace(clipboard, "(.*)", "intitle:""$1""",, 1)
SendInput %result%
return

Example:

Copy this to clipboard:

Blog Post

Enter the following string:

]eint

It will be replaced with:

intitle:"Blog Post"

Summary

This post doesn't pretend to be the most complete, but I hope it'll help you start with AutoHotkey a bit quicker. AutoHotkey gives you an easy way to add extra hotkeys to Windows OS, as well as useful "Hot Strings". And the best part - it's mature enough, that if you want to use it for something specific to you, most likely it's already available on the internet - you can find hundreds of scripts on GitHub, forums and blog posts. And if it's not, AutoHotkey has impressive documentation and a responsive user base eager to help.

This article shows everything C# program can contain. I mean it, EVERYTHING. After reading this article you'll understand what is possible in ANY C# program. And nobody will tell you that you are wrong. But be aware that the data presented here is based on the data, presented in Microsoft.CodeAnalysis.CSharp v3.9.0 NuGet package, which is RoslynAPI for C# language. And I will even dare to say that this NuGet package is the latest stable C# Language Specification. And after reading this article to the end, you should understand why.

Before We Go (Prerequisites)

You should already know what is SyntaxTree in RoslynAPI. For this, I recommend reading the official documentation that can be found here: Get started with syntax analysis (Roslyn APIs) | Microsoft Docs

Also, my previous article may help to grasp the core ideas of this one. It can be found here: C# RoslynAPI SyntaxTree - Variables Are Not Variables (Gotchas)

All syntax trees in examples have gotten by using SyntaxTreeVisualizer extension. And it's important to know, that this extension omits "Syntax" postfix for all syntax nodes. That is why when we see "StructDeclaration" we should read it as StructDeclarationSyntax which is a particular class inside Microsoft.CodeAnalysis.CSharp.Syntax namespace.

Let's consider the most basic C# language unit in RoslynAPI - CSharpSyntaxNode. Why is it the most basic? Because any C# Syntax Unit like a condition or statement, class or method is inherited from the CSharpSyntaxNode. For example, here is the inheritance chain for a class:

1. CSharpSyntaxNode
2. MemberDeclarationSyntax
3. BaseTypeDeclarationSyntax
4. TypeDeclarationSyntax
5. ClassDeclarationSyntax

Now, when we know where it all starts, we can dig deeper.

And when I say deeper I mean we should go down the inheritance chain of CSharpSyntaxNode. Why? Because if we know that any C# construct is represented by it, we can see all possible constructs in C#. So, our next steps are to see all public SyntaxNodes that the RoslynAPI exposes.

Going Down the Rabbit Hole

Be aware, the first level of the hierarchy contains quite a lot of information. But don't be discouraged by it, take a brief look and go on reading. So, here it is:

Here we can notice that all of those top-level classes are abstract and directly inherited from CSharpSyntaxNode. Except for the lower node. I grouped all directly derived from CSharpSyntaxNode sealed classes at the end of the tree and called them, well, "sealed". And it is the only one "group" in this list that doesn't exist in the Microsoft.CodeAnalysis.CSharp package. It contains all not abstract, sealed syntax nodes. We will take a look at them later.

ExpressionOrPatternSyntax

Let's start at the top where we can see abstract ExpressionOrPatternSyntax that also contains abstract ExpressionSyntax and PatternSyntax:

The ExpressionOrPatternSyntax does not have any direct children and can be considered as a "Type-Marker" or a shared container.

ExpressionSyntax

What is ExpressionSyntax? Have you ever seen a refactoring suggestion by Visual Studio, Resharper or Rider saying, "Use expression body for properties"?

So, EVERY single construct that you write after => and before ; (semicolon) is ExpressionSyntax. In this case it is this._nvim. There are so many types derived from it, so it deserves a separate article.

Notice 1: everything including => and ; is actually ArrowExpressionClauseSyntax which is pure container for expressions.

Notice 2: a property is not the only place where ExpressionSyntax can be found. For example, it can be used inside ExpressionStatementSyntax too.

The expression syntax has another abstract child types:

as well as non-abstract:

Once again, don't be overwhelmed. For now, this list is presented only to understand the scale.

To understand all quirks about C# syntax in RoslynAPI we should see at least one example of C# expressions. And the simplest one is BinaryExpressionSyntax. Everything it does is combines two other expressions:

and it's corresponding syntax tree:

We can notice a couple of important facts:

1. BinaryExpressionSyntax is ExpressionSyntax
2. As we will see later, IdentifierNameSyntax is also ExpressionSyntax. It means any ExpressionSyntax may contain other expressions as child nodes.

The second fact has a pretty handy consequence. It means that in C#, we can combine almost any expression with another expression. For example, we can nest one BinaryExpression into another BinaryExpression.

We can also see in the syntax visualizer that this node is "AddExpression". But it is not the name of the class that represents this node. When we select it in the syntax visualizer below the syntax tree, we can see the following:

It says that the actual type of the node is BinaryExpressionSyntax, but the kind is AddExpression.

From here we could also conclude:

1. The syntax visualizer is showing us the kind of a node instead of its type for some nodes.
2. The same types of syntax nodes can have different kinds.

For example, here are some possible kinds of a binary expression:

1. AddExpression
2. SubtractExpression
3. MultiplyExpression
4. DivideExpression
5. ModuloExpression

TypeSyntax

This child category of ExpressionSyntax contains any type that can be specified in expressions. It has two main sub-categories:

1. NameSyntax
2. Direct children of TypeSyntax

NameSyntax nodes and its children nodes represent names that can refer to any identifiable constructs like targets of invocations (e.g. a method name). We already saw an example of IdentifierNameSyntax above that belongs to this category.
Let's take a look at one more example of a NameSyntax - GenericNameSyntax. It's a part of the following ObjectCreatingExpressionSyntax:

and it's corresponding syntax tree:

Recap: every type derived from NameSyntax is:

1. ExpressionSyntax
2. TypeSyntax
3. NameSyntax

Direct children of TypeSyntax represent a reference to a specific type, used in expressions. For example, it's being used to specify a return type in any given method.

Let's see what is TypeSyntax by analyzing its direct child - ArrayTypeSyntax:

and here the syntax tree:

Recap: every child node of the ArrayType is both ExpresssionSyntax and TypeSyntax.

InstanceExpressionSyntax

The following abstract child of ExpressionSyntax is easy to understand. It contains only two sealed types:

ThisExpressionSyntax is simply any expression that uses this keyword. For example:

has the following expression tree:

And the BaseExpressionSyntax, as you might guess is used in every expression that accesses a base member. For example:

has the following syntax tree:

To summarize, this category contains nodes to access instance and base members. No more, no less.

AnonymouseFunctionExpressionSyntax

The following abstract child of ExpressionSyntax is AnonimouseFunctionExpressionSyntax:

If you know what anonymous functions and lambda expressions are, you can already be familiar with what members of this category do. In case you would like to see an example, here is SimpleLambdaExpressionSyntax:

and the corresponding syntax tree:

it consist of a lambda parameter and an expression body. Not quite simple, huh?

BaseObjectCreationExpressionSyntax

The following abstract child of ExpressionSyntax is BaseObjectCreatingExpressionSyntax:

and the corresponding syntax tree:

PatternSyntax

Now, we should already have a basic understanding of what ExpressionSyntax is in C#. But what about PatternSyntax? PatternSyntax nodes are responsible for, you guessed it, describing a pattern matching in C#.

It was introduced in C# 7.0. You can read more about it:
C# 8.0 - Pattern Matching in C# 8.0 | Microsoft Docs

And you can read about changes introduced to pattern matching in C# 9.0:
Pattern matching changes - C# 9.0 specification proposals | Microsoft Docs

Those syntax nodes should also be self-explanatory. The following example demonstrates the concept:

and the corresponding syntax tree:

In other words, a pattern matching "matches" objects that correspond to a specific pattern. You can think of it as regular expressions for C# objects.

StatementSyntax

I call this group of nodes "method body members":

Why "method body members"? Because those are the ONLY nodes that can be a direct child of a BlockSyntax of MethodDeclarationSyntax (and other types, inherited from BaseMethodDeclarationSyntax). That's it, anything that can be specified inside a method body is a statement. Of cause, until it's an expression-body, in which case, only expressions can be specified in there.

Interesting facts:

1. A method body cannot contain an expression. But it may contain the ExpressionStatementSyntax which can contain any expression.
2. Many loop and conditional statements consist of syntax nodes scattered around different syntax node categories. For example, if statement consists of IfStatementSyntax which has the following child nodes that can be accessed via properties: (1) condition (ExpressionSyntax), (2) statement (StatementSyntax which is actually BlockSyntax), (4, optional) ElseClauseSyntax (direct child of CSharpSyntaxNode)
3. Statements can contain nested statements via BlockSyntax, UsingStatementSyntax, LockStatementSyntax, CheckedStatementSyntax, etc.
4. BlockSyntax is a pure container for other statements.
5. Except ThrowStatementSyntax there is also ThrowExpressionSyntax (direct child of CSharpSyntaxNode)
6. Except SwitchStatementSyntax there is also SwitchExpressionSyntax
7. LabeledStatementSyntax is a parent for statements to which it applies (not a sibling).
8. Multiple semicolon statements separated by white space are considered as multiple EmptyStatementSyntax. For example ;; are two EmptyStatementSyntax nodes.
9. Else-If is actually a nested IfStatementSyntax inside ElseClauseSyntax. Strictly speaking, IfStatementSyntax cannot contain the else-if statement because there is no else-if syntax node in RoslynAPI.

Let's take a look at IfStatementSyntax:

and it's syntax tree:

So, statements are workhorses of methods. Here is what they can be.

Loop Statements:

1. for
2. ForEach
3. while
4. do ... while
5. break
6. continue

Condition Statements:

1. if
2. switch

Control-Flow Statements:

1. return
2. yield
3. try
4. throw
5. label
6. goto

Arithmetic:

1. checked
2. unchecked

Garbage Collection Statements:

1. fixed
2. using

Multithreading:

1. lock

Unmanaged Statements:

1. unsafe

Other:

1. Local Functions
2. Expressions (via ExpressionStatementSyntax)

Notice 1: Similarly to IfStatementSyntax, CatchStatementSyntax and FinallyStatementSyntax are not inherited from StatementSyntax. Instead, they are direct children of CSharpSyntaxNode. Why? Remember "method body members" alias? Most likely the Roslyn team did so because you can't specify catch or finally keywords directly in a method body. They are only valid as children of TryStatementSyntax.

Notice 2: There is may be a confusion between [statements and keywords in C# language] and [RoslynAPI syntax classes]. For example, a one can think that catch is a statement, after reading official C# documentation:

but in RoslynAPI there are no "catch" nor "try-catch" statements. As mentioned above in RoslynAPI "catch" is represented by CatchClauseSyntax which is not a child of ExpressionSyntax class. So, a one who uses RoslynAPI may think of CatchClauseSyntax as about a separate entity because it's a direct child of CSharpSyntaxNode. In any case, we can safely call a "catch" a keyword. Have you noticed a catch here?

Notice 3: There is no unchecked statement syntax node in RoslynAPI. unchecked is using CheckedStatementSyntax but it has UncheckedStatement kind.

Notice 4: Many statements have expression variant. For example, there is CheckedStatementSyntax and CheckedExpressionSyntax.

Here is another example to understand the difference between statements and expressions of a similar kind:

and it's corresponding syntax tree:

Notice: The kind of unchecked expression is UncheckedExpression

This separation is subtle and very important to understand. Because you can't use expressions (e.g. checked-expression) directly in a method body but you can use statements (e.g. checked-statement) there. Similarly, you can't use statements in expressions (e.g. checked-statement in a property's expression body) but you can use expressions there (e.g. checked-expression).

MemberDeclarationSyntax

This category unites classes, namespaces, enums, interfaces, fields, properties, methods, etc. Basically it contains everything that can have a member. For example, a class can have the following members:

1. Fields
2. Properties
3. Methods
4. Events
5. Indexers

RoslynAPI defines four main member categories (abstract):

as well as non-abstract sealed direct children:

As you can see there are constructs that are unique and doesn't have any other sub-types. Why? If we consider namespaces, then it's obvious that there is only one type of a namespace declaration. And if C# language design team decide to create another tricky kind of a namespace then the Roslyn team may introduce another base type.

We will see examples in the following sections.

TypeDeclarationSyntax

I would say those nodes are the heart of the C# language. Those ones represent central OOP features of the language, like classes:

Let's see how the most common TypeDeclarationSyntax looks like:

and it's syntax tree:

That's it, ClassDeclarationSyntax includes everything starting from access modifiers and ending with CloseBraceToken. Also, you may notice that those green specifiers in SyntaxVisualizer (like PublicKeyword) are actually syntax tokens and not syntax nodes.

BasePropertyDeclarationSyntax

This sub-category of MemberDeclarationSyntax should be self-explanatory:

Though this category is tiny, it can show a couple of sleeve tricks. As you'll see later, EventDeclarationSyntax is not the only possible construct related to an event declaration. In RoslynAPI there is also EventFieldDeclarationSyntax. Wait, isn't there is only one event keyword in C#? Well, in RoslynAPI a single keyword can be used in several syntax nodes. Here is an example:

and the corresponding syntax tree:

You can have noticed several nuances here:

1. The difference between EventFieldDeclarationSyntax and EventDeclarationSyntax is that EventDeclarationSyntax is both a property and an event, as well as it has a block body which is BlockSyntax. In contrast, EventFieldDeclarationSyntax is both a field (as you'll see later) and an event, as well as it does not have a body.
2. EventDeclarationSyntax has accessors which are AccessorDeclarationSyntax with syntax AddAccessorDeclaration and RemoveAccessorDeclaration kinds.

Here is a kind of AccessorDeclarationSyntax that uses "add" keyword:

Notice 2: AccessorDeclarationSyntax can have a block-body (BlockSyntax) or expression-body (ExpressionSyntax) but NOT both.

And here are properties:

and the syntax tree:

Properties are similar to events, but there are a couple of nuances too:

1. Similarly to EventDeclarationSyntax, PropertyDeclarationSyntax has accessors of type AccesorDeclarationSyntax but they have GetAccessorDeclaration and SetAccessorDeclaration kinds.
2. Similarly to EventDeclarationSyntax, PropertyDeclarationSyntax accessors can have both types of bodies - a block-body and an expression-body (but not both at the same time).
3. In case of a read-only property is omitted (set to null) but it has an expression-body.
4. In case of an auto property AccessorListSyntax is presented but it does not have any accessors.

Notice: Though, PropertyDeclarationSyntax can have an expression-body, EventDeclarationSyntax cannot.

Now, let's take a look at indexers:

and the corresponding syntax tree:

Indexers are similar to properties but there are a couple of nuances too.

1. Similarly to properties, indexers can be read-only or have block-body or expression-body accessors.
2. Indexers posses BracketedParameterListSyntax but PropertyDeclarationSyntax are not.

So, we've just taken a look at `BasePropertyDeclarationSyntax` nodes. Though properties, events and indexers are slightly different, they have a lot in common from the syntax point of view. Now, you can even brag to someone that events and indexers are actually properties because they share the same base class in RoslynAPI.

BaseMethodDeclarationSyntax

I will only show a single example for this group because those nodes are similar. They can have a block-body or an expression-body but not both. Here is an example of a method:

and its syntax tree:

Here what you may notice:

1. The main parts of a method are (1) `TypeParameterListSyntax`, (2) `IdentifierToken` - I haven't marked it on the screenshot but it contains the name of a method, (3) a method body (can be `BlockSyntax` or `ExpressionSyntax`), (4) `TypeParameterConstraintClauseSyntax`.
2. `TypeParameterListSyntax` is a container for `TypeParameterSyntax`
3. `ParameterListSyntax` is a container for `ParameterSyntax`

OperatorDeclarationSyntax and ConversionOperatorSyntax a bit different in a way, that the conversion operator is responsible for operator overloading and the operator declaration is responsible for implicit and explicit type conversion.

InterpolatedStringTextSyntax and InterpolationSyntax

Those are the parts of string interpolation feature in C#. Here is an example:

and the corresponding syntax tree:

VariableDesignationSyntax

Basically, it's like a variable declaration which is used to temporarily designate variables where you won't or can't declare a full variable:

You may already notice it in the examples above inside SimpleLambdaExpressionSyntax:

and here the corresponding syntax tree:

Have you noticed that little "u" character? Yep, this is VariableDesignationSyntax.

QueryClauseSyntax

I don't use query clauses at all in my code and prefer to use LINQ. But it's there, and C# team is carefully carrying it from release to release. I suppose it's there to introduce SQL-like queries. I won't describe each group in these categories. Feel free to explore it on your own.

You can read more about it here: Query expression basics (LINQ in C#) | Microsoft Docs

Here is an example from the Microsoft Docs (the link above) to continue the flow:

ArgumentListSyntax, ArgumentSyntax, ParameterListSyntax and ParameterSyntax

Those ones are closely related, though they do not share a base type. Those are also closely related to the following direct children of CSharpSyntaxTree:

Sealed, Parameters Related:

1. TypeParameterListSyntax
2. TypeParameterSyntax
3. FunctionPointerParameterListSyntax
4. TypeParameterConstraintClauseSyntax
5. CrefParameterSyntax

Sealed Arguments Releated:

1. AttributeArgumentListSyntax
2. AttributeArgumentSyntax
3. TypeArgumentListSyntax
4. ArgumentSyntax
5. OmittedTypeArgumentSyntax

This group is responsible for passing arguments to invocations. In other words, it answers the question "What should be passed to a function call as an argument?"

Notice: ArgumentSyntax does not have a base class, and it is a direct child of CSharpSyntaxNode. But ParameterSyntax has BaseParameterSyntax.

And very closely related to the arguments group is parameter group. It is responsible for defining parameters of functions. In other words, it answers the question "What a particular function can accept?" You can also think about it as about a "contract" between you and a function, meaning when you agree to a certain contract, you should comply with it when making calls to that function.

Here is an example that uses both an argument and a parameter in a single expression:

I hope, you can clearly see the difference between arguments and parameters here:

1. An argument is something that you passes during a method call (or while accessing something). In this example, you can see that we pass SimpleLambdaExpression as an argument to Where function invocation.
2. A parameter is something you define on the callee side (like a variable declaration). In this example, you can see that "x" is a parameter of the SimpleLambdaExpression. Also, in the example above you can see that ArgumentSyntax is contained inside ArgumentListSyntax. Similarly, parameters are contained in the ParameterListSyntax.

TypeParameterList and TypeParameter

Those are the base part of the generic types in C#. They allow you to specify a generic type for any type or method.

Notice: they are sealed, non-abstract and direct children of CSharpSyntaxNode.

Let's see an example:

and the syntax tree for the class:

and the syntax tree for a generic method parameter:

You may notice that TypeParameter is nested inside TypeParameterList. We need TypeParameterList because C# allows specifying multiple generic parameters for a type.

BaseListSyntax, BaseTypeSyntax and PrimaryConstructorBaseTypeSyntax

BaseListSyntax is the list of all base types for a specified type. It also a parent container for BaseTypeSyntax. Those are the core of C# inheritance. They allow us to specifies base types for a type we define.

Here we can see that the ClassMemberStateBase class is inherited from another LocalContextState class:

and here is how it's defined in the syntax tree:

Now, have you wondered what is PrimaryConstructorBaseTypeSyntax? It is also related to inheritance in C#. They apply only to C# 9.0, where records were introduced:

and it's syntax tree:

But what is even more interesting is that there is no separate syntax for a "primary constructor" in RoslynAPI, despite that you can specify PrimaryConstructorBaseTypeSyntax. Let's see a syntax tree for the R1 type:

Notice, the record does not have a "PrimaryConstructor" though RoslynAPI has PrimaryConstructorBaseTypeSyntax. Even Mads Torgersen mentioned the "primary constructor" in his blog post C# 9.0 on the record | .NET Blog in the comment:

I suppose, reusing ParameterListSyntax in RecordDeclarationSyntax just saved a couple of story points to the Roslyn team.

SwitchLabelSyntax

Those nodes represent a labels in C# language:

As you can see, there are three of them, each one specific to a context where it can be applied.

DirectiveTriviaSyntax

This group represents directives in C#:

StructuredTriviaSyntax and BranchingDirectiveTriviaSyntax

This groups represent different trivia constructs:

CrefSyntax, XmlNodeSyntax and XmlAttributeSyntax

Those are primarily used in XML comments and some of them can reference actual classes:

Direct Children of CSharpSyntaxNode

You've already seen a lot of nodes from this group. It contains different nodes that belong to other syntax groups but have no explicit relationships to those groups. Earlier, we seen that IfStatementSyntax has ElseClauseSyntax from this list. Also, we can find independent syntax nodes here. One of them is CompilationUnitSyntax. It is a node-container for all C# code that we define in a .cs file. I won't give additional examples for those, because this article has already become pretty long.

Conclusion

In this article, we've seen every single public syntax node that available in RolsynAPI. You may have noticed that there were not a single syntax node related to asynchronous programming (except AwaitExpressionSyntax) nor multi-threading (except lock statement). Have you wonder how is it even possible to see everything that possible in C# but not seeing any of those constructs (e.g. async/await)? It's because a programming language is just the way to describe things that a compiler can understand. When you invoke a function, all you have to know is the name of a function, arguments (a calling convention) and how to interpret the result. And it doesn't matter whether it's your personally crafted method or a System.Threading.Thread.Start - it's just a name that a compiler can understand. That is why RoslynAPI doesn't need some kind of "AsyncFunctionSyntaxNode".

Last but not least - RoslynAPI provides a consistent source of truth for naming C# language constructs. You may miss something while reading a textual language specification, but you can't miss a class like CSharpSyntaxNode. And you may be sure it is correct because (in case of RoslynAPI) it can parse any valid (and even not valid) C# source code.

I hope this article gave you a fresh perspective on C# language as well as a feeling of completeness. DotNet/C#/RoslynAPI teams did a great job of crafting the language till it reached its current state. People, that started their journey from C# v1.0, remember countless changes and improvements that were introduced during all those years. Nowadays, we can easily manipulate any C# source code by using RoslynAPI. But it was not always possible. So, I also hope, you'll appreciate RoslynAPI a bit more too.

P.S.: If you have any questions or suggestions feel free to contact me on twitter.

Have you ever wondered what is variable when you write your C# code in terms of syntax? Are you familiar with Roslyn API? If you are planning to create any developer tool for other C# developers, write Visual Studio Extension, or .NET Analyzer, then it's very likely you'll use Roslyn API. The goal of this article isn't cover all basic concepts but to gently introduce you to the world of the latest C# compiler platform.

Below are some questions that can help to verify your assumptions. If you know the answers, feel free to skip the article:

1. Do you know that event in C# is actually both a field and a variable from the syntax point of view?
2. Do you know that to get a local method's variable, you should NOT search for VariableDeclarationSyntax?
3. Do you know the difference between VariableDeclarationSyntax and VariableDeclaratorSyntax?
4. Are method arguments accept variables from the syntax point of view?

Prerequisites and tools

To demonstrate the concept of C# variables from the syntax point of view, I'll be using the "Roslyn Syntax Visualizer" tool for Visual Studio. You can find more about it here. It's a tool to browse the syntax tree of the active file in a project.

To get started with understanding SyntaxTrees, semantics, and the difference between both, I recommend reading the official documentation:

1. Work with syntax | Microsoft Docs
2. Work with semantics | Microsoft Docs

A syntax tree is a tree-like structure created by a compiler during compilation. It represents your code in terms of the SyntaxNode of different kinds, like classes, structs, variables, etc. A root node of the syntax tree is "CompilationUnitSyntax," which represents a file. So, your projects consist of multiple SyntaxTrees, each one representing a CompilationUnitSyntax/File. But it's not always true because you can create an entire program without having any files using RoslynAPI. Anyway, it should be enough to get to the point.

Variables are Not Variables

Exploring the fields

To start, let's consider the following class (you can skim it for now and return to it as you need):

Here we can see two private fields, defined in a single line in a class:

private int age, height;

Can you guess what kind of a syntax node it represents? Something related to variables, right? Not exactly.

A field in the C# syntax world is represented by the FieldDeclarationSyntax node. Below is the output of "Roslyn Code Visualizer" for this line of code:

You can see that it's not a variable. But it has child VariableDeclarationSyntax and VariableDeclaratorSyntax. But does it contain any names? Let's take a look at the properties of this node:

It doesn't seem so. Does the variable declaration contain it?

Another miss. Does VariableDeclaratorSyntax contain it? Almost. It contains IdentifierSyntax, which contains an actual name of the first field:

and another one of the second field:

Exploring the events

What are the events from the syntax point of view? Are those variables?

public event EventHandler<EventArgs> HappinessMaxout, SaddnessMaxout;

Let's take a look at the syntax tree. Here is EventFieldDeclarationSyntax:

Notice, it also contains VariableDeclarationSyntax node, containing multiple VariableDeclarator nodes.

So, answering question #1 at the top of the article - yes, from the syntax point of view, events are both fields and variables.

Exploring local variables

What are the local variables from the syntax point of view? Let's take a look at this line of code:

int mutation1, mutation2;

It also contains VariableDeclarationSyntax but it is LocalDeclarationSyntax:

Fields, Events, Methods Exploration Summary

What does all this mean? First of all, in terms of syntax, the term VariableDeclarationSyntax is ambiguous and can be part of:

1. Fields
2. Events
3. Method's/Expression Local Variables

Secondly, a field, event, and local variables in terms of the syntax are variables. But to be more precise, they contain VariableDeclarationSyntax and VariableDeclaratorSyntax

What is VariableDeclaratorSyntax and why do we need it?

You should already understand the difference between VariableDeclarationSyntax and VariableDeclaratorSyntax.

VariableDeclarationSyntax allows to define multiple variables on a single line:

int a, b;

or on multiple lines:

int a,
    b;

while each variable inside it is represented by VariableDeclaratorSyntax.

When we want to access the first variable name, we can't do it by just having VariableDeclarationSyntax, because it doesn't contain an IdentifierSyntax node (that contains the actual variable name).

But VariableDeclaratorSyntax does contain IdentifierSyntax node with name. Here is code to demonstrate the concept:

variableDeclarationNode.Variables[0].Identifier.TextValue == "a"; // true
variableDeclarationNode.Variables[1].Identifier.TextValue == "b"; // true

Where:

• Variable[0] = VariableDeclaratorSyntax
• Identifer = IdentifierSyntax
• TextValue = the actual name of a variable

Hopefully, it answers questions #2 and #3 at the top of the article.

ParameterSyntax vs ArgumentSyntax

We often use the words "parameter" and "argument" as synonyms. We can also say that we pass a variable to a method. But in RoslynAPI, those are different.

ParameterSyntax is used inside MethodDeclarationSyntax:

ArgumentSyntax is used inside InvocationExpressionSyntax (when calling methods):

and none of those contains VariableDeclarationSyntax, nor VariableDeclaratorSyntax.

So, answering question #4, we can call them "Variables", but can't say for sure that "a method can accept variables" in terms of C# syntax.

Summary

And that's it! To learn those concepts further along with other Roslyn APIs, I recommend writing a simple console application and exploring it with the "Roslyn Syntax Visualizer" extension in Visual Studio.

Also, to find a real-world example, you can check out my dngrep repo (.NET Global Tool) on GitHub. Thanks for reading!

Currently, there is a lot of hype around WSL and WSL 2 on Windows. It allows us to run almost any Linux application, including Docker. It even allows us to develop applications for Linux in VS Code using the "Remote - WSL" extension. But the goal of this article isn't to praise WSL but to show that there is a better way to use Docker on Windows.

Let's start from the beginning. Docker allows you to build and run Linux Containers (Windows too but we will not talk about it right now) in a very straightforward way - all you need is to put some build instruction in a docker-file, build the image using the "docker build" command and run the container using "docker run." But how does docker run a container on a Linux/Windows machine?

"The Docker on Linux" Way

When you use Docker on Linux, it simply uses native kernel features, like cgroups, to run the code inside the container. As the result, it's lightning-fast because it doesn't use any emulation (e.g. in contrast to Virtual Box).

"The Docker on Windows" Way, Part 1 - Hyper-V

When you use Docker Windows and it doesn't have WSL2 installed, the default backed is Hyper-V. After the installation, Docker asks you to activate it and reboot your machine. It is doing this because it uses Hyper-V to run a small virtual machine on it. Because there is no magic - you can't run Linux executables natively on Windows. Interestingly, If you use Virtual Box on the same machine then it may become slower or stop working at all. Because what happens when you activate Hyper-V - your copy of Windows became some kind of a Virtual Machine (the host OS) that also runs on top of the Hyper-V virtualization layer. And when your run Virtual Box it's somewhat similar to starting a VM inside another VM. It's not completely similar, because the latest versions of Virtual Box can use Hyper-V as their emulation backend. But be aware that in order to use it your machine should support Hardware Virtualization.

"The Docker on Windows Way", Part 2 - WSL2

The first time I heard about the possibility of running Docker on WSL2 I was happy as a child. Running without Hyper-V with performance, batter than the performance of WSL1, isn't it cool? Well, it would be cool if WSL2 didn't rely on virtualization technology. It requires you to enable the "Virtual Machine Platform" feature of the latest builds of Windows 10. And as far as I can understand it is similar to running under Hyper-V. So, no benefits here. Almost. But it may change in the future. For now, it seems more like a marketing trick. For now, it even has a bug that prevents docker from reclaiming the memory from WSL it. One day while I was working building images with Docker on WSL2 I noticed that the process was using more than 10BG of memory! But this feature is still in beta and hopefully become better over the years. So, how can you enable it? First of all, install and WSL2 as described in the official documentation here. Then tick the following checkbox in the docker settings:

"The Docker on Windows" Way, Part 3 - WSL1

There is also an option to run Docker on WSL1 using an older version (it won't work with the latest ones). All you have to do is to install that specific version inside any WSL1 distribution and start to use it. But then you became limited to that version, and when you run a container, it will always use around 30% of your CPU, even if the container is doing nothing. So, you can try it or even use it, especially if you have a powerful desktop PC. But it's certainly not the best way to use Docker on your laptop due to increased power consumption and overheating.

"The Docker on Windows" Way, Part 4 - Virtual Box

This way is primarily designed for those who don't have the hardware virtualization feature on their PC. All you have to do is to install Virtual Box on and then install a specific version of Docker called "Docker Toolbox." Docker Toolbox also uses a small virtual machine but instead of running it on Hyper-V (which requires the virtualization) uses Virtual Box. It has its limitations, but I love it because it provides some benefits even when you do have the hardware virtualization support. Why? Because, because then you can disable Hyper-V and all other Windows Virtualization Features. It will allow you to run Virtual Box at full speed and also make your system a bit more responsive. You can read more about it in the official Hyper-V documentation in the "limitations" section here.

"The Docker on Windows", The Better Way

This way is a bit unusual and may not be suited for everyone, but I'm suggesting you reading to the end because there is a good chance you'll love it as much as I do.

All options mentioned above can be pretty good, and some of them are official ways of running Docker on Windows. But what all those ways require you to modify your system, and sometimes it may be undesirable. For example, when you use Hyper-V it may make your system a bit unstable as described above. Also, when your run Docker Desktop, let's say, on your laptop, it uses its resources during builds and for running containers. Sometimes it can slow you down. Needless to say, that when you build containers locally, it may use quite a lot of system disk space, and you should keep an eye on the size of the local images because it can grow pretty quickly. Mine was around 100GB one day, and it took a couple of hours to understand why and how to clean it up. So, what is the better way?

It's "Docker on Raspberry Pi" way. Recently, I bought a Pi4, connected it to an external 2TB drive with USB 3, and configured a samba (Windows Share) service to expose it to the local network at home. I was tinkering with it, and, accidentally, decided to try to run a Minecraft server on it. I quickly build an image on my windows laptop with Docker Desktop on WSL2, pushed it to the Docker Hub, and tried to run it on the Raspberry Pi. But I quickly realized that it was failing with the following error:

As it turned out, Docker builds images with the same processor architecture under which it's being built. In the case of "Docker on Windows," the resulting architecture of an image is x86_64. In the case of Raspberry Pi 4 and Ubuntu (64 bit), it's aarch64. We can verify it by running the "uname -m" command on a Raspberry Pi:

The next step was to build the image on Raspberry Pi. Only then I realized that I should build images on the Raspberry Pi itself. I didn't use any git repositories for this quick project; and because my samba server had been already configured on my Windows laptop, all I have to do was to copy project files with the Dockerfile to a folder on the connected Network Drive (samba share).

So, I build the image once again on the Raspberry Pi. It succeeded, but then I've got a similar error. However, the error occurred not during a container startup, but on during Minecraft server startup:

Why a similar error? Didn't I build it with the required architecture? To completely understand this error, you should know that a Minecraft Bedrock Edition Server is only available for Linux with x86_64 architecture (64 bit). And I was downloading it during the image build using wget. The resulting architecture of the image was aarch64, but I was trying to run x86_64 executable on it. It's somewhat similar to trying to run a Visual Studio executable from Windows on the phone. The only way I found to make it work is to use an emulator. And so, my journey with Docker on Raspberry Pi and QEMU began. But I won't describe it here. The only thing I mention about it here is that I'd got it working, but it was to slow to use even for a single player. Because the goal of this article is to show you the beauty of working with "Docker on Raspberry Pi." Later that day, I opened the Visual Studio Code in the shared folder on the Raspberry Pi. And I was a similar (or even better) experience of running Visual Studio Code with the "Remote - WSL" extension. But because I was using Docker on a Raspberry Pi and connected to it via ssh, my laptop was using 0% CPUs during docker builds, its SSD was completely clean from temporary image layers, and all containers were running outside the main machine allowing it to be as responsive as possible.

Setting Up "Docker on Raspberry Pi"

Now, lets set it up from the beginning. First of all, we have to enable cgroups (it wasn't enabled by default on Ubuntu 20, x64 for me) by editing "cmdline.txt". We can open it in vim with:

sudo vim /boot/firmware/cmdline.txt

Next, we should append the following configuration to the first line (e.g. by pressing Shift+A and entering:

cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1

Save it and quit from vim by pressing :wq<Enter>. The next step is to reboot the Raspberry Pi to apply the changes:

sudo reboot

Now, we are ready to install docker:

sudo apt update
sudo apt upgrade
sudo snap refresh
sudo snap install docker

We can verify that it's correctly installed by running:

sudo docker run hello-world

The output should look something like this:

The next step is to enable samba service to access project files easily on a Windows machine:

sudo apt install samba

Let's say, we would like out code to live in ~/code (e.g. /home/ubuntu/code):

mkdir ~/code

In order to configure samba server on the Raspberry Pi and share ~/code folder we have to edit smb.conf file:

sudo vim /etc/samba/smb.conf

First of all, modify the "global" section. Mine looks like this:

and create a new share by appending it's configuration at the end of a file. It may look like this:

Notice, here we configured ubuntu as our user. But we can specify any user name here, not just ubuntu. Samba users are not the same as system users. For simplicity, we can even enable public access without a password by setting "public = yes." Save it and quit from vim. Now we should add our ubuntu-samba user and generate a password for it:

sudo smbpasswd -a ubuntu

To apply the changes, we should restart the samba service:

sudo service smbd restart

To verify that our service is working fine we can run the following command:

sudo systemctl status smbd

If it's active then we didn't mess with samba.conf and are ready to connect to the samba service from Windows. Notice, I'm assuming you are familiar with your network configuration. At this point, it would be almost essential to assign a static IP address to your Raspberry Pi on your router. I assigned 192.168.100.16 for mine. It will allow you to easily restore the network drive connection to Raspberry Pi each time your laptop is booted and connected to the local network.

All we have to do is to open the Windows Explorer and press the "Map Network Drive" button:

specify required options and press finish:

enter credentials for the ubuntu user (the ones you've added using smbpasswd):

and viola, now we can access our share from Windows as it was a regular drive:

From here we can clone any git repository using PowerShell, and then open it in Visual Studio Code. For example:

git clone https://github.com/docker-library/hello-world
cd hello-world
git reset --hard 9ef4804c28679a416a445397f9b2e2b105005151
code .

To verify it's working, open hello.c file, and add/modify any text you want. For example:

and remove those lines from Dockerfile.build (on the moment of writing this article those packages were unavailable on Raspberry Pi, Ubuntu 20, x64):

and delete all blocks that starts with "RUN set -ex" except this one:

and change CMD line from amd64 to arm64v8:

and save the changes. Then switch to the Raspberry Pi (I'm ssh-ing to it) and run the following commands:

cd ~/code/hello-world
sudo docker build -t hello:latest -f Dockerfile.build .
sudo docker run --rm hello:latest

And here is our modified message:

Isn't that cool? Now, you can work on your docker projects on a Windows machine without the need to have Docker installed.

Summary:

So, what is the "Docker on Raspberri Pi" way about? It's about isolating your personal/professional environment from the Docker itself, quickly iterating using shared folders on a Raspberry Pi filled with your project files and git repositories, and using your preferred code editor opened on your favorite machine. And it's about freedom of choice.

Pros:

1. It doesn't rely on Hyper-V, WSL2, or any other virtualization technology.
2. It doesn't take any memory and processing power on your main laptop.
3. You can easily bring it to your office.
4. No need to pay for a separate VM and compute resources.
5. Easy to use.

Cons:

1. Resulting images are compiled to aarch64 (arm64) architecture and can't be run on a laptop (unless you use buildx or an emulator).
2. Computing resources of Raspberry Pi are limited.
3. Some libraries may not be available on aarch64.
4. Relatively hard to configure.

Thanks for reading and happy coding.

This article is based on the official Visual Studio Code documentation: Developing in WSL | VS Code Docs but extends it with a practical example.

Introduction and The Context

Let's say, you found a project on GitHub (or it's your own) that has to be accessed from Linux (WSL) using VS Code. This guide shows you how.

For example, I'd like to use WSL for editing YAML files (kubernetes deployments) with NeoVim, and "kubectl" util for managing kubernetes clusters. The reason behind is simple - Linux provides a lot of utilities that can enhance your experience with kubectl (like xarg, awk) and you can use bash (or any other) scripting language for automating your deployments.

So, let's say we have the "deployments" folder inside the user's home directory on Ubuntu (WSL):

In that folder, we have three YAML files (they are taken from Run a Replicated Stateful Application - MySQL | kubernetes.io example):

So, the goal is to access those files in VS Code, make a change to one of them and see the diff for the change.

Prerequisites

To achieve what we want some prerequisites must be satisfied - those should be already installed and configured on your Windows OS:

1. Visual Studio Code (VS Code)
2. Windows Subsystem For Linux (WSL)

Overview

Here are the steps needed to access Linux folders outside WSL:

1. Install Remote Development extension for VS Code
2. In VS Code, Press Ctrl+Shift+P, start typing and choose "Remote-WSL: New Window"
3. Pick up a folder you'd like to open and press "OK"

Practical Example

Let's try to open our "~/deployments" folder. I'll skip the installation of the extension though. After pressing Ctrl+Shift+P inside VS Code and starting typing "Remote" we will see something like this:

Here we should select "Remote-WSL: New Window". After selecting, a new VS Code window will be opened and it should ask your permission for accessing the network (or may not, depending on your Windows configuration):

After giving access to the network, we will see a familiar VS Code welcome window:

Here we should open the "Explorer" panel and click "Open Folder" button (it also possible to just press "Open folder..." under the "Start" section):

After that you'll see a Drop-down menu with a list of folders inside your home folder on WSL:

Then start typing a folder you'd like to open (in our case it's "~/deployments") and select it from the list:

You'll see it populate the line with the requested path. The last step is to press the "OK" button:

And that's it! Now, you'll see all WSL files from the "deployments" folder in VS Code "Explorer" window as if they were opened in Windows:

From here you could do pretty anything you could do with a project inside a Windows folder: open command prompt and run commands, use source control, debug, etc. Let's finish this example by making a change into one file and see that "diff" view is working as expected:

Conclusion:

VS Code and the "WSL Remote Development" plugin are powerful tools that can greatly improve your coding productivity and support complex development scenarios by allowing you to work with Linux files on WSL as if they were a part of a Windows file system. It abstracts all implementation details and allows you to focus on what matters.

Side Note: Also, be aware that the "Remote Extension" is not limited to working with files on WSL. For example, it can also attach to kubernetes containers. Check out the Visual Studio Code Change Log v1.44: Remote Development and the extension's page for more use case scenarios. Happy coding!