Guidelines for Apps

With great powers comes great responsibilities. As part of the curation process for Apps, we've created a list of guidelines you need to follow to ensure high-quality apps that can work across all the content management systems that Ucommerce integrates with and to ensure they work well alongside other installed apps as well.

The points mentioned in this section will be verified during the curation of apps.

Ucommerce App Template

Helps you get started on building e-commerce apps for Ucommerce. Set up a solution that makes it easy to hit the ground running.

Download the App Template here.

When the App Template is installed and the solution is created with the template. You can package the whole solution into an Ucommerce App by building the solution (located in /package in the solution root).

Ucommerce Sample App

To help you build your shiny new app, you can leverage the Ucommerce Sample App project. It contains examples of many of the most common extensions you might need and conventions you need to follow.

Component Ids

Unique component ids are important to avoid conflicts between apps unless you're specifically looking to override existing components of Ucommerce or others apps.

To avoid this your component ids should be prefixed with the app name, e.g. MyApp.MyComponent as opposed to MyComponent.

Ucommerce will pick up all the .config in the apps folder and therefore the ids of the components registered are very important, as you shouldn't override other app developer's components.

Dependencies

Ucommerce Dependencies

Your app package should not contain any Ucommerce assemblies as they will already be present on the system when your package is installed. Besides that, Ucommerce core tools like Castle Windsor or NHibernate should not be part of the package either.

CMS Dependencies

To make your app run across all CMSs supported by Ucommerce, your app must depend on the Ucommerce CMS abstractions instead of CMS's own implementations.

This also ensures that your app will work when additional CMS integrations are released. You're always welcome to contact us if you feel we're missing something obvious that will help you build your app.

Other Dependencies

To avoid dependency conflicts between your app and others, it is the best practice that all of your app's assembly dependencies are signed.

This is to ensure that .NET always pick the right assembly if the same assembly is present in multiple versions. Unsigned assemblies (with PublicKeyToken=null) are considered the same version regardless of the version number of the assembly.

Your app can't contain the assembly System.Web.Mvc.

Database Migrations

The installation process of an app in Ucommerce looks for database migrations in your app package and executes those against the database.

The App Installation pipeline looks for a folder called "Database" containing files with the following naming convention: AppName.SchemaVersion.sql, e.g. UcommerceDB.001.sql

Ucommerce will then use the schema version to make sure that it doesn't run a migration twice in upgrading scenarios and the migrations are run in sequential order based on the schema version.

Installing Your App

Go to the Ucommerce backend and open "Settings" -> "Apps" -> "Install App" in the menu tree to the left. Upload the app nupkg file and click the upload button. In the details page for the app click the install button.

When your app is installed, views, binaries, and configuration will be added to the Apps folder, e.g. uCommmerce/Apps/MyApp. As Ucommerce starts it will load the assembly dependencies of all the installed apps.

Your app may need to set up something for it to work, for this, there is an initialization pipeline, which is run when Ucommerce starts up.

Packaging Functionality

To make it easy for you to distribute your app, the sample app project can generate a NuGet package for you, by default the sample app project will generate a package everytime you build the project.

Documentation

The documentation for your app can be part of the NuGet package that you upload to the app store and the documentation will be hosted on our documentation site.

Support

Supporting your app is important because users will have questions about your app that won't be covered in your documentation, they will encounter bugs using your app and they will need your help, and Users will have suggestions to changes and extensions that you might not have thought about.