Integrating and using the uCommerce API from another application

So I just had to create and update some products in uCommerce from outside the application. This was done from a class library that was initiated through a test project. I had many bumps on the road but I finally got it working after reading several articles and forum posts - most were years old. So I want to give a complete example of what needs to be done for this to be working.

This guide assumes that you have a running uCommerce solution which you can copy a few things from. As far as I can tell there is currently no nuget package for creating integrations with uCommerce.

My uCommerce platform was created using Umbraco but I do not think there is any difference if you are using Sitecore - except for step one.

1 - Copying dll's

Yes I said copy. At first I tried using nuget packages. But the truth is that I ran into a lot of dependency problems and not all the dll's are in the nuget feed. Most forums about integrating with uCommerce also suggests that you copy the dll's (Yes I know this doesn't feel right!).

The following dll's needs to be copied:

Castle.Core.dll
Castle.Windsor.dll
ClientDependency.Core.dll
FluentNHibernate.dll
Iesi.Collections.dll
Infralution.Licensing.dll
interfaces.dll
log4net.dll
NHibernate.Caches.SysCache.dll
NHibernate.dll
Raven.Abstractions.dll
Raven.Client.Embedded.dll
Raven.Client.Lightweight.dll
Raven.Database.dll
ServiceStack.Common.dll
ServiceStack.dll
ServiceStack.Interfaces.dll
ServiceStack.ServiceInterface.dll
ServiceStack.Text.dll
UCommerce.dll
UCommerce.Infrastructure.dll
UCommerce.Pipelines.dll
UCommerce.Presentation.dll
UCommerce.Transactions.Payments.dll
UCommerce.Umbraco7.dll
UCommerce.Web.Api.dll
UCommerce.Web.Shell.dll
Umbraco.Core.dll
umbraco.DataLayer.dll
umbraco.dll
Umbraco.ModelsBuilder.dll
umbraco.providers.dll

If you do not want the hassle of finding these dll's you can just copy all the dll's from uCommerce - they are all found there.

I moved these dll's to a lib folder inside of my application and then referenced them. This way they are not lost when I clear the bin folder.

2 - Setup app.config

Now that you are running outside a web context there is a couple of entries that needs to be copied from a uCommerce web.config file to your app.config. These are the section groups commerce, and syscache and their configurations. If you do not have an app.config file you can create one by this:

Right click project -> Add -> New Item... -> Visual c# items -> Application Configuration File -> name it "app.config".

Once you have copied the section and configurations your app.config will look something like this:

<configuration>
  <configSections>
    <sectionGroup name="commerce" type="System.Configuration.ConfigurationSectionGroup">
      <section name="catalogConfiguration" type="UCommerce.Infrastructure.Configuration.CatalogConfigurationSection, UCommerce.Infrastructure" />
      <section name="runtimeConfiguration" type="UCommerce.Infrastructure.Configuration.RuntimeConfigurationSection, UCommerce.Infrastructure" />
      <section name="securityConfiguration" type="UCommerce.Infrastructure.Configuration.SecurityConfigurationSection, UCommerce.Infrastructure" />
    </sectionGroup>
    <section name="syscache" type="NHibernate.Caches.SysCache.SysCacheSectionHandler, NHibernate.Caches.SysCache, Version=4.0.0.4000, Culture=neutral, PublicKeyToken=6876f2ea66c9f443" requirePermission="false" />
  </configSections>
  <commerce>
    <runtimeConfiguration enableCache="true" cacheProvider="NHibernate.Caches.SysCache.SysCacheProvider, NHibernate.Caches.SysCache, Version=4.0.0.4000, Culture=neutral, PublicKeyToken=6876f2ea66c9f443" connectionString="(Auto)" />
    <catalogConfiguration defaultCultureCode="en-US" enforceCategoryNameUniquenessWithinCatalogs="true" />
    <securityConfiguration enable="true" />
  </commerce>
  <syscache>
    <!-- Cache catalog objects for 60 mins before refreshing -->
    <cache region="CatalogFoundation" expiration="3600" priority="5" />
    <cache region="MarketingFoundation" expiration="3600" priority="5" />
    <cache region="SecurityFoundation" expiration="3600" priority="5" />
    <cache region="Backend" expiration="3600" priority="5" />
  </syscache>
</configuration>

3 - Setup connection string

Inside your configurations that you just copied there is a connection string. Currently it's value is (auto). This has to be changed to the connectionstring that you are currently using. My connectionstring looks like the following:
connectionString="Server=localhost;Database=Umbraco_Ucommerce_Test;Integrated Security=true". You can find this in your web.config in your uCommerce solution.

Which means your runtimeConfiguration will look something like this:

<runtimeConfiguration enableCache="true" cacheProvider="NHibernate.Caches.SysCache.SysCacheProvider, NHibernate.Caches.SysCache, Version=4.0.0.4000, Culture=neutral, PublicKeyToken=6876f2ea66c9f443" connectionString="Server=localhost;Database=Umbraco_Ucommerce_Test;Integrated Security=true" />

4 - Copy pipelines and configurations

Time to copy some configurations for uCommerce. This is two folders that needs to be copied to our project. The folders are shown in the image below:
Image of configuration and pipelines folders in windows explorer
Once the are copied move them to your project so that they are in the root of it:
Image of configuration and pipelines folders in project
But you are not done yet! You will have to set the "copy to output directory" to "copy if newer" property for all the configurations for this to work. Mark all the configuration files right click and hit properties. it will show you a window like the one below. Don't forget to save it.

Image of properties in visual studio. With marked "copy if newer"

5 - Remove entries from components.config

There is a few configurations in the components.config file that needs to be removed or commented. These are the ones:

<!--<include uri="Presenters.config" />-->
<!--<include uri="XmlRenderings.config" />-->

And at the bottom of the file:

<!--<include-folder path="../Apps" />-->
<!--<include uri="Custom.config"/>-->

Actually I later found out that the two first includes I could leave be. But i see no harm in commenting them out since they are presentation.

6 - Remove "ServiceStackAppHost"

This feature is used for uCommerce web services. You will most likely not need this and it will cause an error. Go to core.config and remove the entry ServiceStackAppHost. It looks something like this:

<!-- Web services -->
<!--<component
id="ServiceStackAppHost"
service="ServiceStack.WebHost.Endpoints.AppHostBase, ServiceStack, Version=3.9.55.0" type="UCommerce.Web.Api.UCommerceAppHost, UCommerce.Web.Api"/>-->

Optional: Running this from a unit test and using Resharper?

If you are running a test project using NUnit/Resharper like I was. Then you will have to uncheck the following:
ReSharper -> Options -> Tools -> Unit testing -> Shadow-copy

That's it!

This took me a morning to figure out. As mentioned I found the information needed to do this scattered around the web. I hope this helps someone out there.

If you have any questions, things that this guide lacks, or any other information that might help someone with this problem - please write in the comments below! :)

The following errors might have gotten you here:

  • Castle.Windsor.Configuration.Interpreters.ConfigurationProcessingException' occurred in Castle.Windsor.dll but was not handled in user code: I encountered this issue when I did not do step 5 in my guide.
  • 'UCommerce.Web.Api.UCommerceAppHost, UCommerce.Web.Api' to a type. Assembly was not found. Make sure it was deployed and the name was not mistyped: I encountered this error when I did not do step 6 in my guide.
  • Additional information: Could not convert string 'UCommerce.Umbraco7.UI.Resources.ResourcesDependencyLoader: I encountered this when I forgot to copy one of the Umbraco dll's in step one.
  • An exception of type 'FluentNHibernate.Cfg.FluentConfigurationException' occurred in UCommerce.Infrastructure.dll but was not handled in user code
    Additional information: An invalid or incomplete configuration was used while creating a SessionFactory. Check PotentialReasons collection, and InnerException for more detail.
    : I got this exception when I forgot to copy the raven dll's from step one.