CommerceProxyGenerator

Proxy to consume Commerce APIs and entities

To consume the custom Commerce APIs, the commerce proxy tool generates proxy classes and interfaces for the external applications to consume the Commerce APIs in an easier way.

Commerce proxy and when to use it

External applications can use the proxy to interact with Commerce APIs, the Commerce proxy abstracts the Commerce APIs and the Commerce runtime (CRT) entities, request and response and generates interfaces/metadata for the external application to consume the Commerce API and entities in an easier way, like metadata generated by the .NET framework for consuming the supported web services. For example, to consume the custom entities or the Commerce APIs in the external applications either you can use the metadata generated by proxy tool or you can manually create all the entities and request/response metadata in the client applications and manual creation involves lots of additional overhead, because you may need to maintain, update, and duplicate the entities, manager, and request/response code in two places.

The Commerce proxy reduces this effort by automatically generating the proxy for all the custom entities and request/response operations that are added in Commerce APIs. The proxy tool generates the required interface and all the required metadata and abstracts the actual implementation. In that way, you can include the files in the extension projects, and can access the Commerce APIs and the entities by using the metadata and interface that are generated.

Proxy types

There are two types of proxy to support cross-platform scenarios:

• Typescript - POS and e-Commerce use the typescript proxy to access the Commerce APIs and CRT entities. Based on the application type, different types of typescript proxies are generated, for e-Commerce use TypeScriptModuleExtensions and for POS use typescriptextensions. Note: POS project automatically generates proxies based on the Commerce API project referenced.
• C# – The C# proxy can be used by an application which requires C# to consume the APIs, The POS uses the C# proxy when it's offline. (When the POS is offline, it communicates directly with CRT, without using Retail Server.)

Depending upon your application type, decide what type of proxy to generate, the packages consumed to generate the Typescript proxy and the C# proxy are different.

Sample proxy generator projects

In the sample, we created cs projects and added reference to the Microsoft.Dynamics.Commerce.Tools.ExtensionsProxyGenerator.AspNetCore package, Commerce runtime and Commerce API extension projects to generate the proxy. For C# proxy additionally consume the Microsoft.Dynamics.Commerce.Proxy.ScaleUnit package.

This sample demonstrates how to create proxies for your commerce runtime extension.

The sample consists of 3 projects:

1. TypeScriptProxyGenerator: Generates typescript proxies for a given dll. The dll generated from the 'CommerceRuntime' project is used as a sample. You can use a different dll in your project.
2. CSharpProxyGenerator: Generates C# proxies for a given dll. The dll generated from the 'CommerceRuntime' project is used as a sample. You can use a different dll in your project.
3. CommerceRuntime: Contains the entities and controller for the extension.

Building Sample

To build the sample, open and build the ScaleUnit solution.

E-Commerce Application

Consume the generated files from the TypeScriptProxyGenerator on your E-Commerce Application.

Once the solution is built successfully, validate if the following two files got generated in your TypeScriptProxyGenerator project:

1. 'DataService\DataActionExtension.g.ts': This file contains all the data actions extensions that can be used to call the APIs defined in your Commerce Runtime Controller.
2. 'DataService\DataServiceEntities.g.ts': This file contains all entity classes defined in your Commerce Runtime Extension.

Consume files in E-Commerce Application

Once the DataActionExtension.g.ts and DataServiceEntities.g.ts files are generated, you can manually move them to your E-Commerce App. Eg: "Msdyn365.Commerce.Online\src\actions\extensions".

You can also uncomment the 'CopyGeneratedContracts' target section in the TypeScriptProxyGenerator.csproj file to do this automatically for you.

Commerce C# Application

Consume the generated files from the CSharpProxyGenerator on your Commerce Application.