Configure StoreBuilder with new ASP.NET MVC Project

Step 1 - Create a New MVC Project

Step 2 - Add StoreBuilder Nuget Packages

StoreBuilder hosts a private nuget server for our components. If this is your first time using StoreBuilder Nuget, please see Configuring Visual Studio to access the StoreBuilder Nuget Server

Add StoreBuilder Nuget Packages:

  • StoreBuilder
  • StoreBuilder.AspNetIdentity
  • StoreBuilder.HandlebarsCompiler
  • StoreBuilder.Mvc
  • StoreBuilder.WebsiteManager


  • StoreBuilder.Log4net
  • StoreBuilder.Admin

Note: StoreBuilder requires logging. You do not have to use Log4net but if you do not then you must have some other logging library configured and operational for StoreBuilder to run.

Step 3 - Configure StoreBuilder to Use AspNetIdentity Security Provider for Authentication

Add StoreBuilder configuration to your web project's /Web.config file.

Part A - Add a new <section> to your <configSection> element.

<section name="storebuilder" type="StoreBuilder.Config, StoreBuilder" />

Part B - Add a <storebuilder> configuration element.

  <database connectionStringName="StoreBuilder" />
  <securityProvider type="StoreBuilder.AspNetIdentity.IdentitySecurityProvider, StoreBuilder.AspNetIdentity" />

Part C - Provide the correct values for the accountKey and licenseKey attributes of the <license> node.

Step 4 - Configure StoreBuilder Logging

Recall that StoreBuilder requires logging to run. This step describes configuring the StoreBuilder.Log4net Nuget package mentioned in step 2. However, you may use some logging library other than Log4net.

Part A - Add a new <section> to your <configSection> element.

<section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />

Part B - Add a <logProvider> element to the <storebuilder> configuration element that you added in Step 3 - Part B.

  <logProvider type="StoreBuilder.Log4Net.LogProvider, StoreBuilder.Log4Net" />

Part C - Add the <log4net> element to your <configuration> node.

    <appender name="LogFileAppender" type="log4net.Appender.RollingFileAppender">
      <param name="File" value=".\\App_Data\\StoreBuilder.Web.log" />
      <param name="AppendToFile" value="true" />
      <param name="RollingStyle" value="Size" />
      <param name="MaxSizeRollBackups" value="100" />
      <param name="MaximumFileSize" value="10MB" />        
      <param name="CountDirection" value="1" />
      <param name="StaticLogFileName" value="true" />
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%date [%thread] %-5level - %message%newline" />
      <level value="INFO" />
      <appender-ref ref="LogFileAppender" />

Step 5 - Hook in StoreBuilder Routing for MVC

Edit the default /App_Start/RouteConfig.cs file generated by the MVC project template.

Part A - Remove the default route mapping.

     name: "Default",
     url: "{controller}/{action}/{id}",
     defaults: new { controller = "Home", action = "Index", id = UrlParameter.Optional }

Part B - Add the following line as the last route table entry of the RegisterRoutes method thereby passing all unhandled routes to StoreBuilder for processing. StoreBuilder will then internally resolve ecommerce related routes as well as handle any 404 not found routes.

routes.Add(new StoreBuilderRouteProcessor("{*catchAll}", new MvcRouteHandler()));

Part C - Add the following using clause at the top of the file.

using StoreBuilder.Mvc.Routing;

Step 6 - Hook in StoreBuilder Routing for Websync

Websync is a highly scalable HTTP streaming (comet) server built for the Microsoft stack (.NET/IIS) using the Bayeux protocol. StoreBuilder requires Websync for real-time system monitoring and updates.

Part A - To configure Websync open your /Global.asax.cs file and add the following as the first line of the Application_Start method.


Part B - Add the following using clause at the top of the file.

using StoreBuilder;

Step 7 - Add StoreBuilder Namespaces to Your Web.config for Razor Views

Add the StoreBuilder namespace to /Views/Web.config so that StoreBuilder HtmlHelper extension methods work properly in your Razor views.

Add the following lines to the configuration/system.web.webPages.razor/pages/namespaces node.

<add namespace="StoreBuilder" />
<add namespace="StoreBuilder.Models" />
<add namespace="StoreBuilder.Mvc" />

Assuming your solution is named WebApplication1 your configuration should look something like this.

    <pages pageBaseType="System.Web.Mvc.WebViewPage">
        <add namespace="System.Web.Mvc" />
        <add namespace="System.Web.Mvc.Ajax" />
        <add namespace="System.Web.Mvc.Html" />
        <add namespace="System.Web.Optimization"/>
        <add namespace="System.Web.Routing" />
        <add namespace="WebApplication1" />
        <add namespace="StoreBuilder" />
        <add namespace="StoreBuilder.Models" />
        <add namespace="StoreBuilder.Mvc" />

Step 8 - Add a PageWrapper Razor View

The StoreBuilder.Mvc Nuget package contains an MVC StoreBuilderController which is used to integrate StoreBuilder functionality into a regular MVC project. While all StoreBuilder core features and plugins use Handlebars for templating, markup intended to be rendered as a page will be passed through this StoreBuilderController and wrapped with a surrounding Razor view in order to make site wide consistency easy for the MVC developer.

Part A - In your /Views folder, add a new folder called StoreBuilder. Then add a new Razor view in the /Views/StoreBuilder folder named PageWrapper.cshtml.

As a minimum this template may appear as follows.

@model StoreBuilder.Content.Results.PageContentResult
@section styles{
@section scripts{

Part B - Also, add a new Razor view in the /Views/StoreBuilder folder named CaptivePageWrapper.cshtml.

    This razor view is a wrapper for content rendered by StoreBuilder.
    The intention of this razor view is to wrap "captive" pages that should have no regular site navigation elements.
@model StoreBuilder.Content.Results.PageContentResult
    Layout = "~/Views/Shared/_CaptiveLayout.cshtml";
@section styles{
@section scripts{

Part C - For the StoreBuilder.WebsiteManager plugin add a new Razor view in the /Views/Shared folder named _CaptiveLayout.cshtml.

<!DOCTYPE html>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    @RenderSection("styles", required: false)
<body itemscope itemtype="">
    @RenderSection("scripts", required: false)

Step 9 - Create a /themes Folder for Your StoreBuilder Themes

StoreBuilder will by default look for a /themes folder in the root of your project to discover any StoreBuilder theme files. Each theme should be contained within a subfolder of the root /themes folder.

The default theme should be aptly named 'default' and contained within the /themes/default folder.

Part A - Add /themes/default to your project.

Optional Part B - While not absolutely required, StoreBuilder recommends a functional organization structure for themes with subfolders for functional areas of the website. For example, you could add the following subfolders under your /themes/default folder (or to any other theme you create) to organize UI functionally.

  • /everywhere contains JS/CSS that should be included everywhere on your website (all pages).
  • /listing contains JS/CSS/HBS files that will be loaded/used on product listing type pages in addition to anything that was included 'everywhere'. Listing pages include Category pages, Brand pages, Tag pages and Search results.
  • /product contains JS/CSS/HBS files that will be loaded/used on product pages in addition to anything that was included 'everywhere'.
  • /cart contains JS/CSS/HBS files that will be loaded/used on the cart page in addition to anything that was included 'everywhere'.
  • /checkout contains JS/CSS/HBS files that will be loaded/used on the checkout page(s) in addition to anything that was included 'everywhere'.
  • '/account` contains JS/CSS/HBS files that will be loaded/used on the customer account page(s) in addition to anything that was included 'everywhere'.
  • /plugins contains JS/CSS/HBS files that have been provided by any installed plugins. After a plugin has been installed, you have the option to customize the plugin JS/CSS/HBS files to match your branding or unique requirements.
  • /emails contains HBS templates for emails that StoreBuilder may send.

For more information see StoreBuilder ThemeEngine.

Optionally, Use a pre-built StoreBuilder theme to get started quickly.

If you want to get started quickly you can add one of our pre-built themes to your project using Nuget.

  • StoreBuilder.Bootstrap3Theme

To use the theme with our pre-built Header, Navigation and Footer update your _Layout.cshtml file to be similar to the following.

<!DOCTYPE html>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    @RenderSection("styles", required: false)
    <link href='//' rel='stylesheet' type='text/css'>
<body itemscope itemtype="">
    @Html.RenderTemplate("sb-header", new { Environment = StoreBuilderEnvironment.Current, SearchString = Request.QueryString["q"] })
    @Html.RenderTemplate("sb-navbar", new { Environment = StoreBuilderEnvironment.Current })
    <div class="container">
    @Html.RenderTemplate("sb-footer", new { Environment = StoreBuilderEnvironment.Current })
    @RenderSection("scripts", required: false)

Step 10 - Secure the /storebuilder Project Path

If you installed the StoreBuilder.Admin Nuget package then your StoreBuilder web project will have an admin portal. This is located in the /StoreBuilder folder in your project root. All the APIs used by this admin portal will already be secured, however securing the admin portal files will add one more layer of protection to your website and prevent public review of your admin portal code or configuration.

Add the following <location> node to your configuration in /Web.config.

<location path="storebuilder">
      <allow roles="StoreBuilder.Admin" />
      <deny users="*" />

Step 11 - Create a Database

StoreBuilder supports Microsoft SQL Server 2014. Create an empty SQL Server database giving it whatever name you want.

Step 12 - Completing Setup using the WebsiteManager Plugin

StoreBuilder provides a web based WebsiteManager plugin to complete your setup process. You installed this in step 2 when you installed the StoreBuilder.WebsiteManager Nuget package.

Run your project locally. Note that you may see a 403 error for the / path if you have not configured a default.aspx in your project's root. Navigate to /setup and follow the setup steps until the WebsiteManager tells you that your setup is complete.


If, at this point, your StoreBuilder project is still not working, then the first step is to repeat the above steps ensuring you have not missed anything. If you are still having problems you can contact support at