How to access Retail Server in managed code.

While building an application, for instance Point of Sale or Online Store, which interacts with AX you can leverage Retail Server (RS) to access data and perform actions. RS is ODATA Web Endpoint hosting CRT and therefore making it possible to access CRT from anywhere.

Since it is ODATA Service you can build any client which talks HTTP to make a request to it. At the same time there is a component, called Retail Server Proxy which helps a developer to focus on business needs and provides simple strongly typed way to access RS. There are several types/flavors of the proxy, but this article focuses on the type which should be used by Server Side and Native Client applications.

From authentication point of view RS can be accessed in 3 different ways:

C1 - is a context used by such applications like Point Of Sale where calls to RS are done on behalf of an Employee.

C2 - is a context used by such applications like Online Store, in this case a call is done in context of a Customer who is in front of the application (browser, native, ...).

Anonymous  - where a user doesn't have to authenticate and is applicable to the same types of applications as for C2 case above. This way of accessing RS is being demonstrated by this article.

When client apps want to consume RS as C2 or Anonymous they have to specify a Channel the calls should be bound to, to achieve that RS requires a HTTP header oun which should correspond to an Operating Unit Number of the channel. It can be found in AX UI:

Once you know what Operating Unit Number you need you can create an instance of class RetailServerContext by providing the OUN and a URL pointing to RS:

RetailServerContext context = RetailServerContext.Create(
    new Uri(ConfigurationManager.AppSettings["RetailServerRoot"]),
    ConfigurationManager.AppSettings["OperatingUnitNumber"]);

Then you need to create an instance of the factory which will be used to retrieve types which will help you to work with RS by leveraging high level strongly typed methods without having any ODATA knowledge, this is how the factory is instantiated:

ManagerFactory managerFactory = ManagerFactory.Create(context);

At this point we have a factory capable of creating any type of supported managers, for instance, if I need to work with Carts I use ICartManager, if with products - IProductManager and so on. The call below gets an instance of the class implementing ICategoryManager:

ICategoryManager categoryManager = managerFactory.GetManager<ICategoryManager>();

and finally you can now load the categories to render the hierarchy:

PagedResult<Category> categories = await categoryManager.GetCategories(channelConfiguration.RecordId, new QueryResultSettings { Paging = new PagingInfo { Skip = 0, Top = 100 } });
 
 
 

You can combine as many calls from different managers as you need for your specific scenario, for instance, in order to complete the above code we would first need to know the channel's RecordID which can be done by leveraging IOrgUnitManager.GetOrgUnitConfiguration():

IOrgUnitManager orgUnitManager = managerFactory.GetManager<IOrgUnitManager>();
ChannelConfiguration channelConfiguration = await orgUnitManager.GetOrgUnitConfiguration();

 In order to demonstrate all this together we could create simple WPF application (this sample app is primitive and can be done better but the purpose of this specific article is to give you an idea how to consume Retail Server Proxy with minimal distraction):

1. Create new WPF project in Visual Studio 2015: File->New->Project->Visual C#=>Windows->WPF Application
2. Add references to  Microsoft.Dynamics.Commerce.RetailProxy.dll and Microsoft.OData.Client.dll which could be found (I am referencing to LCS VM) at J:\RainMainStab\<Version>\retail\Services\RetailStorefront\Code\bin
3. Modify the content of MainWindow.xaml.cs with the content of MainWindow.xaml.cs referenced later in this article
4. Do the same as above for MainWindow.xaml and App.config

When you run the application you should see something like this:

Below is the content of the files mentioned above (please remove those numbers inside the code - they, by some reason, were put there by the code editor used to prepare this post).

MainWindow.xaml.cs:

using Microsoft.Dynamics.Commerce.RetailProxy;
using System;
using System.Configuration;
using System.Windows;
 
public partial class MainWindow : Window
{
    readonly ManagerFactory managerFactory;
    public MainWindow()
    {
        // Creating an instance of RetailServerContext by supplying Retail Service URL And Operating Unit Number.
        RetailServerContext context = RetailServerContext.Create(
           new Uri(ConfigurationManager.AppSettings["RetailServerRoot"]),
           ConfigurationManager.AppSettings["OperatingUnitNumber"]);
 
        // Creating a factory based on RetailServerContext.
 
        managerFactory = ManagerFactory.Create(context);
 
        InitializeComponent();
    }
 
    protected override async void OnInitialized(EventArgs e)
    {
        base.OnInitialized(e);
 
        // Getting a channelID.
        IOrgUnitManager orgUnitManager = managerFactory.GetManager<IOrgUnitManager>();
        ChannelConfiguration channelConfiguration = await orgUnitManager.GetOrgUnitConfiguration();
 
        // Loading categories.
        ICategoryManager categoryManager = managerFactory.GetManager<ICategoryManager>();
        PagedResult<Category> categories = await categoryManager.GetCategories(channelConfiguration.RecordId, new QueryResultSettings { Paging = new PagingInfo { Skip = 0, Top = 100 } });
 
        // Binding categories to UI element to be displayed there.
        listView.ItemsSource = categories;
    }
}

MainWindow.xaml

<Window x:Class="MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <ListView x:Name="listView">
        <ListView.View>
            <GridView>
                <GridViewColumn Header="Category Name" DisplayMemberBinding="{Binding Name}" />
            </GridView>
        </ListView.View>
    </ListView>
</Window>

App.config (don't forget to replace PutYourServerNameHere with your actual server name)

<configuration>
  <appSettings>
    <add key="OperatingUnitNumber" value="068" />
    <add key="RetailServerRoot" value="https://PutYourServerNameHere.cloudax.test.dynamics.com/Commerce" />
  </appSettings>
</configuration>

Note that Microsoft.Dynamics.Commerce.RetailProxy.dll, for the C2 scenario described in this article, requires the following DLLs at runtime:

Microsoft.Dynamics.Commerce.Runtime.Entities.dll
Microsoft.OData.Client.dll
Microsoft.OData.Core.dll
Microsoft.OData.Edm.dll
Microsoft.Spatial.dll

Newtonsoft.Json.Portable

So, make sure they are available for the application (all of them are available on the VM) at runtime. If you follow the steps above they will be automatically copied while those 2 references are being added.

See Basics of building native client capable of C2 authentication with Retail Server to find out how to work with Retail Server in context of a Customer (versus Anonymous which was described in this article).