DEV Community: Oliver Flint

D365 TypeScript Web Resources - Part 6 - Application Insights

Oliver Flint — Fri, 30 Apr 2021 22:00:00 +0000

Before you get stuck into this make sure you've checked out any previous parts to the series. Each part in this series follows on from the previous, so you may need to grab the code from the previous part if you haven't been following.

Application Insights

What is Application Insights?

Application Insights, a feature of Azure Monitor, is an extensible Application Performance Management (APM) service for developers and DevOps professionals. Use it to monitor your live applications. It will automatically detect performance anomalies, and includes powerful analytics tools to help you diagnose issues and to understand what users actually do with your app. It's designed to help you continuously improve performance and usability. It works for apps on a wide variety of platforms including .NET, Node.js, Java, and Python hosted on-premises, hybrid, or any public cloud. It integrates with your DevOps process, and has connection points to a variety of development tools. It can monitor and analyze telemetry from mobile apps by integrating with Visual Studio App Center.

https://docs.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview

Setup

First lets install the npm package(s):

npm install @microsoft/applicationinsights-web

Next we need to setup Application Insights in Azure. If you don't have an azure subscription you can signup for a free trial here.

Create an Application Insights Resource in Azure by following the steps here (you can stop at the bit where you copy the instrumentation key)

Now you have an app insights resource and the instrumentation key we are ready to go!

The Code

First we'll put together a little module that encapsulates a minimal setup of Application Insights API

import { ApplicationInsights } from "@microsoft/applicationinsights-web";

const init = () => {
  const appins = new ApplicationInsights({
    config: {
      instrumentationKey: "YOUR_KEY",
    },
  });
  appins.loadAppInsights();
  (window as any).d365ts_appinsights = appins;
  return appins;
};

export const appInsights = (window as any).d365ts_appinsights
  ? ((window as any).d365ts_appinsights as ApplicationInsights)
  : init();

Now, we can simply import our module

import { appInsights } from "./appinsights";

And start tracking page views

appInsights.trackPageView();

Or track exceptions

appInsights.trackException({
  exception: { message: "This is an error", name: "Onload Error" },
});

There are also other tracking functions trackMetric, trackEvent, trackTrace, etc.

Telemetry Initializer

One of the great things about the telemetry initializer is that it allow you to define some custom data/properties to include when tracking

appins.addTelemetryInitializer((item) => {
  const globalCtx = Xrm.Utility.getGlobalContext();
  item.data.Username = globalCtx.userSettings?.userName;
  item.data.UserId = globalCtx.userSettings?.userId;
  item.data.SecurityRoles = (globalCtx.userSettings?.roles as any)
    ?.getAll()
    ?.map((item) => item.name)
    ?.join("|");
  item.data.OrgUniqueName = globalCtx.organizationSettings?.uniqueName;
  item.data.Client = globalCtx.client?.getClient();
  item.data.ClientState = globalCtx.client?.getClientState();
});

To have this included in all tracking we can add it with the module...

const init = () => {
  const appins = new ApplicationInsights({
    config: {
      instrumentationKey: "d5656791-01e1-4d2e-9172-08fd79545a97",
    },
  });
  appins.loadAppInsights();
  appins.addTelemetryInitializer((item) => {
    const globalCtx = Xrm.Utility.getGlobalContext();
    item.data.Username = globalCtx.userSettings?.userName;
    item.data.UserId = globalCtx.userSettings?.userId;
    item.data.SecurityRoles = (globalCtx.userSettings?.roles as any)
      ?.getAll()
      ?.map((item) => item.name)
      ?.join("|");
    item.data.OrgUniqueName = globalCtx.organizationSettings?.uniqueName;
    item.data.Client = globalCtx.client?.getClient();
    item.data.ClientState = globalCtx.client?.getClientState();
  });
  (window as any).d365ts_appinsights = appins;
  return appins;
};

You may even want to add a second telemetry initializer for adding some data from the form context

export const addFormContextTelemetryInitializer = (
  formContext: Xrm.BasicPage
) => {
  appInsights.addTelemetryInitializer((item) => {
    item.data.EntityName = formContext.data?.entity?.getEntityName();
    item.data.EntityId = formContext.data?.entity?.getId();
    item.data.FormName = formContext.ui?.formSelector
      ?.getCurrentItem()
      ?.getLabel();
    item.data.FormType = formContext.ui?.getFormType();
  });
};

Now when the form loads we can add the form context initializer

addFormContextTelemetryInitializer((formContext as unknown) as Xrm.BasicPage);

What's it look like!?

Ok ok! Here is what all that lovely data will look like in Azure Application Insights...

First we have the results in the transaction search:

Then after selecting a result we can see the detail:

And there we have it!

That's all folks!

I hope that has been useful!

You can download a copy of the source code for this blog post here

Thanks for reading.
Ollie

D365 TypeScript Web Resources - Part 5 - Unit Testing

Oliver Flint — Fri, 22 Jan 2021 00:12:23 +0000

Unit Tests? But my code is next level!

Nowadays there is no excuse to not unit test your code. It's becoming easy and more valuable, so don't not do it!

In this post I'm going to provide a basic guide to get you started with unit tests and typescript webresources for Dynamics 365... err Dataverse... err Power Apps... or whatever we are calling it today!

Configure Jest

First of all lets install the jest npm packages we require:

npm install jest @types/jest ts-jest --save-dev

Next we'll create a basic config via:

npx ts-jest config:init

Finally we'll install xrm-mock and sinon to help us a little:

npm install xrm-mock sinon @types/sinon --save-dev

Ensure your package.json is setup to run jest via npm run test makes sure you have the following script defined:

"scripts": {
    "test": "jest",
    ...

Now we are ready to write some tests! :-D

Writing our first test

Create a folder in the root of the project called "tests" and then create a new file called "first.test.ts".

Paste the following into the new file:

import { NavigationStaticMock, XrmMockGenerator } from "xrm-mock";
import * as sinon from "sinon";
import { Pointless } from "../src/sample";
describe("sample test", () => {
  describe("Pointless", () => {
    test("Should display alert", () => {
      XrmMockGenerator.initialise();
      const stub = sinon.stub(
        NavigationStaticMock.prototype,
        "openAlertDialog"
      );

      const msg = "a pointless test message";
      Pointless(msg);

      expect(stub.called).toBeTruthy();
      expect(stub.calledOnce).toBeTruthy();
      expect(stub.firstCall.args[0].text).toBe(msg);
      expect(stub.firstCall.args[0].title).toBe("A Pointless Message");
    });
  });
});

Lets have a closer look at the test...

I'm not going to tell you how to use jest and sinon as these already have great documentation of their own.

First we'll "Arrange" our test...
Initialise our global Xrm object:

XrmMockGenerator.initialise();

Stub openAlertDialog(). As I expect you know, openAlertDialog() displays a dialog in D365. Stubbing the function enables the code to execute without error given we don't have the UI and we can then test/assert the stubs properties etc.:

const stub = sinon.stub(NavigationStaticMock.prototype, "openAlertDialog");

Now lets "Act" by calling our function:

const msg = "a pointless test message";
Pointless(msg);

Finally we'll "Assert" our tests
Has the openAlertDialog() stub been called?:

expect(stub.called).toBeTruthy();

The openAlertDialog() stub should have only been called once:

expect(stub.calledOnce).toBeTruthy();

Was the openAlertDialog() stubs alertStrings.text parameter as expected?:

expect(stub.firstCall.args[0].text).toBe(msg);

Was the openAlertDialog() stubs alertStrings.title parameter as expected?:

expect(stub.firstCall.args[0].title).toBe("A Pointless Message");

It's quite a rudimentary test but it demonstrates the basics.

So, lets run the tests!

Execute npm run test

The output should look something like this:

> jest

 PASS  tests/first.test.ts (10.199 s)
  sample test
    Pointless
      √ Should display alert (34 ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        10.811 s
Ran all test suites.

Fancy a crack at mocking the WebApi?

So, we've written a function that calls Xrm.WebApi, but when we try to test that function it'll fail as the Api doesn't exist... We need to mock the Api call with a stub.

A function that calls Xrm.WebApi...

First of all we'll create a function called CreateAccount (yep you guessed it, it'll create an account!)

export async function CreateAccount(account: any): Promise<Xrm.Lookup> {
  const response = await Xrm.WebApi.createRecord("account", account);
  return response;
}

It's a simple example but it should get the point across.

Testing a function that calls Xrm.WebApi

So here's the test. This can be added to the first.test.ts inside describe("sample test", () => {

It's not a great example, but it should demonstrate how we can stub the WebApi ;-)

describe("CallTheWebApi", () => {
  test("Should return a valid Xrm.Lookup", async () => {
    const stub = sinon
      .stub(WebApiMock.prototype, "createRecord")
      .withArgs("account", sinon.match.object)
      .resolves({
        entityType: "account",
        id: "9bce6686-48d5-4d6f-85a2-da0eea30984d",
        name: "Jest Account",
      } as LookupValueMock);

    const result: LookupValueMock = await CreateAccount({
      name: "Jest Account",
      creditonhold: false,
      address1_latitude: 47.639583,
      description: "This is the description of the sample account",
      revenue: 5000000,
      accountcategorycode: 1,
    });

    expect(stub.calledOnce).toBeTruthy();
    expect(result).toBeTruthy();
    expect(result.name).toBe("Jest Account");
  });
});

You'll notice the absence of XrmMockGenerator.initialise();. I moved this to the beforeEach within describe("sample test", () => { like so

describe("sample test", () => {
  beforeEach(() => {
    XrmMockGenerator.initialise();
  });
  ...

Lets have a closer look again

First we stub the createRecord function via the WebApiMock object provided by xrm-mock

const stub = sinon.stub(WebApiMock.prototype, "createRecord");

Then we define the arguments for that stub (optional). Notice the use of the sinon.match to match an object.

  .withArgs("account", sinon.match.object)

NOTE If we didn't do the above the stub would be executed for all calls to Xrm.WebApi.createRecord

Finally we tell the stub what we would like it to return, or in this case as it's a async/promise we tell it what to resolve.

  .resolves({
    entityType: "account",
    id: "9bce6686-48d5-4d6f-85a2-da0eea30984d",
    name: "Jest Account",
  } as LookupValueMock);

OK OK! Lets run the bloody tests!

Execute npm run test and you should now get something similar to the following output

> jest

 PASS  tests/first.test.ts
  sample test
    Pointless
      √ Should display alert (7 ms)
    CallTheWebApi
      √ Should return a valid Xrm.Lookup (2 ms)

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        2.34 s, estimated 27 s
Ran all test suites.

That's all folks!

Remember to take a look at jest, sinon, and xrm-mock

I hope that has been useful!

You can download a copy of the source code for this blog post here

In the next part we'll take a look at how we can integrate Azure Application Insights into the Webresources.

Thanks for reading.
Ollie

PCF WebApi execute

Oliver Flint — Wed, 10 Jun 2020 23:05:42 +0000

The PCF WebApi execute method is lurking in the background!

Yep, missing from the docs and the type definitions but it's there and it works!

execute

(context.webAPI as any).execute(request).then(successCallback, errorCallback);

see the execute Client API docs for more info

executeMultiple

(context.webAPI as any)
  .executeMultiple(requests)
  .then(successCallback, errorCallback);

see the executeMultiple Client API docs for more info

Enjoy!
Ollie

Disclaimer!
Some of the tips 'n' tricks in the PCF Tips 'n' Tricks category are to be used with caution. Although they may work at the time of writing, they may or may not be officially supported by Microsoft

PCF primary entity info

Oliver Flint — Wed, 10 Jun 2020 18:59:36 +0000

Getting the primary entity info

At present the PCF Template provided by the Power Apps Cli gives us lots of opportunity and scope to improve functionality, but the type definitions are missing some objects that are present api. Now this could be for many reasons, one being support. Anyway, I'm a rogue so here is one I've already used a lot!

The entity id (guid)

const entityId = (context.mode as any).contextInfo.entityId;

This is the equivalent of the following in the Client API

const entityId = formContext.data.entity.getId();

The entity type (entity logical name)

const entityTypeName = (context.mode as any).contextInfo.entityTypeName;

This is the equivalent of the following in the Client API

const entityTypeName = formContext.data.entity.getEntityName();

The record name (primary attribute value)

const entityTypeName = (context.mode as any).contextInfo.entityRecordName;

This is the equivalent of the following in the Client API

const entityTypeName = formContext.data.entity.getPrimaryAttributeValue();

Hopefully this will be helpful to some of you!

Thanks for reading
Ollie

PCF <-> Form Communication

Oliver Flint — Sat, 06 Jun 2020 02:12:12 +0000

Communication

Communication, It's one of the single most important "things" in EVERYTHING!

So why am I finding it so difficult to have my PCF control and Form script talk to each other? Maybe I am missing something but I believe the only "OOTB" method for the two to communicate is via a bound field/control...?

I want better comms!

Yep, I want a better way for my control and form to communicate without having to bind multiple fields and in some cases create new fields just to support this communication.

Here's what I came up with...

Custom Events

Using custom events we can send messages back a forth between the form and the PCF control.

The basic example I'll be using for this blog post is linked to the issue where we are not able to bind to the OOTB address fields on entities like contact and account. Here's the Idea I raised on the Power Apps community forums back in the summer of 2019 (a year ago!!!).

I'll assume you already have the beginnings of a JavaScript web resource with the OnLoad form event wired up, and a PCF Control project.

So, it's all pretty simple really. Firstly we need to "dispatch" our event. I'll be doing this when a user selects an address from a ComboBox after searching by post code...

public addresslistComboBox_onChange(event: React.FormEvent<IComboBox>, option?: IComboBoxOption | undefined, index?: number | undefined, value?: string | undefined): void {
    const selectedAddress = JSON.parse(option?.data);
    const attributeName = this.props.context.parameters.postalcode.attributes?.LogicalName;
    const customEvent = new CustomEvent("onReceiveAddress", {
        detail: {
            Address: selectedAddress,
            Attribute: attributeName
        }
    } as CustomEventInit<EventData>);
    window.dispatchEvent(customEvent);
    this.setState({
        addresslistHidden: true
    });
}

Then all we need is to wire up a "listener" to listen within our form script for the event and handle it...

window.parent.addEventListener(
  "onReceiveAddress",
  (ev: CustomEvent<EventData>) => {
    if (ev.detail) {
      if (ev.detail.Attribute === "address1_postalcode") {
        const address = ev.detail.Address;
        formContext.getAttribute("address1_line1").setValue(address.line_1);
        formContext.getAttribute("address1_line2").setValue(address.line_2);
        formContext.getAttribute("address1_line3").setValue(address.line_3);
        formContext
          .getAttribute("address1_city")
          .setValue(address.town_or_city);
        formContext.getAttribute("address1_county").setValue(address.county);
        formContext.getAttribute("address1_country").setValue(address.country);
      }
    }
  }
);

Note when adding the event listener in the form script we must use window.parent, this is because in the Unified Interface custom form script web resources are all loaded within an iframe. Whereas the PCF control is rendered directly in the main document.

Pretty neat! So no duplicate fields to allow me to bind my control and no WebApi Updates directly from the control. Using this method we can update any field from our control without the need to bind at design time.

If your interested in having a look at the full source code I've uploaded it to github

So Long, and Thanks for All the Fish

D365 TypeScript Web Resources - Part 4 - Modules & Debugging

Oliver Flint — Sat, 11 Apr 2020 00:07:42 +0000

ES Modules

What are ES Modules?

ES Modules is the ECMAScript standard for working with modules.
Rather then repeat or quote others here are a couple of great articles about ES Modules:

A Sample Module

OK, so I expect the above articles have explained more that enough about es modules. Lets create a sample (because we can).
First create a new file in the src directory called sample.ts, paste the following into the file and save.

export function Pointless(message: string): void {
  Xrm.Navigation.openAlertDialog({
    text: message,
    title: "A Pointless Message",
  });
}

export class Stuff {
  public foo(): void {
    this.bar();
  }

  private bar(): void {
    Xrm.Navigation.openAlertDialog({
      text: "foo bar",
      title: "A foo bar message",
    });
  }
}

Our sample module exports a function called Pointless that displays a pointless message and a class called Stuff with foo and bar functions. Notice foo is public and bar private. foo calls bar which displays a foo bar message.

Lets now consume this module in our ContactMainForm class. First we need to import our function and class. Add the following at the top of contact-main-form.ts:

import { Pointless, Stuff } from "./sample";

Now we have imported these from our module we can make use of them. Add the following to our ContactMainForm.OnLoad function (form load event handler):

Pointless("This is a pointless message.");
const stuff = new Stuff();
stuff.foo();

The complete contact-main-form.ts should now look like this:

import { Pointless, Stuff } from "./sample";

class ContactMainForm {
  public OnLoad(
    executionContext: Xrm.ExecutionContext<Form.contact.Main.Contact, any>
  ) {
    const formContext = executionContext.getFormContext() as Form.contact.Main.Contact;
    formContext.ui.setFormNotification(
      "Typescript locked and loaded!",
      "INFO",
      "ts-msg"
    );
    const parentCustomerAttribute = formContext.getAttribute(
      "parentcustomerid"
    );
    const parentCustomerValue = parentCustomerAttribute.getValue();
    Pointless("This is a pointless message.");
    const stuff = new Stuff();
    stuff.foo();
  }
}
(window as any).ContactMainForm = new ContactMainForm();

Let's build our code with the following command and take a look what happens...

npx webpack

You guessed it! The compiled .js now contains our ContactManForm and the imports from our module sample.ts. Webpack has bundled contact-main-form.ts and all its dependencies into single .js files! :-D

Now you can deploy and test the new script to ensure it all still works.

That is a very basic example but it should set you on the way to creating a better more maintainable structure to your code. Remember the SOLID principles!

Debugging

So, we've got all these lovely tools, patterns and methodologies but how can we debug our code?
Well, you can of course just load up your browsers developer tools and debug the .js files deployed to D365, but these are not a line by line representation of our Typescript source files and the optimized version is practically unreadable!

webpack-dev-server & fiddler to the rescue!

Fiddler

I expect most will have used or heard of Fiddler. If you don't have it installed go grab it here.
We'll be using the Auto Responder functionality to redirect requests for our .js to a locally served file.

webpack-dev-server

Webpacks DevServer is essentially a http(s) file server.
Lets go an install the npm package...

npm install webpack-dev-server --save-dev

Next we need to add some stuff to our webpack.config.js
Fist of all we need to add the following at the top of the file:

var path = require("path");

then wee need to add the following to the development mode section/config:

devServer: {
  contentBase: path.join(__dirname, 'dist'),
  compress: true,
  port: 9000
}

Your webpack.config.js should now look something like this:

var path = require("path");

module.exports = [
  {
    mode: "development",
    entry: {
      "contact-main-form": "./src/contact-main-form",
    },
    output: {
      filename: "[name].js",
    },
    module: {
      rules: [
        {
          test: /.tsx?$/,
          exclude: /node_modules/,
          loader: "babel-loader",
        },
      ],
    },
    resolve: {
      extensions: [".ts", ".js"],
      modules: ["src", "node_modules"],
    },
    devtool: "source-map",
    devServer: {
      contentBase: path.join(__dirname, "dist"),
      compress: true,
      port: 9000,
    },
  },
  {
    mode: "production",
    entry: {
      "contact-main-form": "./src/contact-main-form",
    },
    output: {
      filename: "[name].min.js",
    },
    module: {
      rules: [
        {
          test: /.tsx?$/,
          exclude: /node_modules/,
          loader: "babel-loader",
        },
      ],
    },
    resolve: {
      extensions: [".ts", ".js"],
      modules: ["src", "node_modules"],
    },
    devtool: "source-map",
  },
];

Now lets start up Webpacks DevServer via the following command

npx webpack-dev-server

Once running you should be able to browse to http://localhost:9000/ and the built .js and .map files should be served.

What's the benefit of this I hear you ask! Well, we get a few benefits...

we don't have to deploy the file every time we make a change.
Chrome/Edge (no one uses IE any more right!) will be able to load our source maps.
The source maps will enable us to debug the Typescript in Chrome/Edge Dev tools. Magic! ;-)

Auto Responder

Lets setup the Fiddler Auto Responder. This is the component that will redirect request for our .js in D365 to our locally served files.

Load up Fiddler and select the Auto Responder tab on the right hand pane.

Next click Add Rule and enter the following in the Rule Editor
regex:(?inx)^.*\/webresources\/(((new_)+(?'jsname1'[a-z_\-\.]*\.js))|(?'jsname2'[a-z_\-\.]*\.js\.map))$
and
http://localhost:9000/${jsname1}${jsname2}
Then click Save

It should look like this...

Thats Fiddler setup, lets get debugging!

Debugging in Chrome Dev Tools

OK, so we have built and deployed our contact-main-form script (Assuming you followed from part 1). We also have Fiddler set up to redirect requests for our .js to local files and Webpack Dev Server serving up our files locally.

Now lets load up Chrome, browse to our D365 instance and open up a contact. Hopefully you'll get the notification and alerts from our script!

Hit F12 to load the Developer Tools.

Next select the Source tab

Then hit Ctrl + P to open a file and type contact-main-form. You should see the .ts file in the list, click on it to open it.

Lets add a breakpoint on line 5 (click on the left margin near the number 5)

We are now ready! Hit F5 (refresh) in the browser and Chrome Dev Tools should pause on our breakpoint. Now hit F10 (Step Over) until we are paused on line 9. Feel free to inspect some of the objects and variables along the way.

We are now going to step into our Pointless function so go ahead and hit F11 (you may have to hit it 2 or 3 times to get there). But eventually you should get to line 2 of our sample module sample.ts.

Brilliant isn't it!

No need to deploy

Right, One last thing to show you...
Lets make some changes to our ContactMainForm and test/debug without the hassle of having to deploy/upload the file to D365. Obviously once you've finished your development you'll need to deploy the file to D365, but this method speeds up your dev/test process.

First lets make a change.
I'm going to change the pointless message...

Pointless("This REALLY is a pointless message.");

Save the file and the build via the following command

npx webpack

Refesh the browser and in Dev Tools you should see our changes and be able to debug.

That's all folks!

I hope that has been useful!

You can download a copy of the source code for this blog post here

In the next part we'll take a look at unit testing and few useful tweaks to help some of the processes covered so far.

Thanks for reading.
Ollie

D365 TypeScript Web Resources - Part 3 - Webpack & Babel

Oliver Flint — Sat, 04 Apr 2020 22:00:00 +0000

What the *&^%

Ok, so, err, where do we start! Webpack and Babel are big. Too big for me to cover in one post. To be honest I don't know everything about them and have only scratched the surface myself, so I'll only cover a minimal config to get people started. I'll leave it to you to read and experiment further. After all, the best way to learn is often to just throw yourself in the deep end!

Webpack

Webpack is a "bundler". In basic terms it bundles/merges source files together into a single source file. Additionally it can do things like optimize and tree shake your source code.

Babel

Babel is a JavaScript Compiler (or Transpiler). With a little configuration it can turn your source code into code that is compatible with your target browser(s) and alleviate the headache of having to write code that targets specific browsers.

Install

Firstly lets install Webpack:

npm install webpack webpack-cli --save-dev

This installs the webpack module and it's command line interface

Next we'll install Babel:

npm install @babel/core @babel/preset-env --save-dev

This installs babel and a package of presets for the compiler.

Finally we'll install the Babel Loader for Webpack and a Typescript plugin for Babel:

npm install babel-loader @babel/preset-typescript --save-dev

babel-loader is used by webpack to preprocess (via babel) our source code before bundling and @babel /preset-typescript is a typescript compiler plugin for babel

Config

We now need to configure both webpack and babel...

Webpack config

Create a file in the root folder called webpack.config.js and open the file, paste the following contents and save.

module.exports = [
  {
    mode: "development",
    entry: {
      "contact-main-form": "./src/contact-main-form",
    },
    output: {
      filename: "[name].js",
    },
    module: {
      rules: [
        {
          test: /.tsx?$/,
          exclude: /node_modules/,
          loader: "babel-loader",
        },
      ],
    },
    resolve: {
      extensions: [".ts"],
    },
    devtool: "source-map",
  },
  {
    mode: "production",
    entry: {
      "contact-main-form": "./src/contact-main-form",
    },
    output: {
      filename: "[name].min.js",
    },
    module: {
      rules: [
        {
          test: /.tsx?$/,
          exclude: /node_modules/,
          loader: "babel-loader",
        },
      ],
    },
    resolve: {
      extensions: [".ts"],
    },
    devtool: "source-map",
  },
];

The above sets up two configurations, one for development and one for production. The difference between the two is essentially the file name (production names files *.min.js) as by default the production mode optimizes the output.

Further reading on webpack configuration

Babel config

Create a file in the root folder called babel.config.json and open the file, paste the following contents and save.

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "ie": "11"
        }
      }
    ],
    "@babel/preset-typescript"
  ]
}

The above loads two babel presets. preset-env will ensure the outputted JavaScript is compatible with your target browser(s) via polyfills etc. preset-typescript will enable babel to compile our Typescript into JavaScript.

Now we have switched to webpack and babel we aren't using the original Typescript compiler tsc to compile our Typescript into JavaScript. I'd advise reading the following caveats to help understand the differences.

Further reading on babel configuration

Lets build!

Open a fresh terminal (Ctrl+Shift+') in VS Code and run the following command to build the code:

npx webpack

You should now have 4 files in your dist folder. 2 JavaScript (1 optimized) and a source map for each.

If you take a look at the JavaScript you'll notice the non optimized version is bloated with some webpack bootstrap stuff (ES module loading, etc.), and the optimized version is broken because it has omitted (via tree shaking) our class ContactMainForm.

We just need to make a couple of simple changes to ensure it's included in the optimized code. Update the contact-main-form.ts as below:

class ContactMainForm {
  public OnLoad(
    executionContext: Xrm.ExecutionContext<Form.contact.Main.Contact, any>
  ) {
    const formContext = executionContext.getFormContext() as Form.contact.Main.Contact;
    formContext.ui.setFormNotification(
      "Typescript locked and loaded!",
      "INFO",
      "ts-msg"
    );
    const parentCustomerAttribute = formContext.getAttribute(
      "parentcustomerid"
    );
    const parentCustomerValue = parentCustomerAttribute.getValue();
  }
}
(window as any).ContactMainForm = new ContactMainForm();

Now rebuild with npx webpack and our optimized code can be deployed and tested!

That's all folks!

So, hopefully this has helped kick start your use of Typescript, Webpack and Babel to develop Web Resources.

You can download a copy of the source code for this blog post here

In the next part we'll take a look at modules and debugging.

Thanks for reading.
Ollie

D365 TypeScript Web Resources - Part 2 - Type Declarations

Oliver Flint — Sun, 08 Mar 2020 00:00:00 +0000

Type Declarations for the D365/XRM Client API

What are they?

A declaration file provides a way to declare the existence of some types or values without actually providing implementations for those values.

Do we need to construct our own?

Short answer: No

Long answer: No, but you may want to extend either of the two I'll mention below.

Longer answer: No, but you may want to extend either of the two I'll mention below, and you may even want to author you own.

So what do we have available?

Personally I have had a play with both @types/xrm and delegateas/XrmDefinitelyTyped

Of the two I prefer XrmDefinitelyTyped as it extends on @types/xrm by providing CrmSvcUtil like functionality to build Typescript interfaces that represent the entities and forms within your D365CE environment.

For the purpose of this post we'll take a look at XrmDefinitelyTyped :-)

Install XrmDefinitelyTyped

XrmDefinitelyTyped is packaged via Nuget so you'll need to ensure you have Nuget installed. Just download the latest nuget.exe into the root of you workspace.

Oh, you can download a starter workspace based on part 1 of this series from here

Once you've installed Nuget run the following from the root of the workspace...

nuget.exe install Delegate.XrmDefinitelyTyped -OutputDirectory .\

Next we need to configure XrmDefinitelyTyped. Within the XrmDefinitelyTyped directory you should find XrmDefinitelyTyped.exe.config. We are going to need provide some values for the settings in here.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="out" value="./typings/XRM" />
    <add key="solutions" value="" />
    <add key="entities" value="account, contact" />
    <add key="web" value="WebApiEntities" />
    <add key="jsLib" value="./src/lib" />
    <add key="mfaAppId" value="" />
    <add key="mfaReturnUrl" value=""/>
  </appSettings>
</configuration>

Alternatively you can use command line switches. I tend to use a combination of the two. Providing a list of the entities in the config file but the connection settings via the command line.

XrmDefinitelyTyped.exe /url:https://<organizationName>.crm<regionNumber>.dynamics.com/XRMServices/2011/Organization.svc /username:<username> /password:<password> /useconfig:.\Delegate.XrmDefinitelyTyped.5.1.6\content\XrmDefinitelyTyped\XrmDefinitelyTyped.exe.config

make sure to check the version number of XrmDefinitelyTyped used in the /useconfig: command line switch

Update the tsconfig.json with a reference to our new declarations by adding the typings to the include.

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

Note we also have to turn noImplicitAny off

And that's it. XDT (XrmDefinitelyTyped) should now be installed and ready to reference within your Typescript. As with CrmSvcUtil you will need to run XrmDefinitelyTyped.exe each time you need to update your typings with any customisation changes you have made to your entities, forms, etc.

Typing your types in your Typescript ;-)

Easy, and C# devs will love it!

Remember our first ts file we created in part 1...

class ContactMainForm {
  static OnLoad(executionContext: any) {
    const formContext = executionContext.getFormContext();
    formContext.ui.setFormNotification(
      "Typescript locked and loaded!",
      "INFO",
      "ts-msg"
    );
  }
}

Lets apply some typings to our objects...

class ContactMainForm {
  static OnLoad(
    executionContext: Xrm.ExecutionContext<Form.contact.Main.Contact, any>
  ) {
    const formContext = executionContext.getFormContext() as Form.contact.Main.Contact;
    formContext.ui.setFormNotification(
      "Typescript locked and loaded!",
      "INFO",
      "ts-msg"
    );
  }
}

Now, what I love about XDT is the type inference, for example getting an attribute infers the type depending on the logical name and you get something a little like this when writing your code:

For example the parentcustomerid attribute type is Xrm.LookupAttribute<"account" | "contact"> and the getValue() function returns a EntityReference<"account" | "contact">[]. Anyway I think you get the point.

Remember F12 in your IDE will link you to the definition in the typescript declaration :-)

That's all folks!

I hope that helps you get XDT working in your project. Please use the comments below, i'm more than happy to take questions and extend this post with any suggestions I feel would be of value.

You can download a copy of the source code for this blog post here

Thanks for reading.
Ollie

D365 TypeScript Web Resources - Part 1 - Basics

Oliver Flint — Sat, 07 Mar 2020 00:00:00 +0000

Developing JavaScript Web Resources with TypeScript

In this series (my first) of posts i'll share my experiences when authoring and maintaining JavaScript Web Resources with Typescript. The series will cover the basics and then more advanced options including ES Modules, webpack, babel, unit testing, deployment, etc.

Anyway! Let get started!

Why did I choose Typescript

So the why is potentially quite subjective and we all have our own opinions, this is mine and I don't expect you to agree but hopefully it will help you form your own opinion and maybe win you over to the idea...

Firstly the obvious, Typescript is essentially JavaScript with the addition of being able to (optionally) apply static types to your objects. This allows for more readable, cleaner, and more maintainable code. It also helps identify errors sooner, fits the mindset of C# developers, and has some great tooling to support the end to end development life cycle.

Then we have the endless options and tools for compiling/transpiling. For example, defining the browser(s) you wish to support so you have to worry less about the target browser(s) while writing your code. Also, using tools such a webpack to bundle you code into single files and compressing the output for better performance.

Finally we have unit testing and debugging where you can debug the typescript directly via source maps.

Personally, I will never go back to writing raw JavaScript unless it's the only option!

A Basic Setup

Ok, So lets take a look at what we need for the basic setup when working with D365 Web Resources.

Note: I'll be using Visual Studio Code as my preferred IDE. However, all of this can be done in other IDE's and terminals etc.

Node and NPM

If you don't have it installed already go and grab the latest version of Node

Init

Initialise a workspace/project.

Lets create a directory for our project and change to that directory (via Terminal)

md c:\d365ts-pt1
cd c:\d365ts-pt1

Open the project directory with VS Code (via Terminal)

code .

Init a new project (just go with all the defaults) (via Terminal)

npm init

install the typescript module (via Terminal)

npm install typescript --save-dev

create directories for the source code and the transpiled output (via Terminal)

md src
md dist

Typescript config

create a Typescript configuration tsconfig.json in the root of the workspace...

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

Full details on Typescript configuration can be found here

Our first TS file

create a new TS file in the source directory. We'll create the file contact-main-form.ts for the purpose of the demo paste the below into the file and save.

class ContactMainForm {
  static OnLoad(executionContext: any) {
    const formContext = executionContext.getFormContext();
    formContext.ui.setFormNotification(
      "Typescript locked and loaded!",
      "INFO",
      "ts-msg"
    );
  }
}

A basic onload event that should add a notification to the form once it's loaded

compile/transpile the source (via Terminal)

tsc

You should now see your new transpiled .js and .js.map (source map) files in the dist directory...

You can now update the .js file and wire it up to the Onload event like so...

Then when opening or creating a contact via the main contact form you'll see our form notification :-)

That's all folks!

You can download a copy of the source code for this blog post here

Coming up in the series

In the next part of the series we'll look at type declarations including XrmDefinitelyTyped. Until then feel free to comment below. All feedback is greatly appreciated.

In the future I'll also be covering the following within this series:

Type declarations
Debugging and Source maps
ES6 Modules
Babel and Webpack
Unit Testing
Automated Deployment
Lint rules for deprecated client API
and more So keep checking back for updates

Thanks for reading.
Ollie