Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
TypeScript Helper Class Utility Overview
TypeScript Helper Class Utility (TS Helper) XrmToolbox plugin is intended to help developers generate TypeScript code to assist with complex CRM form and Web Resource scripting.
This project was originally developed by Brendon Colburn (brendon-colburn) for his work at Microsoft Consulting Services (MCS) on various xRM projects. Bendon's goal was to provide a standard method CRM WebAPI calls using strongly typed scripts, implemented as TypeScript modules. We decided that it would best be shared and distributed as an XrmToolbox plugin, so this is the first release.
The original premise takes a page out of the CRMSVCUTIL playbook and provide a method to generate TypeScript objects based on entities within your solution. While the CRMSVCUTIL Naming Provider extensions allow overriding the code generation output, we are provide a very simple templating tool to generate your TypeScript objects. The resulting TypeScript objects are then used as part of an Angular based TypeScript framework.
NOTE: Please let us know if you have any issues with the information and examples provided. As we receive feedback (bugs!) and refine the plugin/templates/scripts and work on additional script models, we will be updating these and other pages. All feedback is welcome and extremely helpful!
The initial release of the TS Helper plugin includes a template TypeScript leveraging the Angular framework with a focus on simplifying CRM WebAPI calls using generated entity script objects. It also includes some helper scripts for working within a CRM form or web resource.
With our current project, we have extended this template to address a few issues, streamline the generated objects, and provide a few more utility methods. We have extended Brendon's initial tool for generating the TypeScript objects, converting it to an XrmToolbox plugin, and while making that conversion, it has evolved into more of a general templating tool for CRM entities.
The Angular based template consists of 3 main files:
- index.html: HTML web resource that loads and references the script resources, provides Angular app and controller elements, and provides any UI elements if required.
- app.ts/app.js: script web resource that provides the main business logic behind the solution, such as form scripts, WebAPI calls, or additional UI elements.
- Xrm.ts/Xrm.js: script web resource that provides common WebAPI methods, helper utilities, and the generated script objects used by the app.ts and the WebAPI calls. This relates roughly to the CRMSVCUTIL output used by CRM Plugins, Workflow activities, etc. The Xrm.ts script will be the output of our TS Helper plugin!
Using three files might seem like overkill for working with script web resources. Because the CRM form rendering engine that loads all resources asynchronously, complex scripting scenarios can quickly run into issues with the order in which scripts are loaded and available. A utility script may not be available at the time the form OnLoad event fires by the CRM form scripting engine. So a goal of this model has been to ensure related resources loaded at the time we invoke our scripts.
Since we use the index.html HTML web resource, our context for load is this web resource document, not the CRM form. This is definitely not a foolproof method for dealing with the asynchronous script loading, but it does offer a bit more control.
TypeScript Helper Class Utility (TS Helper) XrmToolbox plugin provides the means to extend the Angular script model by generating strongly typed interfaces and classes based for each CRM entity required by the solution. This means selecting one or more entities and generating script for each attribute associated with the entity. The plugin handles loading of the entity and attribute metadata objects, iterating on each, and generating the TypeScript based on a custom template syntax. With these generated classes, developers can easily call WebAPI methods with strongly typed objects. Another benefit for development is the early bound scripts, similar to those provided by the CRMSVCUTIL, that make life a little easier while developing web resources or simple form scripts.
Continue with the page Angular Template Reference for more details on the resource highlighted above and the Angular based template. This page provides a bit more detail on each component Angular based model, how they can be used, and some examples.
For the TS Helper XrmToolbox plugin usage, continue with the page titled Plugin Reference. This provides information on how to use the plugin and it various options and how to create your own templates from the CRM entities and attributes.
And for more information on creating your own custom template, please review the Template Reference wiki page.