Configure Storebuilder with new Umbraco Web Project

This configuration is used when you only need one instance of StoreBuilder on your website. Umbraco and StoreBuilder will happily co-exist within the same web project to produce a unified website experience for your customers and staff. This is the most common arrangement for most small to medium sized businesses.

Step 1 - Create new empty Web Project.

Step 2- Add Umbraco Nuget packages.

Step 3 - Create SQL Database and update connection string.

NOTE: Umbraco considers the database unconfigured if their is no valid connection string. If you manually add the new connection string to the web.config within Visual Studio, Umbraco will not correctly run the Umbraco setup wizard when first launched.

NOTE: If you want to force umbraco to re-run the setup wizard, you must delete the connection string and any value from 'umbracoConfigurationStatus' configuration element. See https://our.umbraco.org/wiki/reference/webconfig/

Link to Umbraco Tutorial for setting up content types, etc.

Step 4 - 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
  • Do not add StoreBuilder.Log4net or the standard log4net nuget package
  • StoreBuilder.Mvc
  • StoreBuilder.UmbracoConnector
  • StoreBuilder.Admin

Notes about Logging with log4net with Umbraco

Umbraco uses a special unsigned build of log4net instead of the public (signed) nuget feed for log4net.

In order to accommodate this, we have included an Umbraco specific StoreBuilder LogProvider implementation in the StoreBuilder.UmbracoConnector plugin which references the log4net assembly that ships with the umbraco.Core nuget package.

You should not reference StoreBuilder.Log4net or log4net nuget package directly and simply allow your umbraco.Core package to reference log4net.

Updating Newtonsoft.Json Assembly Bindings

Also note that StoreBuilder will always be compiled against the latest version of Newtonsoft.Json again using the latest published Nuget package. Similar to the above you may add an assembly binding to the web.config to upgrade any older references to use the newer assembly.

Sample web.config assembly binding configuration element:

<dependentAssembly>
   <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" />
   <bindingRedirect oldVersion="0.0.0.0-8.0.0.0" newVersion="8.0.0.0" />
</dependentAssembly>

Step 5 - Configure StoreBuilder to use Umbraco security provider for authentication

Add StoreBuilder section to your web project's web.config file.

Part A - Add configSection declaration:

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

Part B - Add <storebuilder> configuration element.

<storebuilder>
  <database connectionStringName="Storefront" />
  <logProvider type="StoreBuilder.UmbracoConnector.Logging.LogProvider, StoreBuilder.UmbracoConnector" />
  <securityProvider type="StoreBuilder.UmbracoConnector.Security.UmbracoSecurityProvider, StoreBuilder.UmbracoConnector" />
  <license accountKey="XXXX-XXXX-XXXX-XXXX" licenseKey="XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX" />
</storebuilder>

If you remove the logProvider configuration element, you will simply have no logging configured but StoreBuilder will run fine.

Step 6 - Add StoreBuilder namespaces to your Web.config for Razor views

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

<configuration>
  <system.web.webPages.razor>
    <pages pageBaseType="System.Web.Mvc.WebViewPage">
      <namespaces>
        <add namespace="StoreBuilder" />
      </namespaces>
    </pages>
  </system.web.webPages.razor>
</configuration>

Step 7 - 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.

In your Views folder, add a new folder called 'StoreBuilder'. Then add a new Razor view in the StoreBuilder folder named 'PageWrapper.cshtml'.

As a minimum this template may appear as follows:

@model StoreBuilder.Content.Results.PageContentResult
@Html.Raw(Model.Body)
@section scripts{
    @Html.RenderScripts(Model.ThemeResourceArea)
}

Step 8 - Create a /themes folder for your StoreBuilder themes

StoreBuilder will be 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.

For more information see StoreBuilder ThemeEngine.

Step 9 - Secure the /storebuilder project path

If you installed the StoreBuilder.Admin nuget package, it will have added the StoreBuilder folder to your web project which contains an admin portal for StoreBuilder. All the API 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.

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