Announcing .NET Core Tools Updates in VS 2017 RC

Updated (4/2017): See .NET Core Releases to learn about newer releases.

Updated (4/2017): See Announcing .NET Core Tools 1.0 to learn about the final .NET Core Tools 1.0 release in Visual Studio 2017 RTM.

Today, we are releasing updates to the .NET Core SDK, included in Visual Studio 2017 RC. You can also install the .NET Core SDK for use with Visual Studio Code or at the command line, on Windows, Mac and Linux. Check out the Visual Studio blog to learn more about this Visual Studio 2017 update.

The following improvements have been made in the release:

Templates — dotnet new has been updated and now is based on a new templating engine.
The location of the .NET Standard class library template, in Visual Studio, has been moved to the new .NET Standard node, based on feedback.
Quality — ~50 fixes have been made across the tools to improve product reliability.

The quality fixes have been made across the .NET CLI, NuGet, MSBuild and also in Visual Studio. We will continue to squash bugs as we get closer to Visual Studio 2017 RTM. Please continue sharing your feedback on the overall experience.

Getting the Release

This .NET Core SDK release is available in Visual Studio 2017 RC, as part of the .NET Core cross-platform development workload. It is also available in the ASP.NET and web development workload and an optional component of the .NET desktop development workload. These workloads can be selected as part of the Visual Studio 2017 RC installation process. The ability to build and consume .NET Standard class libraries is available in the all of the above workloads and in the Universal Windows Platform development workload.

You can also install the .NET Core SDK release for use with Visual Studio code or with the command-line use on Windows, macOS and Linux by following the instructions at .NET Core 1.0 – RC4 Download.

The release is also available as Docker images, in the dotnet repo. The following SDK images are now available:

1.0.3-sdk-msbuild-rc4
1.0.3-sdk-msbuild-rc4-nanoserver
1.1.0-sdk-msbuild-rc4
1.1.0-sdk-msbuild-rc4-nanoserver

The aspnetcore-build repo has also been updated.

Changes to Docker Images

We made an important change with this release to the tags in the dotnet repo. The latest and nanoserver tags now refer to MSBuild SDK images. The latest tag now refers to the same image as 1.1.0-sdk-msbuild-rc4, while nanoserver now refers to the same image as 1.1.0-sdk-msbuild-rc4-nanoserver. Previously, those two tags refered to the same image as 1.1.0-sdk-projectjson-rc3 and 1.1.0-sdk-projectjson-rc3-nanoserver, respectively.

This is a breaking change, since the msbuild SDK is not compatible with the project.json-based SDK. We need to start moving the .NET Core ecosystem to the msbuild SDK, sooner than expected. We had originally planned to make this change at Visual Studio 2017 RTM. The number of times the latest tag is being pulled is growing much faster than we expected, making the break worse with each passing day. As a result, we were compelled to make this change with this release.

You can continue to use the project-json images for now, listed below, to give you more time to transition to the msbuild images (see dotnet migrate). Changing to these, more specific, tags is a one line change in a Dockerfile.

1.1.0-sdk-projectjson-rc3
1.1.0-sdk-projectjson-rc3-nanoserver

Note: We are no longer updating the project.json images, so please do plan your transition to the msbuild images. For example, only the msbuild SDK images will be updated when we release the 1.0.4 and 1.1.1 runtime updates (we expect) later this quarter.

We apologize if you are broken by this change. We will be providing general guidance on how to best use our tags to avoid a similar situation in future. We’ve been learning a lot about Docker over the last several months, particularly around versioning and naming. Expect a blog post soon on this topic that addresses these issues.

Changes to Supported Linux Distros

Fedora 23 and openSUSE 13.2 recently went out of support, per their respective project lifecycle. As a result, we are now no longer supporting or building for Fedora 23 and openSUSE 13.2.

We will be publishing a more formal policy on Linux distro support, in particular on managing end-of-life of distros. There will be opportunity for feedback on the policy before it is finalized.

Project Files

In the RC3 release, we made major improvements to make the csproj project files smaller. If you are using .NET Core project files created with earlier Visual Studio 2017 versions (before RC3), you should read the Updating Project Files section of the RC3 blog post to learn about changes you need to make to your project files.

dotnet new

The dotnet new command is one of the most important parts of the .NET Core tools experiences. It is useful for both new and experienced .NET Core users. I know that people who use and test the product on a daily basis use dotnet new all the time for experiments and prototypes. I do! It’s also documented on a lot of websites and markdown pages to help users get started with .NET Core. That said, we always knew that dotnet new was a little lacking and decided to improve it.

In short, we want dotnet new to have the following characteristics:

Powerful — expressive and scriptable command-line syntax.
Helpful — an interactive mode helps users pick the templates they need (think Yeoman).
Extensible — anyone can write templates for dotnet new!
Updatable — templates can be updated outside of primary delivery vehicles (e.g. Visual Studio, .NET Core SDK).
Platform — can be used by tools like Visual Studio and generator-aspnet (think yo aspnet).

dotnet new is now based on a new templating engine, which you can check out at dotnet/templating. It already does a great job satisfying what the RC3 version of dotnet new did. We’ll continue to add to it and improve it over the next several months, getting it to the point that it satisfies all the characteristics above. For the immediate term, we’re focussed on ensuring that it has the right quality level for Visual Studio 2017 RTM.

Improvements

We have updated dotnet new in the RC4 release with the following features:

You can now specify a target directory for your new template, with the -o argument, such as in the following example: dotnet new console -o awesome-new-tool. If the target directory does not exist, it will be created for you. This can also be combined with the -n argument to name projects, such as in the following example: dotnet new console -n awesome-new-tool -o src/awesome.

Target frameworks now have their own argument, -f. You can specify a target framework for any template, provided it is a legal value, such as in: dotnet new console -f netcoreapp1.0. The target framework values are the same as the ones used in the project files.

Solution file management has been improved. You can now create an empty solution file with dotnet new sln and then add projects to it. You can create solution files before or after project files, depending on your preferred workflow. If you have been using the older project.json-based tooling, you can think of solution files as the replacement for global.json files.

Important Changes

The basic dotnet new (no arguments) experience no longer default to creating a console template, as it did in RC3 and earlier releases. The dotnet new command will now print the available set of templates, much like dotnet new --help. In a later release, we may update dotnet new to start an interactive new template experience, which helps you select the right template based on a series of questions.

The new commandline has been streamlined. To create templates, you type dotnet new console or dotnet new web for console app or MVC templates respectively. The RC3 and earlier tools versions required a -t argument before the template name, such as dotnet new -t web.

Some of the template names changed, specifically Lib (now classlib) and Xunittest (now xunit). For RC4, you will need to use the new template names.

Walkthrough of the new template experience

You are probably curious about the new dotnet new experience. Sayed Hashimi, the Program Manager for dotnet new, wrote the following walkthrough to give you a good idea of what to expect. That said, I encourage you to install the RC4 SDK and try it out for yourself.

Sayed’s walkthrough was done on Linux. You can replicate the same experience on Windows. Just make sure to replace the Linux commands with the ones you are using in your favorite Windows shell.

Getting familiar with the new new

First let’s get a little familiar with new by displaying the help using the dotnet new --help. The result is shown below.

$ dotnet new --help
Template Instantiation Commands for .NET Core CLI.

Usage: dotnet new [arguments] [options]

Arguments:
  template  The template to instantiate.

Options:
  -l|--list         List templates containing the specified name.
  -lang|--language  Specifies the language of the template to create
  -n|--name         The name for the output being created. If no name is specified, the name of the current directory is used.
  -o|--output       Location to place the generated output.
  -h|--help         Displays help for this command.
  -all|--show-all   Shows all templates


Templates                                 Short Name      Language      Tags          
--------------------------------------------------------------------------------------
Console Application                       console         [C#], F#      Common/Console
Class library                             classlib        [C#], F#      Common/Library
Unit Test Project                         mstest          [C#], F#      Test/MSTest   
xUnit Test Project                        xunit           [C#], F#      Test/xUnit    
Empty ASP.NET Core Web Application        web             [C#]          Web/Empty     
MVC ASP.NET Core Web Application          mvc             [C#], F#      Web/MVC       
Web API ASP.NET Core Web Application      webapi          [C#]          Web/WebAPI    
Solution File                             sln                           Solution      

Examples:
    dotnet new mvc --auth None --framework netcoreapp1.0
    dotnet new mstest --framework netcoreapp1.0
    dotnet new --help

From the help output we can see that to create a project we can execute dotnet new <templatename>. The template names are displayed in the results of --help but you can also get the names using dotnet new -l.

Creating Projects

Let’s create a new HelloWorld console app. The most basic way to create a console app is using the command dotnet new console. The other parameters that we can specify are listed below.

-n|--name
-o|--output
-lang|--language

In this case we want to create a C# console app named HelloWorld in the src/HelloWorld directory. Since C# is the default language for the console app template (default value indicated in help by [ ]) there is no need to pass a value to -lang. To create the project execute dotnet new console -n HelloWorld -o src/HelloWorld. The result is shown below.

$ dotnet new console -n HelloWorld -o src/HelloWorld
Content generation time: 32.4513 ms
The template "Console Application" created successfully.

Let’s see what was generated by listing the files on disk.

$ ls -R
src

./src:
HelloWorld

./src/HelloWorld:
HelloWorld.csproj   Program.cs

The HelloWorld project was created as expected in src/HelloWorld, and it consists of two files HelloWorld.csproj and Program.cs. Let’s restore the packages and run the app using dotnet restore and then dotnet run. See the result.

$ cd src/HelloWorld/
$ dotnet restore
  Restoring packages for /Users/sayedhashimi/temp/blog/samples/src/HelloWorld/HelloWorld.csproj...
  Generating MSBuild file /Users/sayedhashimi/temp/blog/samples/src/HelloWorld/obj/HelloWorld.csproj.nuget.g.props.
  Generating MSBuild file /Users/sayedhashimi/temp/blog/samples/src/HelloWorld/obj/HelloWorld.csproj.nuget.g.targets.
  Writing lock file to disk. Path: /Users/sayedhashimi/temp/blog/samples/src/HelloWorld/obj/project.assets.json
  Restore completed in 953.36 ms for /Users/sayedhashimi/temp/blog/samples/src/HelloWorld/HelloWorld.csproj.

  NuGet Config files used:
      /Users/sayedhashimi/.nuget/NuGet/NuGet.Config

  Feeds used:
      https://api.nuget.org/v3/index.json
$ dotnet run
Hello World!

From the output we can see the packages were restored successfully and when the app was executed Hello World! was printed to the console.

Templates with Options

Templates can expose options, which customize template output based on user input. We can see those options by calling --help on a template, such as with dotnet new mvc --help.

$ dotnet new mvc --help
Template Instantiation Commands for .NET Core CLI.

Usage: dotnet new [arguments] [options]

Arguments:
  template  The template to instantiate.

Options:
  -l|--list         List templates containing the specified name.
  -lang|--language  Specifies the language of the template to create
  -n|--name         The name for the output being created. If no name is specified, the name of the current directory is used.
  -o|--output       Location to place the generated output.
  -h|--help         Displays help for this command.
  -all|--show-all   Shows all templates


MVC ASP.NET Core Web Application (C#)
Author: Microsoft
Options:                                                              
  -au|--auth           The type of authentication to use              
                           None          - No authentication          
                           Individual    - Individual authentication  
                       Default: None                                  

  -uld|--use-local-db  Whether or not to use LocalDB instead of SQLite
                       bool - Optional                                
                       Default: false                                 

  -f|--framework                                                      
                           netcoreapp1.0    - Target netcoreapp1.0    
                           netcoreapp1.1    - Target netcoreapp1.1    
                       Default: netcoreapp1.0

Here we can see that the mvc template has three specific parameters. In this case let’s create an mvc app named MyWeb in the src/MyWeb directory targetting netcoreapp1.1. To do that we will execute dotnet new mvc -n MyWeb -o src/MyWeb -au Individual -f netcoreapp1.1.

$ dotnet new mvc -n MyWeb -o src/MyWeb -au Individual -f netcoreapp1.1
Content generation time: 429.6003 ms
The template "MVC ASP.NET Web Application" created successfully.

Now the project has been created in the src/MyWeb directory. Let’s take a look.

$ ls -lp src/MyWeb/
total 80
drwxr-xr-x  5 sayedhashimi  staff   170 Feb  3 10:43 Controllers/
drwxr-xr-x  4 sayedhashimi  staff   136 Feb  3 10:43 Data/
drwxr-xr-x  5 sayedhashimi  staff   170 Feb  3 10:43 Models/
-rwxr--r--  1 sayedhashimi  staff  1767 Feb  3 10:43 MyWeb.csproj
-rwxr--r--  1 sayedhashimi  staff  4096 Feb  3 10:43 MyWeb.db
-rwxr--r--  1 sayedhashimi  staff   544 Feb  3 10:43 Program.cs
drwxr-xr-x  5 sayedhashimi  staff   170 Feb  3 10:43 Services/
-rwxr--r--  1 sayedhashimi  staff  3081 Feb  3 10:43 Startup.cs
drwxr-xr-x  8 sayedhashimi  staff   272 Feb  3 10:43 Views/
-rwxr--r--  1 sayedhashimi  staff   168 Feb  3 10:43 appsettings.Development.json
-rwxr--r--  1 sayedhashimi  staff   185 Feb  3 10:43 appsettings.json
-rwxr--r--  1 sayedhashimi  staff   197 Feb  3 10:43 bower.json
-rwxr--r--  1 sayedhashimi  staff   604 Feb  3 10:43 bundleconfig.json
-rwxr--r--  1 sayedhashimi  staff    61 Feb  3 10:43 runtimeconfig.template.json
-rwxr--r--  1 sayedhashimi  staff   680 Feb  3 10:43 web.config
drwxr-xr-x  8 sayedhashimi  staff   272 Feb  3 10:54 wwwroot/

Future Plans

We want to enable everyone to create templates and make it easy to share those templates. Templates will be installable as NuGet packages or a folder. In the mean time checkout out the templating wiki for info on creating templates. I was happy to see the Custom project templates using dotnet new post by one of the community members that we’ve been working with for early feedback. Here’s my favorite quote from his post

“This new method makes creating project templates about as easy as it’s ever going to get and allows really easy sharing, versioning and personalization of project templates.”.

We are also working on a way to enable templates to be updated. For critical fixes we are considering updating templates without any user interaction. For general updates we are looking to add a new --update option.

We are working on plans to integrate the templating engine with the Visual Studio family of IDEs and other template experiences, such as Yeoman. We have a vision of everyone producing templates in a single format that works with all .NET tools. Wouldn’t that be nice!?! If you’re interested in learning more about how yo aspnet relates to dotnet new see my comments on the topic.

Last, we’re hoping to update the command line experience to be interactive. In this mode we will prompt for things like the template name, project name and the other information that you otherwise need to provide as command line arguments. We believe that interactive is the ultimate new user experience.

Summary

I’ve been asked several times recently when the .NET Core Tools will ship a final RTM release. The tools will ship as an RTM release the same day as Visual Studio 2017 RTM. We’re getting close. As I said at the start of the post, we’ve got a few more bugs to squash first and then we’ll be happy to get the release out the door for you to use.

In this release, we’ve focussed on quality improvements. We also switched over to a new and more capable templating engine. In this release, the new dotnet new implementation is largely a replacement of the functionality that was included in the RC3 release. In upcoming releases, you should expect to see some great new features that make you more productive at the command line. We hope to integrate this new system into Visual Studio, too, enabling us (and you!) to share templates across all .NET Core tools.

Thanks to Sayed Hashimi for the write-up on the new dotnet new implementation!

As always, please shared your feedback, either in the comments, in email or twitter.

For general feedback, please contact us at dotnet@microsoft.com or at @dotnet.
For template users and authors, feel free to contact Sayed directly at sayedha@microsoft.com at @SayedIHashimi

Thanks!