Razor is a markup syntax for creating dynamic web pages in C#. It has been a part of the ASP.NET MVC framework since early 2011 and is currently a part of ASP.NET Core, serving as a templating engine for building web pages and components in MVC, Razor, and Blazor.

The primary idea behind Razor is to provide a simple syntax for generating HTML using a code-focused templating approach. The same approach can be seen in other popular frameworks and libraries focusing on HTML generation, such as React, Angular, Vue, etc. The described approach uses a hybrid of markup syntax (in this case, HTML) and a programming language (C# for Razor). It combines them during rendering to provide a hydrated and fully rendered web page or a page segment.

Let's get visual. Let's say we want to create a simple <div> with some populated data.

<div>
    <p><b>Name:</b> Denis</p>
    <p><b>Surname:</b> Ekart</p>
</div>

The same thing could be achieved in a .razor component in the following way.

<div>
    <p><b>Name:</b> @Name</p>
    <p><b>Surname:</b> @Surname</p>
</div>
}
@code {
    [Parameter]
    public string Name { get; set; } = "Denis"

    [Parameter]
    public string Surname { get; set; } = "Ekart"
}

The same HTML markup will be generated after the Razor templating engine renders this code. Only now we can provide the rendering engine with additional context (Name and Surname , in this case), which can render dynamic components based on the information provided. Now, scale this approach to the entire website, and you know how Razor works (in a nutshell 🥜).

Rendering web pages is cool and all, but this is not what we're here to do today. We want to (ab)use the Razor rendering engine to render HTML inside a console application.

Why? Well, first of all, because since .NET 8 onwards, we can. But more seriously, there are various use cases where rendering HTML can be used and useful outside of an HTTP request. Generating static website content, structuring rich email messages, and generating PDFs are just a few worthy mentions where templating comes in handy.

Since I've been dealing with a clunky HTML snippet, any time I send out a newsletter for our developer user group, let's convert that into a Razor template (and make my life a little easier).

Let's start

We are going to create an empty console application that's targeting .net8.

dotnet new console -n ConsoleRazorRenderer

If you have .net8 installed, the created ConsoleRazorRenderer.csproj will look something like this.

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net8.0</TargetFramework>
        ...
    </PropertyGroup>
</Project>

Great. Let's modify our project to allow us to include razor files. We will first need to change the project SDK to import the Razor-specific toolset. Open up the ConsoleRazorRenderer.csproj project file and change the <Project Sdk="Microsoft.NET.Sdk"> to Microsoft.NET.Sdk.Razor.

We will also need a couple of external dependencies.

dotnet add package Microsoft.AspNetCore.Components.Web will add the services needed to render the Razor components in our console application.

Additionally, we require dotnet add package Microsoft.Extensions.Logging since the rendering engine depends on the types defined in this package.

Our project file should now look like this.

<Project Sdk="Microsoft.NET.Sdk.Razor">
    <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
        ...
    </PropertyGroup>
    <ItemGroup>
        <PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="8.0.1"/>
        <PackageReference Include="Microsoft.Extensions.Logging" Version="8.0.0"/>
    </ItemGroup>
</Project>

Okay, It's smooth sailing from here. Let's add our NewsletterComponent.razor file to the project and fill it up with the newsletter HTML we've been using so far. Feel free to look at the HTML in the repository, but to get a general idea, this is what the final product should look like.

I'm really sorry for my mad drawing skillz.

We can Identify three variables that will change in any future newsletter version. The title, attached graphics, and the actual content of the newsletter. We can make these dynamic by parametrizing our components.

@code {
    [Parameter]
    public string? EventTitle { get; set; }
    [Parameter]
    public string? HeadingImageUrl { get; set; }
}

The interesting thing here is the actual content of the newsletter. It makes sense that the content of a newsletter will require rich text features (you know, emojis ✨, formatting, and other appealing features). Let's allow the component to accept any arbitrary HTML snippet as the Content.

Obviously, the renderer will not allow us to inject any arbitrary string and render it as HTML without escaping it. This is where the MarkupString comes in handy.

@code {
    [Parameter]
    public MarkupString? Content { get; set; }
}

It allows us to inject raw HTML markup into our components.

If we translate everything above into Razor, we can generate a component (or multiple components) that will look something like the following.

The wrapping component NewsletterComponent.razor will be used as a top-level component containing our styling, content, and graphics.

<!DOCTYPE HTML
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional //EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>SloDug Newsletter | @Content?.Title</title>

        <style type="text/css">
            ...
        </style>
    <body>
        <div>
            ...
            <NewsletterContentComponent Content="@Content?.Content" EventTitle="@Content?.Title" HeadingImageUrl="@Content?.HeadingImageUrl" />
        </div>
        <div>
            ...        
            <NewsletterTrailerComponent />
        </div>
    </body>
</html>

@code {
    public record NewsletterDto(string? Title, MarkupString? Content, string? HeadingImageUrl);

    [Parameter]
    public NewsletterDto? Content { get; set; }
}

NewsletterContentComponent.razor and NewsletterTrailerComponent.razor will hold dynamic content that will be rendered. While NewsletterTrailerComponent will wrap the static footer of our newsletter (not interesting), the NewsletterContentComponent will be used to format our dynamic content into HTML.

While there are numerous ways to structure the component hierarchy for any content, that's not the fun part of the article. Let's see how we can render our creation.

We will use the HtmlRenderer to output the generated HTML as a string.

Let's first define a rendering service, which will take the NewsletterDto we defined earlier and produce a rendered HTML string.

public class NewsletterRenderer(HtmlRenderer renderer)
{
    public async Task<string> RenderHtml(NewsletterComponent.NewsletterDto content)
    {
        var result = await renderer.Dispatcher.InvokeAsync(async () =>
        {
            var parameters = ParameterView.FromDictionary(new Dictionary<string, object?>
            {
                { "Content", content }
            });
            var output = await renderer.RenderComponentAsync<NewsletterComponent>(parameters);

            return output.ToHtmlString();
        });

        return result;
    }
}

The service will receive a HtmlRenderer injected into the constructor (check out C# 12 primary constructors). We invoke the renderer using its dispatcher to render the NewsletterComponent. All we need now is to supply the renderer with the dynamic content, so we will construct a ParameterView from the content the component expects - the "Content" parameter expects an object of type NewsletterDto.

The RenderComponentAsync method call will return a HtmlRootComponent , which contains the rendering result and has a handy ToHtmlString method. Now that we have our HTML output, we need to return it to the caller.

It's that simple. Now, let's put it all together. In the Program.cs entrypoint, we will create a ServiceCollection, add the necessary services, and build our DI container.

var provider = new ServiceCollection()
    .AddLogging()
    .AddTransient<HtmlRenderer>()
    .AddTransient<NewsletterRenderer>()
    .BuildServiceProvider();

Now that we have our service provider, we can resolve the renderer by calling

var renderer = provider.GetRequiredService<NewsletterRenderer>();

The only thing left is to define our content and render the HTML.

var content = new NewsletterComponent.NewsletterDto(
    Title: "Pre NTK - DevOps Edition",
    // language=html
    Content: new("""
                 (...)
                 <div>
                     🗓️ WHEN: Wednesday, January 17th 2024, at 6PM <br />
                     📍 WHERE: BTC City Ljubljana <br />
                     🔗 <a ...>Sign up here</a> <br />
                 </div>
                 (...)
                 """),
    HeadingImageUrl: "https://slodug.blob.core.windows.net/uploads/a9424857-0326-49a4-bbb0-b89ecb9a1038/SloDug_wide_empty.png");

var newsletterHtml = await renderer.RenderHtml(content);
// send the newsletter to subscribers (or something)

And that's it. We can now render dynamic content using the Razor rendering engine. This also allows us to reuse existing components we use throughout our web application, making things even easier.

Newsletter sent!

Don't forget to check out the repository for a complete sample.

✌️

The story so far

We have been calling ourselves self-proclaimed compiler development experts for a few weeks now. During this time, we managed to

• alienate our colleagues by creating this really cool analyzer that will completely block any and all development efforts if multiple subsequent empty lines are encountered in our codebase,

• enrage our boss by failing all of our builds and effectively shutting down our product development department, and

• making a savior move by providing the ability to automatically fix all errors caused by the original analyzer.

And here we are. Our mouse is hovering over the Merge button. We are seconds away from either becoming a hero to our company or being sued by the legal department. Suddenly we hear a voice in our head. A long-dead Greek philosopher is speaking to us.

Quality is not an act. It is a habit.

Oh man, our psychologist warned us about this.

We slowly move the pointer away from the button and take a second to regroup. We make a decision then and there. From now on, we will test before we ship!

Why test at all?

I will not spend too much time defending the various reasons why testing is beneficial in software development. A list of reasons (pros, if you will) usually includes

• ensuring the quality of the delivered product,

• reducing flaws and unexpected behavior in the software,

• making development easier and especially faster,

• ensuring the stability of the codebase and allowing developers to refactor code safely (or at least safer), and

• serving as living documentation, the kind that doesn't get outdated over time (at least in cases where tests are used as quality gates).

There are, of course, numerous resources available to you on the Wild Wild Web. For starters, navigate to the Microsoft Learn platform and find articles like this or that.

Testing Roslyn

I could have skipped the previous chapter and written a general article about testing instead. The thing is, Roslyn is a bit different. Roslyn is a compiler for all intents and purposes (well, for our purpose, at least). And you typically need a compiler to compile your code before you can test it. But we are testing the actions performed by the compiler. See the issue?

Okay, I'm exaggerating. Lucky for us, our compiler platform is entirely written C#. It is also open, extensible, and accessible enough to think of it as just any other .NET library. That being said, we need to be aware of some new concepts that testing a compiler will introduce.

Analyzers, code fixes, and other Roslyn extensions are typically encountered in projects. These reside in solutions open in various workspaces such as your Visual Studio IDE, JetBrains Rider, VS Code, or even the dotnet CLI. Finally, the actual diagnostic messages usually relate to a particular document in your project, such as the Program.cs application entry point.

To effectively test the compiler, we need to recreate all of these components, states, and actions for each of our unit tests.

Starting from scratch

Before we start, I want to assure you there are already several libraries and tools that can get you started with unit testing. If you are just looking for that initial push, jump to the next chapter where we go over the existing libraries used for testing.

If you are curious to learn how Roslyn works under the covers, this section will focus on building a straightforward and transparent means of testing Roslyn from the ground up.

Writing unit tests for our particular use case should be the same as what we usually do (and we do write unit tests, right?!).

Let's open up the analyzer solution we implemented in the previous articles and add a test project.

 dotnet new nunit -f net7.0 -n RoslynTests

Head over to our `RoslynTests.csproj` project file next and add a reference to our analyzer and code fix project. The project file should now look something like this.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsPackable>false</IsPackable>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\EmptyLinesAnalyzerAndCodeFix\EmptyLinesAnalyzerAndCodeFix.csproj" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.3.2" />
    <PackageReference Include="NUnit" Version="3.13.3" />
    <!-- ... -->
  </ItemGroup>
</Project>

We have an NUnit testing project ready to run. Of course, you could easily use some other testing framework, such as XUnit or MSTest.

All actions performed in this article are done using the CLI or directly implemented in the code. Depending on which IDE you use, there may be a more convenient way of achieving the same things. The CLI approach, at least, will guarantee that the actions performed will work regardless of the platform or IDE being used.

Next, we need a NuGet package that will enable us to build virtual solutions. And, of course, let's remember our trusty FluentAssertions package. Run the following scripts.

dotnet add RoslynTests package Microsoft.CodeAnalysis.CSharp.Features
dotnet add RoslynTests package FluentAssertions

Essentially, we are writing unit tests for how the compiler treats our source code. Let's start with wrapping some code in the SourceText abstraction available from Microsoft.CodeAnalysis.Text namespace.

var source = SourceText.From("""
            namespace DemoConsoleApp;


            /// <summary> </summary>            
            public class EmptyLines
            {
            }
            """);

For our benefit, we are using the raw string literal notation introduced with C# 11

Okay, so the source construct will be the unit we are testing. The first thing we need is to create a workspace.

Create a virtual workspace

As we learned in the first article of the series, the workspaces API acts as an entry point into our application. It exists to help us organize all the information about our source code. It ties everything into a neatly packed object model. It offers us direct access to the compiler layer and all the syntax and semantic information the compiler has. To put these words into a picture,

this is what we need to build. Only the entire workspace must exist for the short duration of running a single unit test.

When you see a solution like the one pictured above, it is usually built from a MSBuildWorkspace or one of its siblings such as VisualStudioWorkspace . While the used workspace type is generally specific to the workload or your development environment, these workspaces usually have at least one thing in common. They allow you, the developer, to point to a folder, a csproj, or a sln file and automatically load the entire workspace for you.

There is, however, another workspace AdhocWorkspace available in the NuGet package we installed just moments before. To quote the authors, it is "a workspace that allows full manipulation of projects and documents but does not persist changes". Perfect. This is precisely what we need to build our virtual workspace.

Let's start by creating a static class named RoslynTestExtensions and, in it, an extension method that will be responsible for creating the workspace. We are modeling a solution that will contain a single project. That project will include a single document, our source.

We will also need to provide our solution with some references. These allow us to access types and functionalities from external assemblies. Referencing System and System.Linq will do just fine for our use case.

private static readonly MetadataReference[] CommonReferences =
{
    MetadataReference.CreateFromFile(typeof(object).Assembly.Location),
    MetadataReference.CreateFromFile(typeof(Enumerable).Assembly.Location),
};

Let's also define a couple of default values. We know our solution will always contain a single project. This project will also have a single document containing our syntax.

private const string DefaultProjectName = "ProjectUnderTest.csproj";
private const string DefaultDocumentName = "SourceUnderTest.cs";

Now we have enough information to compile a simple workspace.

private static AdhocWorkspace CreateWorkspace(this SourceText source)
{
    var projectId = ProjectId.CreateNewId();
    var documentId = DocumentId.CreateNewId(projectId, DefaultDocumentName);

    var sourceTextLoader = TextLoader.From(
        TextAndVersion.Create(source, VersionStamp.Create()));
    var document = DocumentInfo
        .Create(documentId, DefaultDocumentName)
        .WithTextLoader(sourceTextLoader);

    var project = ProjectInfo.Create(
        id: projectId,
        version: VersionStamp.Create(),
        name: DefaultProjectName,
        assemblyName: DefaultProjectName,
        language: LanguageNames.CSharp)
        .WithCompilationOptions(new CSharpCompilationOptions(
            OutputKind.DynamicallyLinkedLibrary));

    var workspace = new AdhocWorkspace();
    var updatedSolution = workspace
        .CurrentSolution
        .AddProject(project)
        .AddMetadataReferences(projectId, CommonReferences)
        .AddDocument(document);

    workspace.TryApplyChanges(updatedSolution);

    return workspace;
}

A couple of things to note here.

• one: Our project will be compiled as a dynamically linked library. This allows us to not worry about the compilation failing when our source does not contain a valid static void Main(...) application entry point.

• and two: If you look closely at the code, you can also notice that our source code, document project, and solution appear immutable. Looking back to what we discussed in the first article of the series, most of the basic Roslyn building blocks are, in fact, immutable. With one exception. A workspace provides access to all of the abovementioned building blocks. It is designed to change over time by supporting live interactions from the environment or via a call to the workspace.TryApplyChanges(updatedSolution).

Find the diagnostic

Now that we have a solution, we can manipulate it and attempt to produce an analyzer diagnostic we are trying to test. Starting from the source text, we can create another extension method.

The extension method will return a collection of diagnostics in the source code. More specifically, only the diagnostics that the analyzer TAnalyzer is reporting. Using the standard Roslyn APIs, that is quite easy to achieve.

static async Task<ImmutableArray<Diagnostic>> GetDiagnostics<TAnalyzer>(this SourceText source) where TAnalyzer : DiagnosticAnalyzer, new()
{
    var workspace = source.CreateWorkspace();
    var document = /*the default document*/
    var analyzer = new TAnalyzer();
    var diagnosticDescriptor = analyzer.SupportedDiagnostics.Single();
    var compilation = await /*the default project*/.GetCompilationWithAnalyzerAsync(analyzer);
    var allDiagnostics = await compilation.GetAllDiagnosticsAsync();

    return allDiagnostics.Where(x => 
            x.Id == diagnosticDescriptor.Id &&
            x.Location.SourceTree?.FilePath == document.Name)
        .ToImmutableArray();
}

I will let you fill in the blanks. Feel free to check the roslyn-playground repository (link at the end of this article) if you get stuck anywhere.

We can now finally create a simple unit test to wrap everything up.

[Test]
public async Task EmptyLinesAnalyzer_ShouldReportDiagnostic_WhenMultipleEmptyLinesExist()
{
    // Arrange
    var source = /*we know this already*/

    // Act
    var actual = await source.GetDiagnostics<EmptyLinesAnalyzer>();

    // Assert
    actual.ShouldContainDiagnosticWithId("DM0001");
}

Ahh, one bit is missing. Let's create another extension method ShouldContainDiagnosticWithId . It should receive an ImmutableArray of Diagnostics, and properly assert the existence of a diagnostic with a provided Id.

static void ShouldContainDiagnosticWithId(this ImmutableArray<Diagnostic> diagnostics, string diagnosticId)
{
    diagnostics.Should().NotBeNull().And.HaveCountGreaterOrEqualTo(1);
    diagnostics.Should().Contain(diagnostic => diagnostic.Id == diagnosticId);
}

✅ Let's move on!

Apply the code fix

We can use a similar approach for testing our code fix. Since we know our diagnostic contains an accompanying code fix, it gives us a perfect place to start modifying the virtual solution.

Similarly to what we did when testing the diagnostic in the previous chapter, we need to find the diagnostic to fix. Let's assume we are left with a singleDiagnostic that was reported by the analyzer under test. Because we checked that the diagnostic has the correct id, we also know that our TCodeFixProvider supports a code action to fix it.

I suppose we are making way too many assumptions at this point. Naturally, our code will have proper validation in place so that nothing will be left to chance 😉.

static async Task<SourceText> ApplyCodeFixes<TAnalyzer, TCodeFixProvider>(this SourceText source) 
where TAnalyzer : DiagnosticAnalyzer, new() 
where TCodeFixProvider : CodeFixProvider, new()
{
    // create the workspace, find the diagnostic, and ...
    await workspace.ApplyCodeFix<TCodeFixProvider>(document, singleDiagnostic);

     return /*the modified source*/
}

The only thing left to do is to implement the ApplyCodeFix<TCodeFixProvider> extension method.

If you remember the article where we implemented the code fix provider, we needed to implement the CodeFixProvider abstract class. As a part of that implementation, we implemented the RegisterCodeFixesAsync(CodeFixContext) method. This will be our access point to the code fix provider.

We can surely create an instance of the CodeFixContext since we have all the needed building blocks. A point of interest for us is the registerCodeFix argument. This delegate gets invoked whenever the code fix encounters a fixable diagnostic. As a result, we are left with a CodeAction.

This is something we are already familiar with. Remember, a code action contains all the information needed to apply the fix to our solution. This is achieved through the set of operations it exposes. Calling codeAction.GetOperationsAsync will enable us to access the ApplyChangesOperation, which will contain a ChangedSolution . This is the fix we need. The only thing left is to apply that changed solution to our workspace.

💡I, for one, love it when things start falling into place.

Let's type this up real quick.

static async Task ApplyCodeFix<TCodeFixProvider>(this AdhocWorkspace workspace, Document document, Diagnostic singleDiagnostic)
where TCodeFixProvider : CodeFixProvider, new()
{
    var codeFixProvider = new TCodeFixProvider();
    List<CodeAction> actions = new();
    var context = new CodeFixContext(document,
        singleDiagnostic,
        (a, _) => actions.Add(a),
        CancellationToken.None);
    await codeFixProvider.RegisterCodeFixesAsync(context);
    foreach (var codeAction in actions)
    {
        var operations = await codeAction.GetOperationsAsync(CancellationToken.None);
        if (operations.IsDefaultOrEmpty)
        {
            continue;
        }

        var changedSolution = operations.OfType<ApplyChangesOperation>().Single().ChangedSolution;
        workspace.TryApplyChanges(changedSolution);
    }
}

Again, we have everything we need in place to finally write the unit test. The following snippet is self-explanatory.

[Test]
public async Task EmptyLinesCodeFix_ShouldApplyFix_WhenMultipleEmptyLinesExist()
{
    // Arrange
    var source = SourceText.From("""
        namespace DemoConsoleApp;


        public class EmptyLines
        { }
        """);
    var expected = SourceText.From("""
        namespace DemoConsoleApp;

        public class EmptyLines
        { }
        """);

    // Act
    var actual = await source.ApplyCodeFixes<EmptyLinesAnalyzer, EmptyLinesCodeFix>();

    // Assert
    actual.ShouldBeEqualTo(expected);
}

✅ Pass. We are done.

Well, not quite. As mentioned, the approach we just implemented was meant to demonstrate how Roslyn works and should not be considered a valid approach to test your analyzers and code fixes (please). Let's look at how testing should actually be attempted.

Using Roslyn's testing library

Luckily for us, we can skip the previous chapter altogether. The team behind Roslyn provides a comprehensive suite of utilities designed to test analyzers, code fixes, and other components.

Getting started here is easy. Make sure you install the library first.

dotnet add RoslynTests package Microsoft.CodeAnalysis.CSharp.CodeFix.Testing.NUnit

Keep in mind that similar packages also exist for XUnit and MSTest.

The only thing we are left with is to use a verifier for the code fix we want to test. We can be tricky here and create an alias for the verifier.

using EmptyLinesAnalyzerAndFix;
using Microsoft.CodeAnalysis.Text;

namespace RoslynTests;

using Verify = Microsoft.CodeAnalysis.CSharp.Testing.NUnit.CodeFixVerifier<EmptyLinesAnalyzer, EmptyLinesCodeFix>;

public class EmptyLinesTests
{
    // ...
}

The previous test can now be rewritten to use the CodeFixVerifier like so.

[Test]
public async Task EmptyLinesCodeFix_ShouldApplyFix_WhenMultipleEmptyLinesExist()
{
    // Arrange
    var source = /*...*/
    var expected = /*...*/
    var diagnostic = Verify.Diagnostic()
        .WithSpan(startLine: 2, startColumn: 1, endLine: 4, endColumn: 1)
        .WithSpan(startLine: 4, startColumn: 1, endLine: 4, endColumn: 7);

    // Assert
    await Verify.VerifyCodeFixAsync(source, diagnostic, expected);
}

Two things to note. The Verify alias already knows the diagnostic we are testing. The only thing we are left with is to define where the diagnostic is supposed to occur. The WithSpan extension, along with numerous other extensions, can be used to specify the constraints of the diagnostic we are testing.

That's all good, but aren't we supposed to get a single diagnostic in this test? Why are we specifying two locations, then?

Looking back at the article where we implemented the analyzer, we added an additionalLocation that was later used by the code fix provider. This is the second span we want to test for.

Calling the Verify.VerifyCodeFixAsync will cycle over numerous verifications that will generally go over the same steps we went over in the previous chapter. Only the verifications executed here are far more precise and elaborate. The documentation in the Roslyn repository is a great entry point if you wish to explore the numerous capabilities of the testing library further.

We intentionally skipped testing the analyzer, since the library also provides the same assertions when testing an accompanying code fix provider. General guidelines and best practices for using the Roslyn test library suggest testing only the code fix provider when possible.

If this is not possible, you can freely use the AnalyzerVerifier from the Analyzer NuGet package, to test the analyzer on its own.

But wait, there's more.

Streamline testing using the Roslyn testing library

There are various cool and somewhat undocumented features included in this testing library. A couple of them, at least, can significantly streamline your test development.

The testing library supports a special markup syntax to aid in your test development.

Let's take the test of our code fix provider (the one above). Instead of explicitly creating a Diagnostic() with expected spans, we can embed that information into the source code.

var source = """
    namespace DemoConsoleApp;
    {|DM0001:

    |}public class EmptyLines
    { }
    """;

Notice the {|DM0001: ... |} markup, which tells the verifier that there is an expected diagnostic with the id DM0001 supposed to appear in the same position as denoted by the brackets.

The assertion part can, therefore, also be simplified since the diagnostic was implicitly created for us by the library.

await Verify.VerifyCodeFixAsync(source, expected);

We can use similar syntax to specify the location of any reported diagnostic using an alternative bracket markup [| ... |] .

[Test]
public async Task EmptyLinesAnalyzer_ShouldReportDiagnostic_WhenMultipleEmptyLinesExist_UsingRoslynLibraryCustomSyntax()
{
    // Arrange
    var source = """
        namespace DemoConsoleApp;
        [|

        |]public class EmptyLines
        { }
        """;

    // Assert
    await Verify.VerifyAnalyzerAsync(source);
}

Pretty cool, right?! Now replace the above markup with a marker $$ that specifies the expected location of a diagnostic. We have another passing test ✅.

var source = """
    namespace DemoConsoleApp;
    $$

    public class EmptyLines
    { }
    """;

In summary

We managed to get our hands dirty with Roslyn's workspaces. This API gave us enough insight into code analysis in C#. Additionally, we learned how to properly and easily test our inventions.

If you made it this far, head over to the denisekart/exploring-roslyn repository and start exploring⭐.

... As the sun is starting to rise, we glance at our updated merge request. Soothing green light from the generated code coverage report shines blissfully in our eyes. As we move our mouse closer to the Merge button, we wonder. What other secrets lie beneath this compiler's shining API?

Until next time, ✌

Storytime!

A week ago, we had a brilliant idea to implement an analyzer that would fail the entire build whenever multiple empty lines were encountered in our solution. Of course, someone made you push the code we implemented into production (hey, don't look at me). It just so happens that your company, CoolCorp, has ground to a halt because of that.

You get called into a web meeting titled "Fw: URGENT Who the hell broke our builds?!!". You enter the chat unbeknownst to the amount of trouble your Roslyn learning journey has caused the company. Your tech lead is bisecting the git history in front of senior management, trying to find the commit that broke everything. Ahh, here it is feat: disallow multiple subsequent empty lines (that will teach them).

The commit author, you, is now known to everyone. As you unmute your mic, you angle your web camera slightly to the right to reveal the famous quote from a guy that has something to do with faces, or books, or lizards.

You speak up with confidence: I can fix it!

Enter code fixes

Roslyn allows you to write a code fix provider, that can enable the IDE to calculate a change to the solution that would fix the reported diagnostic. Let's break this down.

An analyzer will report a diagnostic with a unique id (e.g. DM0001). A code fix provider can register a code action capable of providing a fix for the issue from that diagnostic. This means that any time there is an error, warning, or even an informational squiggle in your IDE, chances are there is an accompanying code fix that can make that squiggle go away.

The code fix provider will take the existing solution, make the necessary syntax changes, and return a new, fixed solution.

Side note; you must follow several rules when implementing analyzers or code fixes for Roslyn. The diagnostic id needs to be unique across all analyzers and be in a specified format, must not be null, must have the correct category, ...

When developing a for Roslyn, there are several helpful analyzers and code fixes to aid in the development.

Writing a code fix provider

Starting with our existing analyzer project EmptyLinesAnalyzerAndCodeFix.csproj, let's create a new class and call it EmptyLinesCodeFix.

Before doing anything else, we need another NuGet package to help us manipulate common workspace items such as Documents. Head over to the CLI and run the following command.

dotnet add EmptyLinesAnalyzerAndCodeFix package Microsoft.CodeAnalysis.Workspaces.Common

With proper dependencies installed, the class can derive from Microsoft.CodeAnalysis.CodeFixes.CodeFixProvider abstract class. For the IDE to recognize that this is a code fix provider, we must also decorate it with an ExportCodeFixProviderAttribute. This is what a barebones code fix provider should look like.

using System;
using System.Collections.Immutable;
using System.Composition;
using System.Threading.Tasks;
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CodeFixes;

namespace EmptyLinesAnalyzerAndFix;

[ExportCodeFixProvider(LanguageNames.CSharp, Name = nameof(EmptyLinesCodeFix)), Shared]
public class EmptyLinesCodeFix : CodeFixProvider
{

    public override Task RegisterCodeFixesAsync(CodeFixContext context)
    {
        // ...
    }

    public override ImmutableArray<string> FixableDiagnosticIds { get; }
}

If you are keen on exploring GitHub and you run across any code fix provider in the Roslyn repository, you might notice it is also decorated by a [Shared] attribute. The reason for that is code fix providers are MEF components. As per Roslyn guidelines, they should also be stateless. This means an IDE using a particular code fix provider can optimize its usage by creating a single shared instance of said code fix provider.

Link the code fix to the analyzer

We first need is to provide our code fix provider with a list of diagnostics it can fix. Since we are only fixing our diagnostics and we also conveniently remembered to expose the DiagnosticId constant in the EmptyLinesAnalyzer, we can use it here.

public override ImmutableArray<string> FixableDiagnosticIds => ImmutableArray.Create(EmptyLinesAnalyzer.DiagnosticId);

This will ensure that any time the referenced diagnostic is encountered, this code fix provider will be able to fix it.

To be fair, our implementation can't fix anything yet. For this to happen, we also need to register a code action. A code action describes an intent to change one or more documents in a solution. Simply put, a code action allows the host (e.g. an IDE), to display a light bulb 💡, which enables you to apply a code fix.

For JetBrains Rider users, there is an annoying limitation feature in the IDE that allows you to apply a code fix only to a particular occurrence. Visual Studio, for example, will display several additional options for fixing your code and previewing the code fix.

Enable fixing multiple diagnostics

For the code fix provider to be able to fix multiple occurrences simultaneously, we also need to provide a "smart" way to achieve this. Luckily, Roslyn already offers a built-in solution for fixing batches of diagnostics in a single go (just be mindful of its limitations).

public override FixAllProvider GetFixAllProvider() => WellKnownFixAllProviders.BatchFixer;

Register the code fix

To enable the compiler to see and the IDE to display our code fix action, we need to (hint hint) implement the RegisterCodeFixesAsync method.

public override Task RegisterCodeFixesAsync(CodeFixContext context)
{
    const string action = "Remove redundant empty lines";

    var diagnostic = context.Diagnostics.First();
    context.RegisterCodeFix(
        CodeAction.Create(
            title: action,
            createChangedDocument: cancellationToken => /*...*/,
            equivalenceKey: action),
        diagnostic);

    return Task.CompletedTask;
}

The text specified in the title will be displayed when the user hovers over the light bulb. "Remove redundant empty lines" will also be used as an equivalenceKey. This means that by fixing multiple occurrences of this diagnostic (say, by executing the code action over the entire solution), all diagnostics with the same equivalence key will be fixed.

With all that ceremony out of the way, we are left with the final piece of the puzzle. To fix the code, we need to provide a factory that will be invoked by the compiler once the change is necessary. The createChangedDocument parameter takes a delegate. When invoked, this delegate will receive a cancellation token provided by the compiler and return a document or solution that was modified by our code fix provider.

The code fix provider needs to utilize the received cancellationToken properly. The compiler may, at any time, cancel the operation. For the IDE to remain responsive, any extensions to the compiler (e.g. our code fix provider) should react to cancellation requests immediately.

private static async Task<Document> RemoveEmptyLines(Document document,
    Diagnostic diagnostic,
    CancellationToken cancellationToken)
{
    // ...
}

Implement the code fix provider logic

We now have all the information available to fix our diagnostic. The document defines the syntax tree we will be modifying. It also represents the document where the diagnostic is located. The cancellationToken, as mentioned, should be passed to any time-consuming operations (or we could just cancellationToken.ThrowIfCancellationRequested(); when doing any CPU-bound work in our code).

And now, the fun part, let's figure out how to change the document to fix the diagnostic. 👨‍💻

What? No. No peeking! Alright, I will include a link to the demo repository at the end of this article.

If you are adamant about trying to solve this yourself, here are a couple of tips to help you on the way.

• Similarly to the previous article, we only need to deal with the syntax tree. This means that we can skip semantic analysis altogether and focus on a single document source code,

• referencing the analyzer we implemented in the previous article, we were smart enough to include an additionalLocation which is a good place to start looking for the part of the syntax tree that needs to change,

• remember, Roslyn syntax trees are immutable. There are several benefits to this. Although for us, this means that any time we need to change a node in that tree, it needs to be rebuilt from the ground up.

Let's see how our implemented solution works in the demo console app.

Great! We are done. Ship it. Now.

But wait, let's take a step back this time. Let's imagine not hearing Mark Zuckerberg uttering the words that decorate our office walls.

Let's be sane this time around and test our code instead of our boss's patience.

As promised, here is a link to the denisekart/exploring-roslyn repository, where you can find all the samples from this series. We will explore various ways of testing Roslyn analyzers and code fixes in the next installment.

Until next time, ✌

The last article ended with the words, "let's write some code." While I'm all for writing code, perhaps some purpose is needed first. One of the goals of an open compiler platform is, for sure, the ability to extend and modify it to solve your problems. I have problems (yikes!).

First, define the problem

While this makes complete sense when written by a stranger on a blog post, it is always good to be reminded that to solve a problem, you must first know what the problem is (duh, get on with it already).

Let's say you get employed at a cool, trending company with a product wholly written in the latest flavor of C#. It's your first day on the job with your brand new 14" Mac, and a colleague gives you a link to the codebase you will be working on. You Set everything up, open up your favorite code editor, and load Program.cs . You see this.

// this is the entrypoint to the CoolCorp application



var builder = WebApplication.CreateBuilder(args);




// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();




var app = builder.Build();

// Configure the HTTP request pipeline.

And then the screen ends. There is no more vertical space on your brand-new MacBook. It has been completely eaten up by empty lines and, gulp, whitespace!

Now, just forget about the handy scrolling capabilities of that state-of-the-art haptic feedback trackpad thingy. You hate that you can only see 4 relevant lines of code on your screen. It hurts, and you want to... No, you need to fix it now!

The goal is to quickly turn the above monster into something more concise, clean, and structured, like so.

// this is the entrypoint to the CoolCorp application

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
}

app.UseStaticFiles();

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Bonus, you wish to punish the people writing such code, so you also want to make sure the build fails if there are multiple sequential empty lines anywhere in the solution.

Great, we have a problem to solve. To be entirely honest, you could just browse the Roslyn documentation and find the diagnostic with ID IDE2000. Then set the severity to error and grab a cold beverage with one of your normal non-developer friends who don't enjoy torturing themselves with coding abstractions at 3 AM on Saturday.

No? No! Let's dive in!

Set up the environment - take one

There are several ways to start developing Roslyn extensions. A straightforward way to start is to open up your latest Visual Studio 2022, find the Analyzer with Code Fix (.NET Standard) template, and dive into it.

Of course, you must ensure that you have installed the necessary workloads first (hint, hint Visual Studio extension development workload with the optional .NET Compiler Platform SDK ☑ component).

Once you create a project, you are greeted with an example analyzer and code fix, including the NuGet or a VSIX Visual Studio extension boilerplate code.

Project setup, as well as the means of distribution, are all essential things to consider, but we will dive into that topic at a later time. Right now, we need to get up and running ASAP. Your boss is watching, and the haptic feedback trackpad is about to give. To get up and running fast, we are going to start from scratch, literally (I know, I know... bear with me).

Set up the environment - take two

Okay, let's start with an empty solution. I'll let you figure out the best way to create it. My preference is always dotnet new sln.

Create a basic console application

While waiting on your Mac to load the entire CoolCorp solution, let's create a simple demo console app dotnet new console -n DemoConsoleApp. We will use this console application to quickly get feedback on our analyzer (no, you shouldn't use a console application to test your work).

Side note; if you are new to dotnet and are still not impressed by the advances made in the last couple of years, just run dotnet run --project DemoConsoleApp, and you have a working console application ready to run in a single step. Mind you, the only file in the project has a single line of syntax written in it.

Hello, World!

Create the analyzer project outline

Create a new class library project and name it something cool like NewLinesAreRelevantSyntaxTooAnalyzer.csproj (or don't, please). Roslyn components should target the netstandard2.0 TFM to ensure that analyzers load in various runtimes available today (mono, .NET Framework, and .NET Core).

Since we are already adding new functionalities to our solution, let's reference the packages needed to create an analyzer.

dotnet new classlib -f netstandard2.0 --langVersion latest -n EmptyLinesAnalyzerAndCodeFix
dotnet add EmptyLinesAnalyzerAndCodeFix package Microsoft.CodeAnalysis.CSharp
dotnet add EmptyLinesAnalyzerAndCodeFix package Microsoft.CodeAnalysis.Analyzers

If everything worked out, the structure of the solution should look like this.

There is now only a single piece of the puzzle missing. We need to reference the analyzer in our DemoConsoleApp.

To do that, open the DemoConsoleApp.csproj, and create an <ItemGroup> that adds a project reference to the analyzer. The file should look something like this.

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net7.0</TargetFramework>
    </PropertyGroup>

    <ItemGroup>
        <ProjectReference Include="..\EmptyLinesAnalyzerAndCodeFix\EmptyLinesAnalyzerAndCodeFix.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false" PrivateAssets="All"/>
    </ItemGroup>
</Project>

What we just did was referenced our analyzer from the console project. We then instructed the compiler that the referenced project should be used as a part of the project analysis. Additionally, we told the compiler that our console application will not be referencing the outputs of the analyzer (but we still need it to be built beforehand). If you wish to learn about other specifics of referencing projects, have a look at common MSBuild project items and how to control dependency assets.

We just achieved the ability to consume the analyzer from the same solution that the analyzer is being developed in (just hit rebuild - and read up on the wonders of MEF parts and dynamic recomposition if you ever need to reload the solution and have no idea why).

Let's take the analyzer for a spin!

A basic diagnostic analyzer

Head over to our analyzer class library and create a new class named EmptyLinesAnalyzer.cs. There are a couple of namespaces we will be using. Make sure that the following are included.

using System.Collections.Immutable;
using System.Diagnostics.CodeAnalysis;
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.Diagnostics;

Since we are positive we have no idea what VisualBasic even looks like, we will add an attribute specifying that the created class will be a [DiagnosticAnalyzer(LanguageNames.CSharp)].

Next, we need is to describe what the diagnostic we are producing will report. We need to instantiate a very simple DiagnosticDescriptor (the one from the Microsoft.CodeAnalysis namespace) to report the relevant information to the developer using our analyzer.

// ...
[DiagnosticAnalyzer(LanguageNames.CSharp)]
public class EmptyLinesAnalyzer : DiagnosticAnalyzer
{
    internal const string DiagnosticId = "DM0001";
    private static readonly DiagnosticDescriptor Rule = new DiagnosticDescriptor(
        id: DiagnosticId,
        title: "I work!",
        messageFormat: "I Work!",
        category: "Design",
        defaultSeverity: DiagnosticSeverity.Error,
        isEnabledByDefault: true,
        description: "I work!");

    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics
        => ImmutableArray.Create(Rule);

    public override void Initialize(AnalysisContext context)
    {
        //...
    }
}

If you recall from the first post in this series, analyzers can interact with several stages of compilation. Our use case will involve only syntax analysis. The diagnostics, however, will always point to a location in the analyzed syntax.

I would invite you to read up on syntax analysis, but for now, just imagine our console application has a single syntax tree (the contents of Program.cs ). That tree represents every keyword, variable, expression, comment, and every other character within this file.

Each token in that syntax tree has a span. The character index at which the node begins and its length. The most simple job of an analyzer is to find the location of a code issue (the hard part) and report it to the compiler (the easy part).

Let's do the easy part first.

public override void Initialize(AnalysisContext context)
{
    context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
    context.RegisterSyntaxTreeAction(context =>
    {
        var location = Location.Create(context.Tree, TextSpan.FromBounds(0, context.Tree.Length));
        var diagnostic = Diagnostic.Create(Rule, location);
        context.ReportDiagnostic(diagnostic);
    });
}

We just instructed the compiler to report an error for any syntax tree encountered and that the error should span the entire document.

Side note; you would not believe how many autogenerated files exist in a single-line console application. AssemblyInfo, AssemblyAttributes, GlobalUsings, you name it. We can ensure this code is not analyzed by setting the GeneratedCodeAnalysisFlags to None.

Okay, if all the semicolons are in place, rebuilding the solution will most certainly produce an error.

Now try to remember the last time you were happy that your code didn't work?!

Anyway, we have a real problem to solve now...

Implement empty lines analyzer logic

Since solving this problem was not intended to be a part of the article (what?!), I will try to leave you with some hints on how to attempt this yourself. If, however, you feel like the extra tinker time is not worth it, I will include a link to a fully working analyzer at the bottom (don't you dare touch that haptic feedback trackpad now!).

To try and solve this problem, we first need to know what parts of the syntax tree the empty lines usually occur. The fastest way to see this is by inspecting the syntax tree of the program code. There is handy tooling already available that allows you to traverse a live syntax tree either in Visual Studio, Rider, or even online.

Most of the empty lines are a part of syntax trivia. Trivia is a special kind of token found in the syntax tree. It contains syntactically insignificant parts of your code, such as comments, preprocessing directives, whitespaces, and, bingo, new lines.

One way to start is to traverse all leaf tokens in a syntax tree. Once a token with leading trivia is encountered, we need to verify if it is structured so that it contains multiple subsequent empty lines. If found, we need to report the location to the compiler (and we already know how to do that).

Side note; we should define what multiple empty lines truly mean. Are these just sequential \n characters? How about platform-specific line terminators such as \r\n ? Do we ignore the whitespace and \t characters between new lines?

One way we could implement the above solution is to analyze each observed syntax tree in the following way.

private void Recurse(SyntaxTreeAnalysisContext context, SyntaxNode node)
{
    foreach (var nodeOrToken in node.ChildNodesAndTokens())
    {
        if (nodeOrToken.IsNode)
            Recurse(context, nodeOrToken.AsNode());
        else if (nodeOrToken.IsToken)
            AnalyzeToken(context, nodeOrToken.AsToken());
    }
}

private void AnalyzeToken(SyntaxTreeAnalysisContext context, SyntaxToken token)
{
    if (!token.HasLeadingTrivia)
        return;
    // ...
}

After finding and reporting all locations at which multiple subsequent empty lines occur, the analyzer will ensure that the compilation process encounters an exception and report the diagnostic we created.

One more thing

You might notice that your IDE will begin to issue warnings that a project containing analyzers or source generators should specify the property <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>. The compiler platform comes equipped with a plethora of analyzers intended to help with developing and extending the Roslyn compiler.

When the abovementioned property is set in your EmptyLinesAnalyzerAndCodeFix.csproj, these analyzers start analyzing your analyzer and offer valuable guidance on properly handling common scenarios when developing for Roslyn.

To sum up

If you managed to follow through to the end, you should have a working analyzer that does a couple of really interesting things.

• It is capable of identifying locations that are basically empty space,

• it can fail the build when such locations are found within your codebase and offer information on where to find them, and

• is fully equipped to annoy your coworkers to no avail.

That may present a challenge but worry not. In the following article, we will create an accompanying code fix that can fix issues reported by our empty lines analyzer.

And, as promised, check out the denisekart/exploring-roslyn repository, where you can find all the samples from this article (and more).

Until next time, ✌

(This series is a work in progress. I will update the article with relevant links as I progress through the series)

• Episode 1: Exploring Roslyn .NET Compiler Platform SDK (this article)

• Episode 2: Getting Started With Roslyn Analyzers

• Episode 3: Fixing Mistakes With Roslyn Code Fixes

• Episode 4: (soon)

What is Roslyn anyway? Okay, let me just... CTRL+C, CTRL+V

.NET Compiler Platform, also known by its codename Roslyn, is a set of open-source compilers and code analysis APIs for C# and Visual Basic languages from Microsoft.

Clear, concise. That makes sense, right? But wait, there's more. To better understand Roslyn, we need to go back to its inception (well, we don't, but why not). Here is a brief replay of the events that lead up to all the fun stuff I'm about to describe in this series.

A (very) brief history of Roslyn

• On December 2010, Eric Lippert posted an article, Hiring for Roslyn announcing a major re-architecture of the C# compiler (and VB compiler too).

• At a 2014 Build conference, Microsoft made the Roslyn project open-source under the stewardship of the newly founded .NET Foundation. Roslyn gets shipped with VisualStudio 2015.

• In 2015, C# 6 gets released with several prominent language features, which somewhat hides the fact, that the C# compiler (and VB compiler too) has been completely rewritten in C# (and VB too), making this year a significant milestone for the language.

Compiler as a service

The .NET compiler SDK consists of several layers of APIs, allowing you to effectively integrate into the compilation process, starting at the parsing phase and ending in the emit phase.

The Compiler API surface allows you to access the information exposed by the compiler at each stage of the compilation process.

As a part of the compilation process, the compiler may produce diagnostics of varying severity that may be purely informational or expose a compilation error. The Diagnostic API allows you to integrate into the pipeline naturally. It enables you to produce a set of custom diagnostic messages or even provide the ability to execute code fixes.

Scripting API allows you to execute various code snippets effectively, enabling you to use C# as a scripting language. The C# interactive (Read-Evaluate-Print-Loop) is one tool that utilizes this API.

Of course, modern C# tooling allows you to perform various types of code analysis and refactoring jobs. These are all possible because the Workspaces API provides a virtual, well, workspace making it possible to format code across projects, find type references and even generate source code.

Okay, now I have a bunch of APIs to which I somehow have access. Any idea what to do with them?

Analyze code and report diagnostics

Roslyn allows you to inject components that interact with the compilation process and can ultimately emit diagnostics. These diagnostics can have varying severities and can be used to inform the developer of non-significant compilation events (missing comment on a public member) or can halt the compilation process entirely (missing semicolon at the end of a statement).

This allows you to tailor the entire compilation process to your project needs and standards. While writing custom code analysis tools may be a good exercise, there is already a vast ecosystem of Roslyn analyzers that might fit your needs. These can be installed as IDE extensions or injected into your project as standard NuGet package dependencies.

Provide code fixes

As it turns out, nagging about things without having the ability to fix them is pretty useless(a life lesson right here). For that reason, Roslyn allows you to define a code fix corresponding to a diagnostic.

Code fixes can be applied manually through editor actions or automatically be applied using a tool such as dotnet format (so many tools).

Rewrite existing code

There are various reasons why you would want to rewrite your code. Perhaps a method has become too complex. Possibly you can improve the code readability by hiding away some implementation details (e.g. writing declarative code). Whichever reason you may have to refactor your solutions - manually doing so can be tedious work.

Roslyn allows you to plug in a refactoring solution that can analyze your syntax to provide intelligent means of automatically refactoring code.

Generate source code

Have you heard of the saying the best code is no code at all? It turns out source code is evil. It has bugs. It rots over time. It requires maintenance. It needs engineers to write it.

Wait, what am I saying? I'm an engineer. I love writing code, though not all code. There is code I am always hesitant to start writing. Not because it's hard but because it's solving the same problem I have solved numerous times before.

Roslyn allows you to automate this too. You can use create a source generator that can automatically analyze relevant parts of your solution to spit out code without you typing a single syntax token (well, apart from writing the actual source generator).

Before we proceed

Just a fair warning. The tools described in this article integrate perfectly with Microsoft VisualStudio IDE and will work on any updated version of VisualStudio 2022 (and above). That being said, the Roslyn Compiler Platform is a part of the mentioned IDE, meaning that the utilities described in this series of articles will (with minor exceptions) work in any IDE that supports modern .NET and will even work without an IDE(dotnet CLI).

All examples in these articles were developed using .NET 7, VisualStudio 2022 Community Edition, and JetBrains Rider.

Let's write some code!