Wed, 02/03/2021 - 13:43 By Stéphan Drouard
TypeScript

Dynamics 365 TypeScript Web Resource

Presentation

What is Typescript?

Typescript is an open-source language developed and maintained by Microsoft. It is a strict syntactical superset of JavaScript (that means that every piece of Javascript code can be used in Typescript). The typescript is transcompiled in Javascript and so can be used by any browser. The file extension is .ts.

In dynamics CRM, Typescript is used to develop component such as PCF or to create web-resources.

For PCF, you can go to read this article to learn how to create your first PCF.

In this article, we will develop a very simple web resource that can be used in dynamics 365.

When it is done, you can use Fiddler to easily debug your new control. Everything is explained in this other chronicle.

Your first Typescript Web-resource

In the following tutorial, we will create a simple web-resource using typescript that will display a field into a simple notification on a form. 

Prerequisites

First you will need to install the following:

Initialize the project

First, create a folder where you want that will contain the project.

Then after installing npm, open a command prompt and navigate to your newly created folder (using the command cd)

One little tips on Windows to open a command prompt directly in your folder:

  • Navigate to your folder
  • type cmd in the search and type enter

Dynamics 365 TypeScript Web Resource

Once the command prompt is opened, execute the following command:

npm init

You will be asked some information about your project such as the package name, version, etc....

Dynamics 365 TypeScript Web Resource

By typing Yes, a file package.json will be created on your folder.

Now we have to install typescript in the project:

npm install -g typescript

Dynamics 365 TypeScript Web Resource
 

Then, we need two folders

  • src: that will contain every source files
  • dist: that will received the transcompiled file

You can create them directly from Visual studio or by using the following command:

md src
md dist

Dynamics 365 TypeScript Web Resource

At this point, your folder should contain these files:

Dynamics 365 TypeScript Web Resource

We can start using Visual Studio. Open it and open a local folder.

4.5

Then create the tsconfig.json at the root of the project that will contain the configuration to well transcompiled the typescript:

{
	"compilerOptions": {
		"module": "ES6",
		"noImplicitAny": true,
		"removeComments": true,
		"preserveConstEnums": true,
		"outDir": "dist",
		"sourceMap": true,
		"moduleResolution": "node"
	},
	"include": [
		"src/**/*"
	],
	"exclude": [
		"node_modules",
		"**/*.spec.ts",
		"dist"
	]
}

111

As you can read, when compiling, it will take every files from the src folder, and save the transcompiled files into the folder dist.

Now your environment is set up and we can start developing our web-resource.

Develop your web-resource

As explained, every code must be created into the src folder.

Let's create a typescript file containing the following code:

class MyForm {
    static OnLoad(executionContext: any) {
        const formContext = executionContext.getFormContext();

        let attrContactName: Xrm.Attributes.StringAttribute;
        attrContactName = formContext.getAttribute('firstname').getValue();

        formContext.ui.setFormNotification("My Typescript is now loaded!: this is the firstname:" + attrContactName, "INFO", "ts-msg");
    }
}

The code is quite simple:

We have a class named MyForm containing one function: OnLoad. These names are important as we will use them to call the right function in the CRM.

The OnLoad function will do several actions:

  • First, he will get the form context. We will use the formContext variable to access the different part of the form.
  • The two next line will get the value of the text field named "firstname"
  • The last line will display a notification at the top of the form

Once you code is ready, we will have to transcompile the typescript files. To do so, go back to your command prompt and execute the following:

tsc

33

Your dist folder should now contain the generated javascript file that will be imported in dynamics 365.

44

The next stage will be to deploy your web-resource on dynamics 365.

Deploy your web-resource through the Dynamics 365 interface

Now we have a proper javascript file to import, let's open your dynamics 365 environment.

Navigate to your customization screen, and select the form where you want to apply your web-resource.

In the below example, I chose the out-of-the-box contact form. Go on the Form Properties:

77

On the form properties popup, click on Add 

9.2

Now you can search for an existing resource or, in our case, create a new one by clicking on New:

9.6

Fill in the resource form like below and upload your myForm.js file:

10

After saving and publishing, close this window. In the previous screen, you can now select your newly created resource and click on Add

9.6

Now we will add the event handler:

9.8

On the next popup, we will have to give some information about our new function:

10.5

The Function must be the concatenation of the class and the name of your function separated by a dot -> MyForm.OnLoad

We have to tick the checkbox Pass execution context at first parameter because we need it to get the firstname value

If you wish, you can also send a list of parameter (like fields) to your function. In this case, add the name of the desired fields separated by comma into the last textbox. For example, "firstname", "lastname". In our example, let it blank.

Click on Ok.

your final windows should be like below:

11

Now you have to save the form, and publish all customization.

Once done, go on a contact record, and normally, your notification should be display at the top of your form:

6

You know now how to develop a typescript web-resource and how to deploy it on your dynamics 365 instance.

If you need to do some notifications, just change your code, re-transcompile and modify your current web-resource. 

If the web-resource already exists, you will have to only copy the content of your generated javascript file.

88

If you want to avoid deploying your control every time you want to test it, you can use Fiddler.

If you want to know more about it, just click here to access another Chronicle about that! 

 

Simplify the way to code using Intellisense with XrmDefinitelyTyped

The main slowdown when developing a webcontrol is that you don't know your CRM model by heart.

That's why a tool like the XrmDefinitelyTyped exist! It will allow you to use an Intellisense to easily find attributes names of your entites.

First we need to install it.

Open your Visual Studio and right click on your project -> Manage Nugets packages...

And Search for the Delegate.XrmDefinitelyTyped, and install it.

2

 

When the installation has finished, a new folder is created in your project -> XrmDefinitelyTyped.
In this new folder, you will first have to set the config file.
3

In my case, I have to use the method OAuth to connect my CRM. For that, I had to create a new App in my Azure Portal. You can read the first step of this tutorial to do it. 

4

The entities setting must contain all the entity you're going to use in your scripts.

When you have filled in your configuration, launch the XrmDefinitelyTyped.exe to generate the TypeScript declaration if you're using Windows. You can also execute the PowerShell script Run.ps1.
If it works, you should have the below result:

5

BEWARE: On my case, after created the new App in Azure Portal, I had this error after running the script:
6

In this case, I had to Grant admin consent in your Persmission API in Azure Portal.

XrmDefinitelyTyped

After this consent, you should be able to run your script properly. It will create two folders:

  • typings: contains every definition of your entities: attributes and controls
  • src: contains the js script used for the intellisense

Include this two folders to your project

XrmDefinitelyTyped

You're now ready to use the intellisense. Let's create a new Typescript script into your project.

As my script is supposed to be used on the Main form of the contact entity, I create a new variable Form pointing on the generated class. Then, you could use the intellisense.

9This intellisense will make your dev's life much easier !!!

Now that's your turn ! Enjoy !

Dynamics 365 TypeScript Web Resource

Add new comment

Image CAPTCHA
Enter the characters shown in the image.