Published by Oliver Heywood
March 10th, 2021
This guide provides step-by-step instructions to stand up a hosted middleware API using a specific technology stack. It is intended for readers with a developer background, but who may not be familiar with these specific tools.
This guide can also be found the github for dotnet-catalyst-examples.
Developers building OrderCloud ecommerce apps often use a server-side project for a variety of features. For example, secure integrations with 3rd parties like payment processors, scheduled jobs that sync data like product imports, custom event triggered emails, and others. Its almost certain your ecommerce solution will require middleware.
Before beginning you will need an Ordercloud account and an Azure account. You should register for both before continuing. You will also need these free tools installed on your local machine - the .NET Framework, the .NET Core 3.1 runtime and Visual Studio 2019.
Pull down starter code in the dotnet-catalyst-examples repository.
git clone https://github.com/ordercloud-api/dotnet-catalyst-examples
Get this code into your own version control system.
Your middleware API will need stored settings such as Ordercloud API Client credentials. We recommend storing them in Azure App Configuration. Then you can access one group of settings for hosted apps and local debugging. Follow these steps.
settings.OrderCloudSettings.ClientSecretwould have key
Repeat these steps, starting with creating a new App Configuration resource in Azure, for each of your environments (e.g. Test, Stage, Prod).
Open the project in Visual Studio 2019 and add the connection string as an environment variable in a new debug profile. Do this by right clicking the WebApi project and go to Properties > Debug > New > Environment Variables. Use
APP_CONFIG_CONNECTION as the key.
In Visual Studio 2019, select the project Catalyst.Api, and select the new debug profile ("Staging" in the image) you created with the connection string. Click the green arrow.
https://localhost:5001 should pop up in your browser with route documentation for the starter API. Make a GET request to https://localhost:5001/api/env and you should see some of the settings you created in Azure.
You will need to create a new App Service resource in azure. Then add an app setting for
APP_CONFIG_CONNECTION in the Configuration tab the same way you did locally in Visual Studio. Once that is done, you're ready to deploy code. Deploying is its own devops discipline. For the quick and dirty purpose of getting started you can deploy directly from Visual Studio. However, a CI/CD deployment tool like Azure Devops can greatly improve your deploy processes.
Azure Devops is our recommended approach. This project includes a azure-pipelines.yml config that specifies an Azure Devops build pipeline. For more info on these configs, see here. Modify line 8 of azure-pipelines.yml with your Azure App Service name and push that changes to the branch you want to deploy. Then, in Azure Devops create new build pipeline. Specify your git repository and Azure Devops should find deploy.yaml and handle the pipeline set up.
After the pipeline has run and been released, you should have a working hosted API! Navigate to the url specified on the App Service overview tab to confirm. You should see the same behavior you saw locally.