The ASP.NET Core API project template contains the following features:
Optional Feature Selection
The ASP.NET Core API project template uses
dotnet new to enable you to turn features of the project template on or off. Literally everything can be turned on or off with the click of a button for a truly personalized project. Find out more about
dotnet new here.
- Swagger (Default=On) – Swagger is a format for describing the endpoints in your API and letting you try out your site using its user interface.
- Versioning (Default=On) – Enable API versioning to version API endpoints.
- HealthCheck (Default=On) – A health-check endpoint that returns the status of this API and its dependencies, giving an indication of its health.
- XmlFormatter – Choose whether to use the XML input/output formatter and which serializer to use.
- DataContractSerializer – The default XML serializer you should use. Requires the use of [DataContract] and [DataMember] attributes.
- XmlSerializer – The alternative XML serializer which is slower but gives more control. Uses the [XmlRoot], [XmlElement] and [XmlAttribute] attributes.
- None (Default) – No XML formatter.
- 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.
- Description – A description of the project which determines the assembly description. If the Swagger feature is enabled, shows the description on the Swagger UI.
- Author – The name of the author of the project which determines the assembly author and copyright information.
- TreatWarningsAsErrors – Treat warnings as errors.
- HttpPort – Port number to use for the HTTP endpoint in launchSettings.json.
- HttpsPort – Port number to use for the HTTPS endpoint in launchSettings.json.
- Response Caching (Default=On) – Response caching is allows the use of the
[ResponseCache]attribute on your action methods. Cache settings (cache profiles) are stored in the configuration file and referred to by name.
- Response Compression (Default=On) – Enables dynamic GZIP response compression of HTTP responses. Not enabled for HTTPS to avoid the BREACH security vulnerability.
- HttpsEverywhere (Default=On) – Use the HTTPS scheme and TLS security across the entire site, redirects HTTP to HTTPS and adds a Strict Transport Security (HSTS) HTTP header with preloading enabled.
- HstsPreload (Default=Off) – Enable Strict Transport Security (HSTS) HTTP header with preloading.
- CORS (Default=On) – 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.
- HostFiltering (Default=On) – A white-list of host names allowed by the Kestrel web server e.g. example.com. You don’t need this if you are using a properly configured reverse proxy.
- SecurityTxt – Adds a security.txt file to allow people to contact you if they find a security vulnerability.
- ForwardedHeaders (Default=On) – If you use a load balancer, updates the request host and scheme using the X-Forwarded-Host and X-Forwarded-Proto HTTP headers.
- ReverseProxyWebServer – The internet facing reverse proxy web server you want to use in front of the primary web server to host the site.
- None – Use Kestrel directly instead of a reverse proxy.
- IIS – A flexible, secure and manageable Web server for hosting anything on the Web using Windows Server. Select this option if you are deploying your site to Azure web apps.
- NGINX – A free, open-source, cross-platform high-performance HTTP server and reverse proxy.
- Both (Default) – Support both reverse proxy web servers.
- CorrelationId (Default=On) – Correlate requests between clients and this API. Pass a GUID in the X-Correlation-ID HTTP header to set the HttpContext.TraceIdentifier. The header is also reflected back in a response.
- Analytics – Monitor internal information about how your application is running, as well as external user information.
- Application Insights – Monitor internal information about how your application is running, as well as external user information using the Microsoft Azure cloud.
- None (Default) – Not using any analytics.
- ApplicationInsightsKey – Your Application Insights instrumentation key e.g. 11111111-2222-3333-4444-555555555555.
- CloudProvider – Select which cloud provider you are using if any, to add cloud specific features.
- Azure – The Microsoft Azure cloud. Adds logging features that let you see logs in the Azure portal.
- None (Default) – No cloud provider is being used.
- robots.txt (Default=On) – Adds a robots.txt file to tell search engines not to index this site.
- humans.txt (Default=On) – Adds a humans.txt file where you can tell the world who wrote the application. This file is a good place to thank your developers.
Always On Features
- Example Controller – The example
CarControllercontains the following actions:
- GET – Returns single car.
- GET – Implements paging to return a single page worth of cars, where the page size is configurable.
- POST – Add a new car.
- PUT – Update an existing car.
- PATCH – Update one or more properties of an existing car.
- DELETE a single car.
- Automatically Return Not Acceptable – Returns a 406 Not Acceptable if the MIME type in the Accept HTTP header is not valid.
- Caching – Both in-memory and distributed cache are configured. You do need to specify where the distributed cache stores its data.
- Caching Static Files – Static files are cached by default using the
- 304 Not Modified – Last-Modified and If-Modified-Since HTTP headers are used to return 304 Not Modified if a resource has not changed.
- AddMvcCore – Uses only the features and packages from ASP.NET Core required for an API. Uses ControllerBase instead of Controller.
- Named Routes – Uses named attribute routes for best performance and maintainability. All route names are specified as constants.
- Kestrel Limits – Allow configuring Kestrel security limits such as maximum request size via configuration and set sensible stricter defaults.
- User Secrets – This feature is turned on when the site is in development mode to allow storing of secrets on your development machine.
- Remove Server HTTP Header – Removes the Server HTTP header for security and performance.
- Translates Models to ViewModels – Using your models which usually come from a database directly in your controllers can result in a mass assignment attack. View models with a translation layer are used to avoid this.
- Serilog – Has Serilog built in for an excellent structured logging experience.
- Developer Exception Page – Shows detailed exception information in the browser. Turned on in development mode only for security.
Patterns & Practices
- Command Pattern – Writing all your code in your controllers can mean you end up with huge classes. The command pattern splits up each controller action into its own class.
- Configure CacheProfile in JSON – All cache profiles can be configured from a configuration file.
How can I get it?
- Install the latest .NET Core SDK.
dotnet new --install "Boxed.Templates::*"to install the project template.
dotnet new api --helpto see how to select the feature of the project.
dotnet new api --name "MyTemplate"along with any other custom options to create a project from the template.