Improve dotnet templates

[nikolajlauridsen]

New functionality

• Enable delivery API
• Choose models builder mode
• Install starter kit
• Choose development mode
• Choose release type (Latest, Latest LTS, or custom version)
• Docker support
  • This includes both a docker file, and a new template to add a docker-compose and prerequisite files to run Umbraco and the database with docker-compose

Enable delivery API

This is added as a flag, if enabled this will add the .AddDeliveryApi() to Program.cs and enable the delivery API in appsettings.json this also means that if the flag is not enabled .AddDeliveryApi() will not be added to Program.cs anymore, which has the added benefit that it won't be shown in the swagger docs either, currently we are documenting a non-existing API in that case.

Example

dotnet new umbraco -n MySite -da

Choose models builder mode

This option allows you to specify the models mode from the dotnet new template, and additionally enables RazorCompileOnBuild and RazorCompileOnPublish if InMemoryAuto isn't selected.

Note

If IDEDevelopment is selected as development mode, this option only changes the modelsbuilder mode in appsettings.development.json

Example

dotnet new umbraco -n MySite -mm SourceCodeAuto

Install starter kit

This option allows you to install a starter kit from a selection when installing Umbraco. Currently, the only option is the official starter kit, but this can be extended to include community starter kits as well. It's worth noting that this configuration is split into its own template file starterkits.template.json to make adding starter kits easier.

Example

dotnet new umbraco -n MySite -sk TheStarterKit

Choose development mode

Allows you to specify the runtime modes you want to use, you have two options here.

• BackofficeDevelopment - Default behaviour
• IDEDevelopment - Configures appsettings.Development.json to Development runtime mode and SourceCodeAuto models builder mode, and configures appsettings.json to Production runtime mode, Nothing models builder mode, and enables UseHttps

Note

It's still necessary to manually set Umbraco:CMS:WebRouting:UmbracoApplicationUrl in appsettings.json when using IDE Development mode.

Example

dotnet new umbraco -n MySite -dm IDEDevelopment

Choose release type

Allows you to specify which release type you want to install

• Latest - The template version
• Latest LTS - The latest LTS version

Note

With the introduction of this new parameter the old UmbracoVersion has been deprecated and hidden in favour of release type.

Important

This means that from this point on we have to update our templates when we make a new LTS, to ensure that a template installs the latest LTS for that template, there is also a limitation here that the template can only install the latest versions from the time of the template release, so it'll still be necessary to manually update your templates.

Example

dotnet new umbraco -n MySite -r LTS

Docker support

Adds Docker support to the template. This comes in two parts

--add-docker parameter

Adds a Dockerfile and .dockerignore to the project, this is by and large a pretty standard dotnet Docker file with one exception. This Dockerfile will recreate the umbraco and umbraco/Logs folders, and run chown for the docker user, the reason for this is that it's ideal to have these folders as volumes, however when the Docker daemon creates these folders it'll do so as the root user, this means that Umbraco won't be able to write logs, modelsbuilder and so on to these files, which it needs to do.

umbraco-compose template

In addition to the docker parameter a new item template has been added umbraco-compose this template will add a couple of files to the current folder.

Important

Due to a know issue with the azure-sql-edge the docker-compose file currently doesn't work on mac, see known issue on https://hub.docker.com/r/microsoft/azure-sql-edge

• Database folder
  • Dockerfile - This is a docker file to setup a SQL database for Umbraco to run with
  • setup.sql - A SQL feed which creates the database if it does not exist
  • startup.sh - A startup shell script that initializes the database if it has not been done yet
  • healthcheck.sh - This shell script will query for the umbracoDb, this is mainly used to ensure that the database is created before the umbraco container is started on the first run.
• .env - An environment file containing the database password
• docker-compose.yml - A docker-compose file that's optimized for local development, this means that folders like views, media, models, and so on are mounted to the host filesystem, allowing you to edit the views directly in your IDE even though it's running in docker. Additionally, it also builds the site using Debug, and sets the ASPNETCORE_ENVIRONMENT to Development

Caution

The umbraco-compose template is intended for local development, and should not be used for production, it is not advisable to have your database password in a .env file in production, it is however considered acceptable for local development.

Parameters

• -P, --ProjectName - This is required, and should be the name of your site project
• -dbpw, --DatabasePassword - An optional parameter that allows you to specify a password to use for the SA user
• -p, --Port - Optional parameter that allows you to specify what port should be forwarded to your docker container, is 44372 by default

Example

mkdir MySite
cd MySite
dotnet new umbraco -n MySite --add-docker
dotnet new umbraco-compose -P "MySite"
docker compose up

Testing

Prerequisites

Docker installed.

A local Nuget feed:

1. Create a folder on your filesystem, for instance, I keep mine in \Github\LocalFeed
2. Add the folder as a nugget source: dotnet nuget add source "C:\Users\NikolajELauridsen\Documents\Github\LocalFeed" -n "Local Feed"

Building and testing templates

1. Ensure that you have Umbraco set up, that is the frontend submodule updated and built, in other words follow our build documentation.
2. Pack Umbraco to create the templates nuget package: dotnet pack umbraco.sln -o Build.Out This will put the files in a Build.Out folder
3. Copy the contents of Build.Out into your local feed folder, created in the prerequisites
4. Install the template: dotnet new install Umbraco.Templates::14.2.0--rc.preview.0.gdfa8ff6 (Replace the version with the one specified in your files), I.E.: Umbraco.Cms.14.2.16--rc.preview.0.gdfa8ff6 has a version of 14.2.16--rc.preview.0.gdfa8ff6
5. Use your template as you normally would dotnet new umbraco -n "MyAwesomeProject"

Caution

Beware of the Nuget cache. Nuget will want to cache your packages, so if you don't see your changes peak through, this is likely because of the cache.

Docker and local templates

If you're working on the docker or docker-compose files, you likely want to run the project created by the template in docker, but there's a caveat here. The docker container needs access to your locally compiled Nuget files to run the restore, however, the docker image does not have access to your files system, and cannot get access to your local Nuget feed.

There is a workaround though

First off add the following two lines just before the RUN dotnet restore line in the Dockerfile:

COPY LocalFeed /packages
RUN dotnet nuget add source "/packages" -n "Local Feed"

This will copy the contents of the Localfeed folder into the container, and then add a local source from that folder in the container, meaning it can now find the local Nuget files.

Important

The LocalFeed folder must be in the same folder as the docker-compose file.

Now you can run the compose with:

docker compose up