Extend Commerce Data Exchange - Real-time Service

Important

This topic applies to Dynamics 365 for Retail and Dynamics 365 for Finance and Operations.

This topic explains how you can extend Commerce Data Exchange (CDX) - Real-time service by adding extension methods to the RetailTransactionServiceEx class. Real-time Service enables retail clients to interact with retail functionality in real time.

To extend Commerce Data Exchange - Real-time Service, you create a new method in the RetailTransactionServiceEx class. This method must meet the following criteria:

  • The method must be a public static method.
  • The return value must be a container that has a length of 2 or more. The first element must be a Boolean value that indicates whether the method call was successful, and a string value that you can use for a comment or error message. The other items in the container can be of any type, and they can even be nested containers.
  • The method parameters must be one of the following primitive types:
    • Boolean
    • date
    • int
    • int64
    • str
    • guid
    • Real

Create and call a new extension method

  1. Start Microsoft Visual Studio.

  2. On the Dynamics 365 menu, click Model management > Create model.

  3. In the Create model dialog box, enter the following details.

    • Model name - Contoso
    • Model publisher - Contoso
    • Layer - USR (Select the relevant layer)
    • Version - 1.0.0.0
    • Model display name - Contoso
  4. Click Next.

  5. In the dialog box, select Select existing package, and then select Application Suite in the list.

  6. Click Next.

  7. Click Finish.

  8. In the New project dialog box, enter ContosoRetailTransactionServiceEx as the project name.

  9. Click OK.

  10. Right-click the project and select Add > New item. In the Add New Item window, select Class and enter the name of the class as ContosoRetailTransactionServiceSample.

To consume the CDX method in Commerce runtime (CRT) you must add the ExtensionOf attribute to your class, such as ExtensionOf(classStr(RetailTransactionServiceEx). This means that the class is extending from the RetailTransactionServiceEx.

  1. In the code editor, add the following code.
    [ExtensionOf(classStr(RetailTransactionServiceEx))]
    final class ContosoRetailTransactionServiceSample
    {
    }
  1. Inside the class, add a new method to do your custom logic. This is the method that you will call from CRT to do the custom logic.
    [ExtensionOf(classStr(RetailTransactionServiceEx))]
    final class ContosoRetailTransactionServiceSample
    {
        public static container SerialCheck(str _serialNum)
        {
            boolean success = false;
            str errorMessage;
            int fromLine;

            ttsbegin;

            try
            {
                if (_serialNum)
                {
                    // check whether the serial number exists

                    // Add your custom logic

                    errorMessage = "Serial number found";
                }
                else
                {
                    // Add your custom logic
                    success = false;
                    errorMessage = "Serial number not found";
                }
            }
            catch (Exception::Error)
            {
                error = RetailTransactionServiceUtilities::getInfologMessages(fromLine);
            }

            ttscommit;

            // Return sanitized error code.
            errorMessage = RetailTransactionServiceUtilities::getErrorCode(errorMessage);

            return [success, errorMessage, "Custom values"];
        }
    }
  1. In Solution Explorer, right-click the project, and then click Build.

After you've finished building your new extension methods, the project will be deployed.

Call the new method from the CRT

  1. In your commerce runtime (CRT), add a reference to the Microsoft.Dynamics.Commerce.Runtime.TransactionService.dll, if it hasn't already been added.
  2. Use the following sample code to call the new method.
        try
        {
            TransactionServiceClient transactionService = new TransactionServiceClient(request.RequestContext);
            ReadOnlyCollection<object> results = transactionService.InvokeExtensionMethod("SerialCheck", "123");
        }
        catch (HeadquarterTransactionServiceException exception)
        {
             string errorCode = (string)exception.HeadquartersErrorData.FirstOrDefault();
             RetailLogger.Log.ExtendedErrorEvent(errorCode, "Custom information", "method name");
             throw new CommerceException("Error resource id", "message");
        }

Note

In case of an exception in headquarters there is HeadquarterTransactionServiceException, which captures an exception and shows a user-friendly message in POS based on your scenario. If you want to log the exception, use the RetailLogger.Log class object to log the events.

  1. From the results object, you can read the response values from Real-time Service.

Note

The InvokeExtensionMethod method takes two parameters. One parameter is the Real-time Service method name, and the other is the list of parameters that should be used. The method name that is passed should be the same as the method name that you created in the ContosoRetailTransactionServiceSample class.