CLI Creation of .NET Core Apps

Something I discovered early about .NET Core was how easy it was to get started. This is due in no small part to the dotnet command line interface. In its earliest releases, .NET Core utilized the dnu and dnx that felt pretty clunky to use, in my opinion. Then the Microsoft team released the dotnet command line changes to the toolchain and that transition made working with the CLI feel much smoother.

Working with the dotnet new Command

To get started you won’t need to download the bloat that is Visual Studio 2017. All you need to do is download the .NET Core SDK and Visual Studio Code. You really don’t even need VS Code for this, but it’s kind of helpful for viewing files in the format intended, and since it’s a fully-fledged, lightweight code editor you can install on Windows, macOS, or Linux, might as well get it out of the way. I use it professionally all the time now and me-sa likes it! <== Yes, that was a Jar Jar Binks reference: I’m a Star Wars fan and admit it publicly.

Once you’ve installed the SDK and Code, go ahead and launch a Powershell prompt. Note: you can do this from a command prompt, but on Windows 10 I’ve just learned to prefer Powershell. I’ll be working inside of a “source” folder on my D drive.

From within Powershell I’m going to type the following:

D:\source > dotnet new --help

If this is the first time you’re running the --help tag you will likely get some output about building the usage telemetry data, i.e., spyware that Microsoft uses to learn how you use .NET Core and the CLI options. It’s fine, I don’t really mind what they know about my usage if it helps to improve the tools. But if you’re that paranoid there’s instructions on how to opt out.

dotnet_new_help

It’s the bottom most content of this output to which I wish to draw your attention. You should find a table listing similar to the following:

dotnet_new_commands

Why, you might ask (or maybe you won’t) am I even pointing this out? Because it never ceases to amaze me how many people fail to RTFM. That’s right—READ THE FRAKKING MANUAL! That’s why Microsoft pays someone serious Gouda to write this stuff. What’s nice about it is I could probably stop right here and you could tell just from that table what do next to build your first .NET Core console app. But nah… where’s the fun in that?

So here we go, now from the prompt type:

dotnet new console -o dnxconsole

You should see the reply: The template "Console Application" created successfully. to indicate app creation.

If you installed Visual Studio Code you can now launch the editor right from the prompt with:

code .\dnxconsole

Assuming all went well with your install of Code, here’s somewhat what you should see (your environment may look a bit different as I’m using the Abyss theme, but it should have at least opened your project inside of Code correctly.

Anatomy of .NET Core Console App

When you first open the console app in Code you’ll probably get a couple of messages as follows:

vscode_warnings

Basically you’ll need to take both those actions but let’s review them one at a time. The first Required assets to build and debug are missing from 'dnxconsole'. Add them? Click Yes to this, as this is what will allow you to actually set break points in, debug, etc. your application. Particularly important if you plan to write some unit tests for this baby, eh? 😉

Note: If you don’t see the above message about assets you may instead see a prompt about installing the C# extension by OmniSharp. If prompted to do so, click the “Show more information” button and install it. You’ll definitely want it. Once you install and reload VS, the message should appear.

Let’s study what sort of effect this will have. First, you’ll notice that a new folder gets added to your project. Specifically:

  • .vscode
  • bin
  • obj

This screenshot shows this as it appears inside of Code. We’ll get more into each of these in a bit.

vscode_new_folders

When you click Restore in the second message, the dependencies are loaded from Nuget as defined in the dnxconsole.csproj and you see output similiar to this:

Restoring packages for d:\source\dnxconsole\dnxconsole.csproj...
Generating MSBuild file d:\source\dnxconsole\obj\dnxconsole.csproj.nuget.g.props.
Generating MSBuild file d:\source\dnxconsole\obj\dnxconsole.csproj.nuget.g.targets.
Writing lock file to disk. Path: d:\source\dnxconsole\obj\project.assets.json
Restore completed in 2.76 sec for d:\source\dnxconsole\dnxconsole.csproj.
Under the Debug folder you also see some additional asset files added:
vscode_debug_assets

The Role of the C# Extension

The C# extension you installed by OmniSharp is what allows you to debug your application within Visual Studio code much like you would if writing any application inside of Visual Studio. You can set breakpoints, write a unit test harness independent of the project, and launch the debugger to step through each line of code if necessary.

With the dotnet restore command (which you invoked through the visual interface in Code) package dependencies were restored, and .NET Core generates two files:

  • launch.json
  • tasks.json

From the OmniSharp README on github:

The launch.json file is used to configure the debugger in Visual Studio Code.Visual Studio Code generates a launch.json with almost all of the required information. If your workspace has only one launchable project, the C# extension will offer to automatically generate this file. If you missed this prompt, you can force the generation by executing the command .NET: Generate Assets for Build and Debug from the VS Code command palette. The generated file contains two sections. One that configures debugging for launch and a second that configures debugging for attach.

In general, the tasks.json file in a project lists the tools to perform automated tasks (go figure). In the case of our project here, there is one build task that will generate the executable to launch our program.

To run the program, press the Ctrl + ` combination to launch the shell/terminal. You can also launch this from the View menu. At the prompt, type dotnet run to execute the program. Assuming all went well you should see the ubiquitous “Hello World!” message.

dotnet_run

That’s it! You’re now a .NET Core expert—in your dreams! We’ll explore this more but we’ve covered what you need to get started. In fact, you know just enough now to be dangerous! Happy coding and watch for my next post when we look at creating a basic ASP.NET .Core app to which we then add OWIN.

Advertisements