Kentico Cloud Boilerplate for ASP.NET Core MVC
This boilerplate includes a set of features and best practices to kick off your website development with Kentico Cloud smoothly.
- Kentico Delivery SDK
- Simple fixed-time caching
- HTTP Status codes handling (404, 500, ...)
- Adjustable images
- Sitemap.xml generator
- URL Rewriting examples
- 301 URL Rewriting
- www -> non-www redirection
- Configs for Dev and Production environment
- Unit tests (xUnit)
The most seamless way to get all prerequisities is to install Visual Studio 2017 with the ".NET Core cross-platform development" workload.
You must have the latest version (.NET Core 2 is minimal) of the dotnet tooling installed. It comes with Visual Studio 2017 (15.3 or higher), or you can download it with the .NET Core SDK. You can check your .NET Core version via
Installation from NuGet
- Open Developer Command Prompt for VS 2017
dotnet new --install "KenticoCloud.CloudBoilerplateNet::*"to install the boilerplate to your machine
- Wait for the command to finish (it may take a minute or two)
dotnet new kentico-cloud-mvc --name "MyWebsite" [--output "<path>"]. (Note: the
--outputparameter is optional.)
- Open in Visual Studio 2017/Code and Run
Installation from source
git clone https://github.com/Kentico/cloud-boilerplate-net.git
dotnet new -i artifacts/*.nupkg
How to debug the app
In Windows, there are basically two ways to run the app:
- via IIS
- as a standalone command-line app
You can read more about the differences on Rick Strahl's blog.
We recommend choosing the second option - as a standalone app. In Visual Studio, you can switch to it in the toolbar:
How to change Kentico Cloud Project ID and Delivery Preview API key
Kentico Cloud Project ID is stored inside
appsettings.json file. This setting is automatically loaded using Options and configuration objects. You can also provide additional environment-specific configuration in
For security reasons, Delivery Preview API key should be stored outside of the project tree. It's recommended to use Secret Manager to store sensitive data.
How to generate Strongly Typed Models for Content Types
With the new Delivery SDK, you can take advantage of code-first approach. To do that you have to instruct the SDK to use strongly-typed models. These models can be generated automatically by model generator utility. By convention, all Content Type Models are stored within the
Models/ContentTypes folder. All generated classes are marked as
partial which means that they can be extended in separate files. This should prevent losing custom code in case the models get regenerated. When generating models, be sure to set the
-n command line parameter to
If you want to use Display Templates (MVC), make sure you generate also a custom type provider (add the
--withtypeprovider parameter when running the generator utility).
How to resolve links
Rich text elements in Kentico Cloud can contain links to other content items. It's up to a developer to decide how the links should be represented on a live site. Resolution logic can be adjusted in the
CustomContentLinkUrlResolver. See the documentation for detailed info.
How to set up webhook-enabled caching
All content retrieved from Kentico Cloud is by default cached for 24 hours in a MemoryCache singleton object. You can either change the time by overriding the value of the
CacheTimeoutSeconds environment variable (e.g. in appsettings.json). Or, if you want your app to immediately clear cache entries of changed content, you can create a webhook in Kentico Cloud for that.
To create the web hook, go to Project settings --> Webhooks --> Create new Webhook. Give it a name (like "Cache invalidation webhook") and the publicly routable URL of your app with
/WebHooks/KenticoCloud appended (like "https://myapp.azurewebsites.net/WebHooks/KenticoCloud"). Then, copy the API secret and paste it as the
KenticoCloudWebhookSecret environment variable (secret) into your app's settings.
Note: During local development, you can use the ngrok service to route to your workstation.
Note: Speed of the Delivery/Preview API service is already tuned up because the service uses a geo-distributed CDN network for most of the types of requests. Therefore, the main advantage of caching in Kentico Cloud applications is not speed but lowering the amount of requests needed (See pricing for details).
How to resize images based on window width
The boilerplate contains a sample implementation of the
HtmlHelperExtensions. Using the
AssetImage() extension method, you can easily create an
img tag with
How to adjust the sitemap.xml
The boilerplate contains a sample implementation of the
SiteMapController. Make sure you specify desired content types in the
Index() action method. Also, you can adjust the URL resolution logic in the
How to handle 404 errors or any other error
Error handling is setup by default. Any server exception or error response within 400-600 status code range is handled by ErrorController. By default, it's configured to display Not Found error page for 404 error and General Error for anything else.
How to adjust URL rewriting
The Boilerplate is configured to load all URL Rewriting rules from IISUrlRewrite.xml file. Add or modify existing rules to match your expected behavior. This is a good way to set up 301 Permanent redirects or www<->non-www redirects.
Feedback & Contributing
Any feedback is much appreciated. Check out the contributing to see the best places to file issues, start discussions and begin contributing.
Wall of Fame
We would like to express our thanks to the following people who contributed and made the project possible:
- Emmanuel Tissera - GetStarted
- Andy Thompson- GetStarted
- Sayed Ibrahim Hashimi - Microsoft
- Charith Sooriyaarachchi - 99X Technology
- Lex Li
Would you like to become a hero too? Pick an issue and send us a pull request!