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:

Run dotnet new --install "NetEscapades.Templates::*" to install the project template

Run dotnet new basicwebapi --help to see how to select the various features to include in the project

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:

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!