P3.NET

Creating a REST API Project Template

While web API and MVC tend to go together, there are cases where you want a pure web API project. This is most common with REST services that have no UI. You would think that this should be easy to set up but, surprisingly, the default web API project in Visual Studio includes MVC. MVC brings in a lot of stuff that you simply don’t need including styling, MVC routing and client libraries. For a REST service where there will be no UI this is wasteful. In this article I’m going to discuss how to create a basic project template for REST services without the need for MVC.

Base Template

We will start with an empty project so that we can add only the features we care about. Go ahead and start up Visual Studio and create a new project. For this template we will use the ASP.NET Web Application (.NET Framework) project. We won’t be opting into Application Insights so uncheck that box. On the Select a Template page choose Empty. Then check the box for Web API under Add folders and core references for. For the skeleton template we won’t be using the cloud or any security (you can add OAuth later if you want) so uncheck those options. Then generate the project.

Customizing the Project

At this point we can start customizing the project template to match whatever requirements we have for our REST APIs. One thing that I always do is disable the default routing. I prefer to have each of the controllers be explicit about their paths so go into App_Start\WebApiConfig.cs and remove the line that calls config.Routes.MappHttpRoute.

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        // Web API configuration and services

        // Web API routes
        config.MapHttpAttributeRoutes();
    }
}

You can go ahead and add your DI container of choice, add any core NuGet references and other features that all your REST projects will use. I don’t use the App_Data folder so I’m going to go ahead and remove that.

The default web API project creates a dummy controller so you have a starting point. If you want to do a similar thing for this template then go ahead and add an API controller by right-clicking the Controllers folder and selecting Add\Controller\Web API 2 Controller – Empty. Customize it as needed but you should probably at least add a method.

[RoutePrefix("api/values")]
public class ValuesController : ApiController
{
    [HttpGet]
    [Route("")]
    public Task Get ()
    {
        return Task.FromResult(DateTime.Now);
    }
}

Adding a Test Harness

Personally I like for all my APIs to have a test harness that can be used to easily test the API. For that I am currently using Swagger and Swashbuckle so let’s add that functionality in next. First add Swashbuckle from Package Manager to your project. There are several different packages available. Personally I tend to use Swashbuckle by itself. There is also a Swashbuckle.Core package but that doesn’t include all the dependencies. Note also that there is a Swashbuckle.Blue package that seems newer.You can use this version if you like but be aware that OAuth is not supported in this version at this time.

Refer to my previous blog about configuring Swagger for your needs. For this post I’m simply going to adjust the URLs to where the documentation resides to use docs/ui instead.

GlobalConfiguration.Configuration 
                .EnableSwagger("help/{apiVersion}", c =>

//...
 .EnableSwaggerUi("help/ui/{*assetPath}", c =>

Go ahead and compile and run the project and make sure the API is working properly. To get the document you need to go to the URL <serverpath>/help/ui/index.

Setting the Default Document

We’re almost done with the project but the last thing that I want to do is have the help page come up as the default document. If this were an ASP.NET site I’d use the default documents in the config file. For MVC I’d put a redirect in the HomeController or update the routing but none of this works with Web API. Instead we’ll have to use URL rewriting. This is actually pretty trivial. All we need to do is add a rewrite rule in the config that maps any requests to the root URL (and only the root) to our help page.

<system.webserver>
   <!-- This rule causes any request to the root URL to be redirected to the documentation without the need for MVC -->
    <rewrite>
         <rules>
             <rule stopprocessing="true" name="Show Help">
                 <match url="^$">
                 <action type="Redirect" url="help/ui/index">
             </action></match></rule>
         </rules>
     </rewrite>
</system.webserver>

The only thing to be aware of is that this requires the URL Rewrite module to be installed. For IISExpress this will just work but for a full version of IIS you need to install it via the Web Platform Installer. Once you’ve done that the redirect should occur automatically.

Export the Template

We have the project set up so now we can convert it to the project template. With the solution open in VS go to the File\Export Template menu and click. Since we want a new project type ensure Project Template is checked and our API project is selected. On the next page enter some basic information about the template.

Template name

The name as it will appear in the project template dialog
Template description
A description of the template
Icon Image
The icon shown next to the template in the list (optional)
Preview Image
The preview that will be shown to the right (optional)
Output Location
Where the generated template file (.zip) is stored
Automatically Import
Indicates whether to go ahead and import the template into VS or not

Once the template has been generated you can create a new project and your template should show up (under Visual C#). But the generated template is not quite consistent with how the rest of the templates work so we are going to adjust it.

Adjusting the Template

One change you might want to make is to generate multiple projects from a single template. This is supported but not well documented. Personally I am fine breaking up multi-project solutions into multiple templates so I can mix and match the stuff I need but if you want to create a multi-project template you’ll need to manually adjust the template as documented here.

The changes that I’m going to focus on for this article is getting the template to show up under the correct category (Web in this case) and giving it a slightly better default name. To do that we need to extract the .vstemplate file from the generated .zip file. Then open it in a text editor or Visual Studio.

<VSTemplate Version="3.0.0" xmlns="http://schemas.microsoft.com/developer/vstemplate/2005" Type="Project">
  <TemplateData>
    <Name>Standard REST API</Name>
    <Description>A standard REST API project</Description>
    <ProjectType>CSharp</ProjectType>
    <ProjectSubType>
    </ProjectSubType>
    <SortOrder>1000</SortOrder>
    <CreateNewFolder>true</CreateNewFolder>
    <DefaultName>Standard REST API</DefaultName>
    <ProvideDefaultName>true</ProvideDefaultName>
    <LocationField>Enabled</LocationField>
    <EnableLocationBrowseButton>true</EnableLocationBrowseButton>
    <Icon>__TemplateIcon.ico</Icon>
  </TemplateData>
  <TemplateContent>
    <Project TargetFileName="SimpleRestProject.csproj" File="SimpleRestProject.csproj" ReplaceParameters="true">
      <Folder Name="App_Start" TargetFolderName="App_Start">
        <ProjectItem ReplaceParameters="true" TargetFileName="SwaggerConfig.cs">SwaggerConfig.cs</ProjectItem>
        <ProjectItem ReplaceParameters="true" TargetFileName="WebApiConfig.cs">WebApiConfig.cs</ProjectItem>
      </Folder>
      <Folder Name="Controllers" TargetFolderName="Controllers">
        <ProjectItem ReplaceParameters="true" TargetFileName="ValuesController.cs">ValuesController.cs</ProjectItem>
      </Folder>
      <ProjectItem ReplaceParameters="true" TargetFileName="Global.asax">Global.asax</ProjectItem>
      <ProjectItem ReplaceParameters="true" TargetFileName="Global.asax.cs">Global.asax.cs</ProjectItem>
      <Folder Name="Models" TargetFolderName="Models" />
      <ProjectItem ReplaceParameters="true" TargetFileName="packages.config">packages.config</ProjectItem>
      <Folder Name="Properties" TargetFolderName="Properties">
        <ProjectItem ReplaceParameters="true" TargetFileName="AssemblyInfo.cs">AssemblyInfo.cs</ProjectItem>
      </Folder>
      <ProjectItem ReplaceParameters="true" TargetFileName="Web.config">Web.config</ProjectItem>
      <ProjectItem ReplaceParameters="true" TargetFileName="Web.Debug.config">Web.Debug.config</ProjectItem>
      <ProjectItem ReplaceParameters="true" TargetFileName="Web.Release.config">Web.Release.config</ProjectItem>
    </Project>
  </TemplateContent>
</VSTemplate>

As you can see some of the values came from the export UI. We want to change the following values.

DefaultName
The default name of the new project. We will set it to RestApi.
ProjectType
The type of the project (which controls category). There are various supported types including standard C# and Visual Basic templates.
ProjectSubType
Some project types support a subtype that further identifies the project type.
PromptForSaveOnCreation
Added this attribute and set it to true otherwise NuGet will not work properly.

To test the changes, update the .zip file with the new template file. Be careful here as there are two places the .zip file resides. The version in the My Exported Templates folder is the template that you exported. But for VS to see it you have to “import” it into VS by copying it to the Visual Studio 2015\Templates\ProjectTemplates folder. It is that version that VS uses. But the template can also be stored in any of the folders under an existing template to further category the template. In general you can put templates into language-specific folders (ex. /Visual C#/1033/Mine).

For getting our template into the Web folder I tried several different things including:

  • Setting ProjectType to Web and ProjectSubType to CSharp
  • Putting the template under /Visual C#/1033/Web
  • Putting the template under /Visual Web Developer

Nothing really worked. The template always showed up under the root templates but never under Web. It is possible, just not sure if it can be done with only a vstemplate.

Once you’ve modified a template you need to tell VS to refresh the installed templates. You can do that by ensuring VS is not running and then starting an elevated command prompt and then running the command devenv /installvstemplates. This will cause VS to relate the templates.

Updating Generated Files

The final set of changes that would be useful is to update the files to reflect the options selected when creating the project. In general the namespace should follow the project name. The template is already set up to replace values inside the source files with values from the project and therefore the namespace will follow the project name. But you may want to adjust other values as well, such as the Swagger name. By default, exporting the template will cause it to scan and replace all namespace references (string or otherwise) with the safe project name parameter.

We could also adjust the file names themselves if we wanted. MSDN documents the supported parameters we can use.

Conclusion

This completes this article. Feel free to update the template according to your needs and create other templates as needed. One unfortunate caveat to all this is that C++, while documented as being supported, doesn’t behave properly as a project template. For C++ projects you have to revert to the legacy wizard interface.

Download the code.