Creating a basic Web API template using dotnet new custom templates

In my last post, I showed a simple, stripped-down version of the Web API template with the Razor dependencies removed.

As an excuse to play with the new CLI templating functionality, I decided to turn this template into a dotnet new template.

For details on this new capability, check out the announcement blog post, or the excellent series by Muhammed Rehan Saeed. In brief, the .NET CLI includes functionality to let you create your own templates using dotnet new, which can be distributed as zip files, installed from the source code project folder or as NuGet packages.

The Basic Web API template

I decided to wrap the basic web API template I created in my last post so that you can easily use it to create your own Web API projects without Razor templates.

To do so, I followed Muhammed Rehan Saeed's blog posts (and borrowed heavily from his example template!) to create a version of the basic Web API template you can install from NuGet.

This template creates a very stripped-down version of the web API project, with the Razor functionality removed. If you are looking for a more fully-featured template, I recommend checking out the ASP.NET MVC Boilerplate project.

If you have installed Visual Studio 2017, you can use the .NET CLI to install new templates and use them to create projects:

1. Run dotnet new --install "NetEscapades.Templates::*" to install the project template
2. Run dotnet new basicwebapi --help to see how to select the various features to include in the project
3. Run dotnet new basicwebapi --name "MyTemplate" along with any other custom options to create a project from the template.

This will create a new basic Web API project in the current folder.

Options and feature selection

One of the great features in the .NET CLI templates are the ability to do feature selection . This lets you add or remove features from the template at the time it is generated.

I added a number of options to the template (again, heavily inspired by the ASP.NET Boilerplate project). This lets you add features that will be commonly included in a Web API project, such as CORS, DataAnnotations, and the ApiExplorer.

You can view these options by running dotnet new basicwebapi --help:

$dotnet new basicwebapi --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


Basic ASP.NET Core Web API (C#)
Author: Andrew Lock
Options:

  -A|--ApiExplorer                 The ApiExplorer functionality allows you to expose metadata about your API endpoints. You can use it to generate documentation about your application. Enabling this option will add the ApiExplorer libraries and services to your project.
                                   bool - Optional
                                   Default: false

  -C|--Controller                  If true, this will generate an example ValuesController in your project.
                                   bool - Optional
                                   Default: false

  -D|--DataAnnotations             DataAnnotations provide declarative metadata and validations for models in ASP.NET Core.
                                   bool - Optional
                                   Default: false

  -CO|--CORS                       Browser security prevents a web page from making AJAX requests to another domain. This restriction is called the same-origin policy, and prevents a malicious site from reading sensitive data from another site. CORS is a W3C standard that allows a server to relax the same-origin policy. Using CORS, a server can explicitly allow some cross-origin requests while rejecting others.
                                   bool - Optional
                                   Default: true

  -T|--Title                       The name of the project which determines the assembly product name. If the Swagger feature is enabled, shows the title on the Swagger UI.
                                   string - Optional
                                   Default: BasicWebApi

 -De|--Description                A description of the project which determines the assembly description. If the Swagger feature is enabled, shows the description on the Swagger UI.

                                   string - Optional
                                   Default: BasicWebApi

  -Au|--Author                     The name of the author of the project which determines the assembly author, company and copyright information.

                                   string - Optional
                                   Default: Project Author

  -F|--Framework                   Decide which version of the .NET Framework to target.

                                       .NET Core         - Run cross platform (on Windows, Mac and Linux). The framework is made up of NuGet packages which can be shipped with the application so it is fully stand-alone.

                                       .NET Framework    - Gives you access to the full breadth of libraries available in .NET instead of the subset available in .NET Core but requires it to be pre-installed.

                                       Both              - Target both .NET Core and .NET Framework.

                                   Default: Both

  -I|--IncludeApplicationInsights  Whether or not to include Application Insights in the project
                                   bool - Optional
                                   Default: false

You can invoke the template with any or all of these options, for example:

$dotnet new basicwebapi --Controller false --DataAnnotations true -Au "Andrew Lock"
Content generation time: 762.9798 ms
The template "Basic ASP.NET Core Web API" created successfully.

Source code for the template

If you're interested to see the source for the template, you can view it on GitHub. There you will find an example of the templates.json file that describes the template, as well as a full CI build using cake and AppVeyor to automatically publish the NuGet templates.

If you have any suggestions, bugs or comments, then do let me know on the GitHub!