Building And Debugging The dotnet new Templating Engine In Visual Studio

Recently the folks at Microsoft have blessed us with a brand new Template Engine, of which is invoked by the dotnet new command in the .NET Core command-line interface (CLI). With it comes the ability to create and scaffold templates that will suit just about any need you have. Be it the desire to template a new project or a simple sub-section of a larger project, the Template Engine has you covered.

Those who are going to want to contribute to the Template Engine project or are simply interested in having the latest development features available to them, are going to need to understand how to work directly with the Template Engine code. That being said, I recently have gone through the pain of early adoption and have managed to figure out how to build and debug the code with some help and guidance coming directly from the Microsoft team responsible for this project. Following I will outline the steps needed to so such using Visual Studio.

Getting The Code

As noted above, the Template Engine's official repository lives on GitHub. Depending on your intentions, you are going to want to do one of two things.

  1. If you plan on contributing to the codebase, you will want to fork the repository to your own account and clone directly from there.
  2. If you are simply looking to produce a build of the latest code, you can clone directly from the Template Engine repository.

It is worth noting that the current "default" branch is the working development branch. The "master" branch is the build branch and it does not accept contributions directly.

Building & Running

Now that you have the code locally, open up a command prompt and navigation to the root of the repository. Here you will find two "setup" scripts. Setup.cmd which is for Windows and Setup.sh which is for Mac or Linux. Based on your environment, run the appropriate script. This will kick of a series of automated build steps that will create a new command, dotnet new3, and make it available n your command line.

Setup scripts

The entire build takes about a minute to complete and you should end up with something similar to the following.

Successful Template Engine Build

Now that we have a successful build, we can start passing arguments against the newly added dotnet new3 command. Anything that is available in dotnet new should be available in dotnet new3 plus any additional features that are available in the development branch you used for the build. For more info on what currently is in development, I would recommend keeping and eye on the repository Issues and Projects pages.

It is worth mentioning that currently the life-cycle of your current build is limited to your current command-line session. Meaning, when you close the command line that session will be terminated. Of which will require to re-build the next time you open up a new session.

Debugging

In order to debug the Template Engine code, your current dotnet new3 session needs to be configured to "DEBUG" and a debugger needs to be attached to the running dotnet-new3.exe process.

Configuring dontnet new3 To DEBUG

Open up a new command line session and navigate to the root of your project. In the root, you will find a script called dn3buildmode-debug.cmd. Execute this script.

debug script

Upon completion you should end up with the following.

debug script complete

Now that dotnet new3 is set to DEBUG, we need to re-run the setup script applicable to our environment so that we will have a fresh donet new3 session available at our command line.

Trigger A Breakpoint

Open up the Microsoft.Templating.sln solution inside Visual Studio. This solution contains the projects needed to run, modify and debug the Template Engine. In the Microsoft.TemplateEngine.Cli project, locate the class named New3Command and navigate to function named Run.

In the Run function, there is a block of logic that checks the list of arguments passed along side your dotnet new3 command for an argument of --debug:attach. If this argument is supplied, a Console.Readline() request will be triggered. This effectively pauses the Template Engine at an early point in its execution. At any point past the Console.Readline(), set a breakpoint.

Breakpoint

Head back to your command line session and run the following.

dotnet new3 --debug:attach {{additonal args}}

In your console window you will see an empty new line, of which is the Console.Readline() request being triggered. This will now give you an opportunity to attach your debugger.

Console Realine Trigger

In Visual Studio, open the Attach To Process window from the Debug menu or by hitting the following keyboard shortcut - ctrl+alt+p. Locate the dotnet-new3.exe process, highlight it and hit the attach button.

Console Realine Trigger

Head back to your command line and hit enter. This will trigger the Console.Readline() to return and allow the breakpoint that you set to bit hit.

Breakpoint hit

The steps I outlined are specific to debugging in Visual Studio. That being said, debugging generally can take place in any application that allows you to "attach to process".

If you have any question, comments or concerns, please feel free to leave them in the comments section below.