Xrm TypeScript @types/xrm

First, if you haven't taken a look at the video on Getting started using TypeScript with Dynamics 365, you should. Another good resource is the Visual Studio Code - Type Script page. Using TypeScript and tslint are extremely useful ways to make sure you are writing code that works and will continue to work.

Back in November, slightly after that great video was posted, I worked on updating the TypeScript definition for XRM to work with Dynamics Version 9.0. There were a lot of client-side APIs being deprecated and the TypeScript definition at the time didn't account for some of the larger changes in the pipeline, such as the deprecation of Xrm.Page. Working with Scott Durow, one of the maintainers of the xrm DefinitelyTyped definition, I submitted a number of changes aimed at providing a warning when you use a deprecated method.

However, not everyone that uses TypeScript has their solution setup to notify them of deprecations. When I do TypeScript development, I use Visual Studio Code (it's free).

If you aren't familiar with TypeScript or why to use it or when to use it, I suggest reading this article over at freecodecamp.org.

If you are familiar with TypeScript and Visual Studio Code, then you might just want to scroll down to see how I configure my environment. If you have suggestions on a better configuration, let me know! I'm always interested in improving how I do things.

Assuming you've never used Visual Studio Code and you haven't watched the video I mentioned above, you can start with an empty folder, I'll call mine Example.

1. Open Visual Studio Code

2. Click File, Open Folder, and open the Example folder.

3. Install npm.

a)  Hit CTRL-P to open the Command View

     b)  Type ext install npm and hit ENTER

     c)  Select npm and click install both of these:

4. Install TypeScript, tslint, and the xrm type definition

     a)  Hit CTRL-' (ctrl and single quote) to open the Integrated Terminal. You can also go to View > Integrated Terminal

     b)  Type npm install typescript and hit ENTER

     c)  Type npm install tslint and hit ENTER

     d)  Type npm install --save-dev @types/xrm and hit ENTER

5.   Initialize the package.

     a)  Hit CTRL-SHIFT-P to open the Command Palette

     b)  Type npm init and hit ENTER

     c)  Follow the prompts

You can hit enter all the way through it and just accept the defaults. You will be able to edit the package.json once it is created.

6.   Modify the package.json

     a)  Replace the scripts section with the following:

"scripts": {
   "build": "npm run lint && tsc --target es6 -p tsconfig.json",
   "lint": "tslint -p \".\"",
   "watch": "tsc --watch"
 },

 7. Create a tslint.json file containing:

{
    "defaultSeverity": "warning",
    "extends": [
        "tslint:recommended"
    ],
    "jsRules": {
    },
    "rules": {
        "no-console": false, //TODO: remove when done developing
        "no-namespace": false,
        "no-redundant-jsdoc": true,
        "unified-signatures": false,
        "class-name": true,
        "indent": [true, "spaces", 4],
        "max-classes-per-file":false,
        "max-line-length": [true, 250],
        "no-unnecessary-type-assertion": false,
        "quotemark": [true, "double"],
        "jsdoc-format": true,
        "no-unnecessary-generics": false,
        "no-empty-interface": false,
        "no-empty": false,
        "no-trailing-whitespace": false,
        "deprecation": true,
        "comment-format": [true, "check-space"],
        "align":[true, "statements", "members"],
        "one-line":[true, "check-catch", "check-finally", "check-else"],
        "no-reference":false,
        "no-conditional-assignment":false,
        "no-shadowed-variable": false
    },
    "rulesDirectory": []
}

Ok... those are my rules in tslint.json and it extends the tslint:recommended settings. The key one that makes the difference is setting deprecation to true.

8. Create a tasks.json file containing:

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
        "tasks": [
        {
            "type": "npm",
            "script": "lint",
            "problemMatcher": {
                "owner": "tslint",
                "severity": "warning",
                "fileLocation": ["absolute"],
                "pattern":[
                    {
                        "regexp": "^(WARNING|ERROR):(\\s+\\(\\S*\\))?\\s+(\\S.*)\\[(\\d+), (\\d+)\\]:\\s+(.*)$",
                        "severity": 1,
                        "file": 3,
                        "line": 4,
                        "column": 5,
                        "message": 6
                    }
                ]
            }
        }
    ]
}

9. Create a tsconfig.json file containing:

If you want to have your source files in one folder (src) and your compiled code in another (pub) then use this:

{
    "compilerOptions": {
        "target": "es5"
        ,"module": "commonjs"
        ,"lib" : ["es6", "dom"]
        ,"noImplicitAny": true
        ,"removeComments": true
        ,"preserveConstEnums": true
        ,"sourceMap": true
        ,"outDir": "./pub"
        ,"sourceRoot": "./src"
        ,"strictNullChecks": true
    }
    ,"include": [
        "src/**/*"
    ]
    ,"exclude": [
        "node_modules"
        ,"**/*.spec.ts"
        ,"**/*.d.ts"
    ]
    ,"compileOnSave": true
}

If you want them in the same folder (src), then use this:

{
    "compilerOptions": {
        "target": "es5"
        ,"module": "commonjs"
        ,"lib" : ["es6", "dom"]
        ,"noImplicitAny": true
        ,"removeComments": true
        ,"preserveConstEnums": true
        ,"sourceMap": true
        ,"strictNullChecks": true
    }
    ,"include": [
        "src/**/*"
    ]
    ,"exclude": [
        "node_modules"
        ,"**/*.spec.ts"
        ,"**/*.d.ts"
    ]
    ,"compileOnSave": true
}

10. Create the src folder and create a script file with a ts extension in the src folder.

For mine, I'm going to create a test.ts file containing:

const a: Xrm.Entity = Xrm.Page.data.entity;

There is an empty line after that line of code.

Unfortunately it doesn't tell me real time that I'm using deprecated libraries, although I see it on IntelliSense. What it does do, is when I run the Task npm: lint it puts the WARNING message in the terminal window, and when I go to problems, it shows the warning there as well. I can double click on the problem and go to the line and fix it.

There you have it, deprecated warnings in TypeScript and a configuration that will help get you started using the Xrm TypeScript Definition.