Create a Custom Service in D365

In the last article we looked at how to setup Postman to call D365 services. We called a simple existing service. In this article I will show you how to create a custom service in D365.

Unlike calling a Data Entity which can create or retrieve data from tables, services allow us to run code within Microsoft Dynamics 365. This is very useful if for example you need to retrieve a value that is not stored in a table. Or you would like to run a process, and return whether it was successful or not.

What Are the Steps?

In order to create a custom service in D365, there are several pieces we need.

1. We need a new class that is our ‘Request‘ object. The data we send in will be mapped to the variables in this class. Then we will use this class to run our operation.
2. We need a new calls that is our ‘Response‘ object. In our code we will set the variables in this class to contain whatever information we want returned to the calling program. D365 will then convert these values into JSON data.
3. We need a Service class. This is the class where we will put the code that will: a) read the data in our Request object, b) run some process, and then c) populate the Response object.
4. We need a Service object, that points to our Service class. This lets Dynamics 365 know that our class can be called by an outside system.
5. Lastly, we need a Service Group to put our Service object into.

Create the Request Class

When you create a custom service in D365, the Request class needs to have a variable for each piece of data you are sending into the system.

First, create a new class in Visual Studio. I named my ‘rsmTutRequestSimple’.

Next, add the Attribute [DataContractAttribute] just above the class declaration.

Add a variable. I named mine ‘dataAreaId’.

Finally, create a parameter method for that variable, and put the attribute [DataMember(“<The name of your Data>“)] above the method.

Your code should now look like this:

[DataContractAttribute]
class rsmTutRequestSimple
{
    private str dataAreaId;

    [DataMember("DataAreaId")]
    public str parmDataAreaId(str _value = dataAreaId)
    {
        if (!prmIsDefault(_value))
        {
            dataAreaId = _value;
        }

        return dataAreaId;
    }
}

Create the Response Class

The Response class needs to have a variable for each piece of information we would like to send back to the calling program.

First, create a new class in Visual Studio. I named mine ‘rsmTutReponse’.

Add the attribute [DataContractAttribute] just above the class definition.

Add variables that will contain information you want to return to the calling program. I created variables ‘success, ‘errorMessage’, and ‘debugMessage’.

Finally, create a parameter method for each of your variables. Put the attribute [DataMember(“<The name of your data>“)] above each method definition. The value you put as <The name of your data> will be the name of the JSON tag that is generated.

Your code should now look like this:

[DataContractAttribute]
class rsmTutResponse
{
    private boolean     success;
    private str         errorMessage;
    private str         debugMessage;

    [DataMember("ErrorMessage")]
    public str parmErrorMessage(str _value = errorMessage)
    {
        if (!prmIsDefault(_value))
        {
            errorMessage = _value;
        }

        return errorMessage;
    }

    [DataMember("Success")]
    public Boolean parmSuccess(Boolean _value = success)
    {
        if (!prmIsDefault(_value))
        {
            success = _value;
        }

        return success;
    }

    [DataMember("DebugMessage")]
    public str parmDebugMessage(str _value = debugMessage)
    {
        if (!prmIsDefault(_value))
        {
            debugMessage = _value;
        }

        return debugMessage;
    }

}

Create The Service Class

The Service class is the most interesting class when you create a custom service in D365. It is responsible for reading values from the Request object, running some process, then setting values on the Response object.

First, create a new class in Visual Studio. I named mine ‘rsmTutServiceSimple’.

Create a method in the class, named whatever you would like. I named mine ‘create’.

The method needs to take as a parameter which has a type of your Request object. And it needs to return a value which has a type of your Response object. So for example this:

public rsmTutResponse create(rsmTutRequestSimple _request)

Next, you can put whatever code you need to inside the method. In my example, I am reading the dataAreaId from the request object, and then I am storing the text “Hello World” in the response object.

public class rsmTutServiceSimple
{
    public rsmTutResponse create(rsmTutRequestSimple _request)
    {
        var response = new rsmTutResponse();
        changecompany(_request.parmDataAreaId())
        {
            try
            {
                response.parmDebugMessage("Hello World");
                response.parmSuccess(true);
            }
            catch (Exception::CLRError)
            {
                System.Exception interopException = CLRInterop::getLastException();

                response.parmSuccess(false);
                response.parmErrorMessage(interopException.ToString());
            }

            return response;
        }
    }
}

I also added a try catch block. If the process throws an error, I am storing the error message in the response object as well.

Create The Service Object

The Service object, exposes our Service class and allows it to be called by an outside system with the proper authentication. In Visual Studio, right click on your project, and select ‘Add New Item’. Then select ‘Service’.

Give the item a name. I named mine ‘rsmTutServiceSimple’

Open the object. Right click on it and select ‘Properties’

In the Properties window, set the ‘Class’ property with the name of the Service Class you created earlier. Mine is named ‘rsmTutServiceSample’. (The same as the service object). Also, set the ‘External Name’ property to the same value. You can change this to be whatever you want. But it is simpler if you leave it the same.

Now, Right click on the ‘Service Operations’ node, and select ‘New Service Operation’

Select the new node that is created, and in the Properties window set the ‘Method’ property to the name of the method in your Service class. I named mine ‘create’. Also set the ‘Name’ property to be the same. (You could change this to be something different. But it is simpler if you set it to be the same as the method name).

Create The Service Group

The Service Group is an object that can contain one or more services and is a way of organizing similar operations together.

In Visual Studio right click on the project and select Add>New Item. Select the ‘Service Group’ item. Then give your object a name. I named mine ‘rsmTutServiceGroupSimple’.

Open the new Service Group object, and right click on the main node. Select ‘New Service’ from the drop down.

Select the node that is created, and view the properties window. Set the ‘Name’ and the ‘Service’ properties to the name of your Service object. In my case, the name of my Service object is ‘rsmTutServiceSimple’.

Call The Service From Postman

You can view the previous article for detailed steps on how to use Postman to call the service. In this case the URL to call the service will be:

https://<D365 URL>/api/services/rsmTutServiceGroupSimple/rsmTutServiceSimple/create

Let’s break down this URL into it’s parts.

• https:// – This specifies we are making a secure call.
• <D365 URL> – This should be replaced by the URL used to access your D365 environment. For example: https://usnconeboxax1aos.cloud.onebox.dynamics.com
• api/services – This text tells D365 that we are calling a service.
• rsmTutServiceGroupSimple – This is the name of the service group we are calling.
• rsmTutServiceSimple – This is the name of the service we are calling.
• create – This is the name of the method we are calling on the Service class.

In this example the Postman body would look like this:

{
	"_request" :
	{
		"DataAreaId": "USRT"
	}
}

Conclusion

You have now performed the actions to create a custom service in D365 as well as call it! Great job! Now any outside system can call code inside of D365. This can be used by Microsoft Power Apps, Power Automate, Azure Logic Apps, other externals systems, and many more. Enjoy!

Peter Ramer

Peter Ramer is a part of the Managed Application Services team at RSM working on Microsoft Dynamics 365. He focuses on the Retail and Commerce industries. When he is not solving problems and finding ways to accelerate his clients' business, he enjoys time with his three kids and amazing wife.