Installing TypeScript for Dynamics 365

This blog will guide you how to install TypeScript so you can write strongly typed JavaScript for Dynamics 365. It will include the setup of TypeScript and get your strongly typed classes generated.

Setting up the solution & project

First thing you do is to create a new solution in Visual Studio. Create a blank solution. If you already have a solution, you can skip this step.

After creating the solution, open windows explorer at the solution directory and add a new folder. Give it a good name, in example ‘Webresources’. All JavaScript and TypeScript files will be placed in this folder.

Go to visual studio and right click the solution. Go to add an existing website. Select the folder you just created. Using the approach of existing website is very beneficial because all files are automatically included in the project. Using TypeScript means you will generate many files, so automatic including of all files saves a lot of work.

Adding Typescript and generating your types

Adding TypeScript via NuGet

Next open nuget and add the package ‘Delegate.XrmDefinitlyTyped’. Some files have now been added to the project. You may need to refresh your solution explorer to see them.

Generating your types

In the XrmDefinitlyTyped folder, open and edit the config file. Set the URL and credentials to match your environment. Change out to ‘../ts/typings/XRM’ and change jsLib to ‘../js/lib’. Optionally change the solutions/entities to generate TypeScript for more forms/entitites. See the example below for my app config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="url" value="https://vermaat11.crm4.dynamics.com/XRMServices/2011/Organization.svc" />
    <add key="username" value="martijn@vermaat11.onmicrosoft.com" />
    <add key="password" value="" />
    <add key="out" value="../ts/typings/XRM" />
    <add key="solutions" value="" />
    <add key="entities" value="account, contact" />
    <add key="web" value="" />
    <add key="jsLib" value="../js/lib" />
  </appSettings>
</configuration>

If you are worried your credentials might end up in source control, you can reference another config file that contains the credentials. Have that file set to ignore in source control or refer to a path outside the repository. See https://docs.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/appsettings/appsettings-element-for-configuration 

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings file="appsettings.config">
    <add key="url" value="https://vermaat11.crm4.dynamics.com/XRMServices/2011/Organization.svc" />
    <add key="out" value="../ts/typings/XRM" />
    <add key="solutions" value="" />
    <add key="entities" value="account, contact" />
    <add key="web" value="" />
    <add key="jsLib" value="../js/lib" />
  </appSettings>
</configuration>

When you finish the app.config file, then run the ‘XrmDefinitlyTyped.exe’ in that folder. This will generate a bunch of TypeScript and JavaScript files. You may need to refresh your solution explorer to see the files. These files contain the strongly typed information about your implementation. You can look at them if you wish. These files are only used for development and will not be uploaded to CRM.

Configuring TypeScript

You create the configuration for TypeScript by adding a JSON file to the root of your project called ‘tsconfig.json’. After creating add  the following JSON to the file.

{
  "compileOnSave": true,
  "compilerOptions": {
    "outDir": "js",
    "target": "es5",
    "sourceMap": true
  },
  "include": [
    "./ts/**/*"
  ]
}

In case you decide to change the names of the folders, then you need to change the includes part of the Json. All folder that include typescript should be in this list.

Writing your first TypeScript

To start writing your first TypeScript, all you need to do is add a new TypeScript file to your project. You should do that in the ts folder. For this blog I add a script for the account form called ‘AccountFormScript.ts’. Here you can write the TypeScript you need in the form. 

namespace Vermaat.Account {

    var Form: Form.account.Main.Account;

    export function onLoad(executionContext: Xrm.ExecutionContext<any>) {
        Form = <Form.account.Main.Account>executionContext.getFormContext();
        Form.getAttribute("name").setValue("Default Name");
    }
}

When you save the TypeScript, a corresponding JS file will be automatically created or updated. You will deploy the JS file to Dynamics like you would do if you just wrote JavaScript. There is no need to deploy any of the (generated) TypeScript code.