How To Write a D365 Runnable Class (Job)

Often times as a developer you have the need to quickly write and run some x++ code in Microsoft Dynamics 365 for Finance and Operations. In this article, I will explain how to write a D365 runnable class (Job). These jobs can be used to quickly test and experiment with some code. As well as to correct some data in a way that cannot be done using the user interface.

What is a Runnable Class (Job)?

Before going further, what is a D365 runnable class (job)? Simply, put, it is just a class, like any other, except that the system generates a public static ‘main’ method for you. The method named ‘main‘ is the method that the system will run first, when it is told to run that class.

Instead of selecting ‘Runnable Class (Job)‘ as the type of object to create, you absolutely can just create an object of type ‘Class‘. Then, add a public static ‘main’ yourself. After doing so, there is no difference between the two.

Therefore, selecting ‘Runnable Class (Job)‘ is simply a way of telling the system to create a class, and generate the ‘main‘ method for you.

That said, it is important to understand that most classes do not have a ‘main‘ method. They just have methods with other names. And these methods are called from other places in code.

Create A Runnable Class (Job)

First, open Visual Studio and Create a new solution and project. Secondly, right click on the project, and select Add>New Item. Thirdly, select Dynamics 365 Items, on the left, and then select ‘Runnable Class (Job)‘ from the list. Fourthly, enter in a name. Finally, click the ‘Add‘ button to the add the job to your project.

Notice, the system will create a class with the name you typed in. Additionally, it will generate a main method, for you to put in your code.

Create A Class

To help understand that a D365 runnable class (job) is just a class with a main method, let’s create a class and add the main method ourselves.

First, open Visual Studio and Create a new solution and project. Secondly, right click on the project, and select Add>New Item. Thirdly, select Dynamics 365 Items, on the left, and then select ‘Class‘ from the list. Fourthly, enter in a name. Finally, click the ‘Add‘ button to the add the class to your project.

Notice, the system will create an empty class using the name you entered.

Now, copy and paste the main method into your class. The finally version should look like this.

class TestClass
{
    public static void main(Args _args)
    {
    }
}

See the Microsoft documentation for more information about classes.

There is not effectively no difference between the two classes, other than the name of the class.

However, the difference is really in the intended purposes. As developers when we create a ‘D365 runnable class (job)’ this means we intend for the code in the class to be run once, and perform a specific task. And therefore the job usually will not be given a menu item, or security objects. This means that only a system administrator can run the job. Additionally, they must know the name of the class to be able to run it.

Example Classes With Main Methods

To clarify further, a class has a ‘main‘ method when it will be called directly by a menu item or as part of a runnable class (job). A class that doesn’t have a ‘main’ method, still contains lots of useful methods. It is just that the methods are called by other objects in the system. Such as forms, reports, table methods, and other classes.

There are two most common places in the system that call a class with a ‘main‘ method.

First, a menu item can have properties that point to a class. This will cause the system to call the ‘main‘ method on the class. This is most often done when calling a ‘batch job’.

Secondly, a runnable class (job) will have a main method. This is where you put the code you wish to run directly.

Why Create A Runnable Class (Job)?

Ultimately, a developer could create a D365 runnable class (job) for any purpose. However, there are two most common reasons.

First, there may exist some data that you need to insert, update, or delete. While it is always best to use the user interface to make changes to the system, there are some cases, where that might just not be possible. In those rare cases, a developer can write x++ code to directly make changes to the underlying data. Again, this should not be done without careful research.

Unlike a batch job, that is designed to run on recurrence and continually clean up or process data, a ‘runnable class (job)’ should only target the specific data that needs to be corrected. After running the job once, it should never need to be run again. And therefore, it does not need to have a known menu item, which would allow users to call it again in the future.

The second reason a D365 runnable class (job) is written is for a developer to test some code. Instead of needing to create a menu item, and form with a button, that when clicked will call some x++ code, a runnable class (job) allows a developer to quickly run code.

As part of these articles, I regularly explain and demonstrate useful ways of writing x++ code. In the articles, I tell you to create a runnable class (job), because it is the fastest way to do this.

Example Runnable Class

Let us walk through a quick example of some code we can put in a D365 runnable class (job).

Add ‘Info(“Hello World!”);‘ to your job. This will print a message to the browser when the code is run. The final result will look like this.

class TestRunnableClass
{
    /// <summary>
    /// Runs the class with the specified arguments.
    /// </summary>
    /// <param name = "_args">The specified arguments.</param>
    public static void main(Args _args)
    {
        Info("Hello World!");
    }

}

Run The Runnable Class In Visual Studio

Now that we have finished writing the D365 runnable class, let’s run it in Visual Studio.

In Visual Studio, right click on the class in the solution explorer. Then select ‘Set as Startup Object’.

Notice, the name of the class will now show as ‘Bold’. This indicates to you that this class is set as the startup object.

Finally, click the ‘Start’ button in Visual Studio.

Assuming the code you have written compiles successfully, the system will open a browser and run the D365 runnable class (job).

Call The Runnable Class From A Browser

As we said before, one common purpose for writing a Runnable Class (Job) is to correct data in ways that cannot be done using the user interface. After writing this job, and promoting the code to a Production environment, you need to be able to run it. While you could create a menu item to call this job, it would require creating more objects that would likely only be used once. Instead, a user with ‘system administrator‘ permissions can run this job by entering in a specific URL into the browser.

To start, open your browser, and browse to your Microsoft Dynamics 365 for Finance and Operations URL.

Then, get the URL of the site, and write it down. It should look something like this:

https://rsmta-peter1234aos.cloudax.dynamics.com.cloudax.dynamics.com/?cmp=USRT&mi=DefaultDashboard

Next, we need to review three pieces.

First, verify that you are in the company where you wish to run the job. You can do this by checking the text in this section of the URL: ‘?cmp=USRT‘. If needed, change the letters to be the correct company.

Second, change ‘&mi=DefaultDashboard’ and replace it with ‘&mi=SysClassRunner‘. This tells the system to run a class.

Third, add the following text to the end of the URL: ‘&cls=<TheNameOfYourClass>‘. Replace <TheNameOfYourClass> with the name of your class. In the example above, it would be TestRunnableClass.

The final format of your URL should be:

https://<URL of your D365 environment>/?cmp=<YourCompany>&mi=SysClassRunner&cls=<TheNameOfYourClass>

https://rsmta-peter1234567aos.cloudax.dynamics.com/?mi=SysClassRunner&cls=TestRunnableClass

Finally, copy this URL into your browser, and hit enter. The browser will then run the D365 runnable class (job). You will see the message ‘Class ‘<TheNameOfYourClass>’ completed’ once your job has finished running.

Run The Job In Production

Recently, Microsoft provides a way to run these jobs in a Production environment without applying a package to Production. Applying a package requires that the environment be taken down for several hours. In this new approach, the job can be run in Production without any downtime. See my article on How to Run A D365 Job In Production.

Conclusion

As a reminder, a D365 Runnable class (job) is a class with a ‘main’ method, where a developer can put x++ code. By convention, these jobs typically do not have related menu items and security objects. And therefore can only be run by a user with the ‘system administrator’ role. While any code can be put in these jobs, usually, they contain code that is intended to be run once, and used to address a specific issue. Such as inserting, updating, or deleting data that cannot be done using the user interface.

Additionally, these jobs can be created by developers in a development environment, and used to quickly write and test some x++ code. Later, this code can be moved to a more conventional place. The D365 runnable class (job) provides for a very fast way for developers to run code.

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.