Working with Umbraco v9 beta in CLI

09/05/2021 umbraco umbracov9 dotnet cli

Now we are in .Net core territory with Umbraco v9 (beta), we can utilise the .Net CLI introduced in .Net Core 2.1. Let's have a look at using the CLI to build our Umbraco application.

Note: this was written in reference to v9 Beta 1.

But first, what's a CLI? This is a command line interface, how we interact with the framework tools via command line. Previously as .Net developers, we would usually create and build .Net projects in Visual Studio, but now we can use CLI.

Before we look at Umbraco specific commands, have a wee look here at the .Net CLI. Any Umbraco commands we use are utilising these.

In .Net CLI tools we can create a new project using 'dotnet new' and utilise templates to create a new project with a set of predefined files and config. With Umbraco v9 beta, we can use this command to create a new project with the files we need for an Umbraco project:

dotnet new umbraco -n CRLUmbracov9

This will create a new project called CRLUmbracov9 that we can then build, run and install (see below). However, this creates the new project with default configurations. What if we want to customise? We can use the help comment to see options available:

dotnet new umbraco -h

This will output the help for dotnet CLI new command but also for Umbraco template, lets focus on the Umbraco configurations here:

Command Description Format Optional? Default
v|--version The version of Umbraco to load using NuGet string yes 9.0.0-beta001
-P|--PackageTestSiteName The name of the package this should be a test site for. text yes  
-U|--UseSqlCe Adds the required dependencies to use SqlCE (Windows only) text yes false
-F|--Framework The target framework for the project

net5.0 - Target net5.0


net6.0 - Target net6.0

yes net5.0
-S|--SkipRestore If specified, skips the automatic restore of the project on create bool yes false
-Fr|--FriendlyName The friendly name of the user for Umbraco login when using Unattended install (Without installer wizard UI) text yes  
-E|--Email Email to use for Umbraco login when using Unattended install (Without installer wizard UI) text yes  
-Pa|--Password Password to use for Umbraco login when using Unattended install (Without installer wizard UI) text yes  
-C|--ConnectionString Database connection string when using Unattended install (Without installer wizard UI) text yes  

For developers looking to get started with the beta, I imagine the option we are used to seeing in the install wizard to use SQLCe will be most useful. This is no longer available by default as Umbraco is now multi platform, so we need to add this during the project set up. Here is how in CLI:

dotnet new umbraco -n CRLUmbracov9 --UseSqlCe

Now we have our project, we can build and run the app via CLI too! First, navigate to the project directory:

cd CRLUmbracov9

Now, we build then run via CLI:

dotnet build

dotnet run

Now, we can access the project in browser (url will be shown in CLI window) to run through the setup as we are used to in Umbraco. Note, you will need to restart the application after install.

If we now want open the project to view & edit code, we can open in VS code using this command:

code .

Now, when in build we can use the watch command to keep the application running and listening for changes while we make changes in code:

dotnet watch run

This keeps the application running, listening for changes to our code it rebuilds and makes these chages immediately available in browser. To stop this in CLI, you can use Ctrl + C.

... and there we are! We have created an Umbraco project, built, run and edited all from command line!