Hey! It’s finally here! The long-awaited article companion to my xRMVirtual presentation. If you haven’t seen the video, then I invite you to do so. If you have, then I apologize for wandering, at times, and trying to squeeze too much into too little a timeframe. I ended up repeating the content to a different group of colleagues, and I went about 90 minutes—spending more time in the live demonstration, than in much of the content I presented initially. That said, I would like to provide a repeat of the demonstration material in a separate video in the near future.
So, parting with the final ado:
- Transcompiles - "Source-to-source". Mostly this is accomplished by removing TS markup, however some language constructs undergo a more nuanced conversion.
What Does that Mean?
In the web-development world, EcmaScript is king, and TypeScript does well to bow to it.
TypeScript's stated direction is to provide feature-parity with EcmaScript 6. Indeed, many of TypeScript 1.4's current features, and the coming 1.5 update will bring the language very close to party with the current specification for EcmaScript 6.
However, you might be surprised to discover that by default, it builds down into EcmaScript 3, which supports a very broad range of browsers (going back to at least IE6, but if you know somebody that is still using IE6, please thaw out their cryo-chamber). Some features require newer versions, such as getters and setters, which require ES5. Most other features are build down into a syntax that works in the older language, such as classes or template strings, which are native to ES6, but built into ES3/5 in a very specific manner so as to allow the ES6 syntax/style to be leveraged for "older" platforms.
Type inference also helps keep the requisite TypeScript syntax to a bare minimum, and where it is most useful. However, you can expect it to nag at you as you design, doing so with real-time compiler validation. Thankfully, it also offers great IntelliSense support to sort out type issues on-the-fly.
Code documentation is formulated in JSDoc, which is more widely used by web-developers, and does break away from XML documentation common to Visual Studio. (I use Atomineer Pro to help generate documentation. It's inexpensive, and offers TypeScript support.)
These are called "TypeScript Definition Files", and carry the special extension .d.ts. This approach is effective, although not always perfect, and is often at the mercy of the crowd--rather than the library's original author. However, there are projects that are good about self-made definitions, and I'd like to give a shout-out to Telerik's Kendo UI framework for being one such example.
- Visual Studio 2013 Update 2 (or later), Sublime Text, Eclipse
- TypeScript 1.5: http://www.typescriptlang.org/#Download
- NuGet: http://docs.nuget.org/consume/installing-nuget,
or TypeScript Definition Manager (Node Package Manager): https://github.com/Definitelytyped/tsd#install
- Gulp: http://gulpjs.com/ If you wanna get freaky amazing.
- this (literally): http://www.2ality.com/2014/05/this.html What this really means, and why it can put your code in jeopardy. Thankfully, TypeScript uses a this redirect to help, but when writing TypeScript code, that redirect is called this inside class definitions.
Yes! You’re ready to get started in the world of TypeScript development. Just crank open your TypeScript-enabled IDE of choice, and keep the language reference guide handy, and you’ll be set to develop in TypeScript.
If you’re developing web resources in Dynamics CRM, and you would like some IntelliSense for the Xrm.Page context, or you would like the whole Xrm API for form-related scripting needs, then I encourage you to install the Xrm definitions files from DefinitelyTyped.
At first download, several definitions will be available: CRM 2013 (6), CRM 2015 (7.0), and CRM 2015 Service Update 1 (Current), ClientGlobalContext, and Parature. Because DefinitelyTyped only accepts definitions that are vetted with their build-testing framework, these files rely on <reference> decorators in file comment headers.
At compile time, a TypeScript project in Visual Studio will instead include all files within the project (by default). This causes compiler errors, as each version of the main definition file conflicts with the definitions of the others. To get around this problem, simply exclude the definitions which are not appropriate for the project:
Now, for best practice, even though Visual Studio will handily incorporate IntelliSense for Xrm throughout your project files, please include the appropriate <reference> header:
This assures the portability of your TypeScript code to other development environments, and makes for a good indicator of the runtime requirements your code will have.
For TypeScript, the Xrm API has been enhanced with generics, interfaces, enumerations, and type unions. No additional functionality has been provided, and due to the nature of a definition file, no code will be produced to support it. Instead, these enhancements help encapsulate functionality and accurately describe the intent and behavior of the code at runtime.
Robust documentation has been provided to the TypeScript definition files, largely borrowed from Microsoft’s own documentation. This provides a remarkable IntelliSense experience. However, with TypeDoc, I’ve created a navigable documentation page to help with understanding it:
There is a tests file in the repository that should help demonstrate some of the basic concepts employed in the API definition. In all, I find that the definition file makes it easier to develop by reducing the amount of time spent looking at the Microsoft API documentation. It does this with stronger typing, which properly sets the code’s expectations, given a little more forward effort on my part to accurately provide type decorations. I encourage you to examine it in Visual Studio, and play with it.
As always, I’m welcome to suggestions and pull requests. So, if you have an improvement, or some better test scenarios to share with the community, I welcome them!