Tips for developing templates for dotnet new

3 minute read

When creating a new project with the dotnet new command, you are offered a list of templates you can use. These templates allow you to quickly bootstrap a new application according to a specific configuration. There are for example templates to create an MVC application, a Razor application, an API etc.

You can also install extra templates which have been created by other authors. You can discover these templates on the .NET Templating Wiki or on the dotnet core templates website.

You are also able to develop your own templates, either for internal use, or to make it available on NuGet for other people to take advantage of.

I recently developed templates that allow developers to bootstrap a new application that makes use of Auth0 for authentication.

Here are useful resources I came across, as well as some tips for issues I ran into.

Useful Resources

A few issues I ran into

Identity and Group Identity

I created 2 templates for Auth0 - one for MVC apps and the other for APIs. I initially thought that the identity for each template should be unique, but that both templates should have the same groupIdentity. What happened however was that when I installed both templates, only one of them showed up.

I came across this issue on GitHub which explained that this is by design. This is used when you have the sample template which is available in different language versions.

If you want the templates to show up as separate listings, they should have different group identities.

Customise parameter names

You can specify extra parameters for your template in the symbols section of your template.json file, e.g.

{
    "$schema": "http://json.schemastore.org/template",
    [...]
    "symbols": {
        "SignatureAlgorithm": {
            "type": "parameter",
            "datatype": "choice",
            "choices": [
                {
                    "choice": "RS256",
                    "description": "Tokens are signed using RS256"
                },
                {
                    "choice": "HS256",
                    "description": "Tokens are signed using HS256"
                }
            ],
            "description": "The algorithm with which tokens returned from Auth0 are being signed",
            "defaultValue": "RS256"
        },
        "SaveTokens": {
            "type": "parameter",
            "datatype": "bool",
            "description": "If specified, saves the tokens returned from Auth0",
            "defaultValue": "false"
        },
        "IncludeProfilePage": {
            "type": "parameter",
            "datatype": "bool",
            "description": "If specified, adds a page which allows you to view the user's profile",
            "defaultValue": "true"
        },
        "IncludeClaimsPage": {
            "type": "parameter",
            "datatype": "bool",
            "description": "If specified, adds a page which allows you to view the user's claims",
            "defaultValue": "false"
        }
    }
}

When you run dotnet new for your template with the -h option, you will be presented with the list of these options.

However, it did not quite like the fact that the templating engine automatically chose -S and -Sa as the short options SignatureAlgorithm and SaveTokens options respectively.

It turns out that you have control over these, by including dotnetcli.host.json file in the .template.config folder. Inside this file you an specify custom short and long names for each of the options. Here is the example of the one I created:

{
    "$schema": "http://json.schemastore.org/dotnetcli.host",
    "symbolInfo": {
      "SignatureAlgorithm": {
        "longName": "signature-algorithm",
        "shortName": "sa"
      },
      "SaveTokens": {
        "longName": "save-tokens",
        "shortName": "st"
      },
      "IncludeProfilePage": {
        "longName": "include-profile-page",
        "shortName": "pp"
      },
      "IncludeClaimsPage": {
        "longName": "include-claims-page",
        "shortName": "cp"
      }
    }
}

With that in place, you can see that the names of the options are presented according to the information in this file:

Conclusion

I am very happy about the inclusion of the new .NET Templating engine. It is still a little limited in some senses, but it is a great step forward. I hope to see the community contribute a lot of new templates.

Did you notice an error? Please help me and the other readers by heading over to the GitHub repo for this blog and submit a Pull Request with the corrections.