Enable the Ucommerce E-commerce API Outside the Web Context

More often than not you will leverage Ucommerce in a web context either via the Commerce Library XSLT extensions or through .NET directly.

In some cases though you might need to leverage the API outside a web context for automated integration between systems, for custom web services, or integration of Ucommerce functionality directly in other custom applications such as point of sale- or kiosk apps.

This article outlines the steps required to get the API going.

Reference Ucommerce Assemblies

First you need to reference the Ucommerce assemblies and their dependencies in your project.

You’ll need to add references to:

UCommerce.dll
UCommerce.Infrastructure.dll
UCommerce.Umbraco.dll
businesslogic.dll (Umbraco)
Castle.Core.dll
Castle.Windsor.dll
FluentNhibernate.dll
NHibernate.dll
Nhibernate.ByteCode.Castle.dll

Modify App.Config

Ucommerce needs some configuration to run. You’ll find examples of the relevant groups in web.config in your Umbraco installation. You’ll want to copy the commerce sectionGroup, connectionStrings, and commerce sections.

Add configSection Element

    
    
    <configSections>
        <sectionGroup name="commerce" type="System.Configuration.ConfigurationSectionGroup">
            <section name="runtimeConfiguration" type="UCommerce.Infrastructure.Configuration.RuntimeConfigurationSection, UCommerce.Infrastructure" />
        </sectionGroup>
    </configSections>

Add connectionStrings Element

    
    
    <connectionStrings>
        <add name="ucommerce" connectionString="Data Source=(local);Initial Catalog=Umbraco;integrated security=SSPI;" providerName="System.Data.SqlClient"/>
    </connectionStrings>

Add commerce Element

    
    
    <commerce>
        <runtimeConfiguration componentsConfigurationFile="Components.config" enableCache="false" cacheProvider="" />
    </commerce>

With all that in place your App.config file should look like this

    
    
    <configuration>
        <configSections>
            <sectionGroup name="commerce" type="System.Configuration.ConfigurationSectionGroup">
                <section name="runtimeConfiguration" type="UCommerce.Infrastructure.Configuration.RuntimeConfigurationSection, UCommerce.Infrastructure" />
            </sectionGroup>
        </configSections>
        <connectionStrings>
            <add name="ucommerce" connectionString="Data Source=(local);Initial Catalog=Umbraco;integrated security=SSPI;" providerName="System.Data.SqlClient"/>
        </connectionStrings>
        <commerce>
            <runtimeConfiguration componentsConfigurationFile="Components.config" enableCache="false" cacheProvider="" />
        </commerce>
    </configuration>

Add Configs to Application Folder

Components.config holds information about all the various subsystems in Ucommerce. Copy Components.config and Marketing.config from the website folder you installed Umbraco and Ucommerce in, e.g. c:\inetpub\Umbraco\Ucommerce\Configuration and copy them to your app folder.

Modify Components.config to Work Outside Web Context

The configuration files assume a web context so we’ll have to update them to work in a non web environment. Open up Components.config in your favorite editor and modify any life cycle with a value of “PerWebRequest” to “Thread”.

This tells Ucommerce to create an instance of the object once per thread as opposed to once per request, which oviously doesn’t make sense for what we’re trying to do.

Do the same for Marketing.config if you intend to use that in your application.

Remove Includes in Components.config

Be sure to remove includes in components.config, which refer to Presenters.config and XmlRenderings.config.

Summary

Leveraging Ucommerce outside a web site makes for some interesting use cases. Foremost is automated integration with other systems, but you could use this method to establish an offline Point of Sale or Kiosk-type system with a completely different frontend done in Windows Presentation Foundation for a rich in store experience.

Documentation