Some of the members of the Visual Studio Windows Azure Tools & Mobile Services teams recently published instructions for “Enabling IntelliSense for Mobile Services JavaScript in Visual Studio.” Since working with the Windows Azure Mobile Services (WAMS) server-side JavaScript files can be a little bit of a blind experience – debugging happens primarily through strategic placement of console.log statements and frequent examination of the Mobile Services server script reference on MSDN – even the littlest help goes a long way…though I am NOT saying that his IntelliSense support only offers “the littlest help.”
To get started, the JavaScript IntelliSense definition file can be downloaded from this link. Additionally, there’s a ReadMe document that provides some supporting information available at this link. The ReadMe file points out that the IntelliSense definition – in its current incarnation – is somewhat limited in its coverage (hey, it’s a start!)
Placing and Referencing the IntelliSense Definition File
The original article references two mechanisms for actually directing Visual Studio to make use of the reference file: adding an explicit reference to the precise path of the definition file on the local file system, and adding a reference to the definition file through the Tools/Options/Text Editor/JavaScript/IntelliSense/References panel in Visual Studio (under “Implicit (Web)”.) Pros and cons of each approach were outlined, including:
- Providing the path to the file within the script files themselves is a bit more work, since every script file needs to be modified;
- Adding the Visual Studio reference results in a “pollution” of the JavaScript IntelliSense since Visual Studio doesn’t discriminate as to whether or not you’re working on Mobile Services scripts in order to choose what definition files to consult.
Now that the stage is set, I’d like to offer some tips for how to extract a little bit more from these IntelliSense files.
A Slight Change to Definition File References
There’s a small alteration that can be made to the list above to enable referencing the definition file. My concern with the presentation of the approaches listed above is that they require the definition file to be in the same path location on every machine that is used to edit the JavaScript contents. In my experience, this is a pain in the neck to achieve – even simply spanning my own development machines. However, the JavaScript IntelliSense tooling does support relative paths. With that in mind, I’d suggest putting the IntelliSense file into the WAMS script Shared directory and uploading it through Git (for more information on using the Microsoft Visual Studio Tools for Git to manage WAMS script files, see my previous article here), then adding relative references to “../shared/mobileservices.intellisense.js” either in the script files or in the Visual Studio settings dialog.
The screenshots below show this in use through the Visual Studio settings:
(* a note about working with the Visual Studio settings – if you’ve added your file path using absolute or relative paths and find that IntelliSense still is not coming up, it may be due to inserting the definition file reference in the wrong “Reference Group”, such as Implicit (Windows) – I call this out because it bit me MULTIPLE times. Reference Groups are discussed in the MSDN documentation here.)
Note that since the file path is relative, when opening/working on JavaScript files in an HTML Web project, unless there’s a matching “mobileservices.intellisense.js” file within a folder titled “shared” relative to the file being worked on in that project, the WAMS IntelliSense won’t be included.
Likewise, including the relative file at the beginning of the WAMS JavaScript file itself has the same results:
While the upside to this approach is that other developers/other development machines acquire the IntelliSense simply by synchronizing the client and server repositories, there is a downside to this approach. Interacting with scripts opened through the Windows Azure Mobile Services node in the Server Explorer will not include IntelliSense. When these files are opened in Visual Studio, they are downloaded and opened from a temporary location on the local file system, so the Shared files are not placed in the location specified by the relative path. I’m OK with this, as I’ve grown to prefer to use the source-control managed file editing and retrieval, and the Server Explorer doesn’t yet provide access to API Scripts or Shared Script content (though I have no doubt that it will soon…but I still like the “safety net” offered by working through Source control and the ease with which I can by using the integrated Microsoft Visual Studio Tools for Git.)
Providing Context
One of the problems with the IntelliSense solution is that there’s no information providing Visual Studio with insight as to how to handle the parameters in the script signatures. The good news is that is not hard to do, and since these objects are frequently referenced within the WAMS scripts, being able to allow them to join in the “IntelliSense party” provides a lot of help.
Having Visual Studio include IntelliSense for these parameters is simply a matter of adding a JavaScript XML Documentation Comment for the method signature. The IntelliSense comments for each of the table script methods follow. (Custom API scripts will be discussed in a second.)
Read:
function read(query, user, request) { /// <param name="query" type="Query"></param> /// <param name="user" type="User"></param> /// <param name="request" type="Request"></param>
Insert (Update uses the same XML comments):
function insert(item, user, request) { /// <param name="item" type="Object"></param> /// <param name="user" type="User"></param> /// <param name="request" type="Request"></param>
Delete:
function del(id, user, request) { /// <param name="id" type="Number"></param> /// <param name="user" type="User"></param> /// <param name="request" type="Request"></param>
With the comments in place that describe the types of the incoming parameters, the server-side scripts now get IntelliSense within Visual Studio:
Before:
After:
Working with IntelliSense in Custom API Scripts
The emphasis of this first JavaScript IntelliSense definition file was to provide support for Table operation scripts. However, with a little help, Custom API scripts can also join in the fun.
Custom API scripts receive two parameters – request and response. However, it is important to note that the request object used in Custom API scripts is not the same request object that is used in the table scripts…in fact, this object provides access to several objects that are directly used as parameters in the Table operation scripts. This distinction is covered in the MSDN documentation for the request object.
Because I now maintain and reference a copy of the mobileservices.intellisense.js file within my source-control-managed “shared” folder, I can augment and/or make changes to the file with some confidence…when an update to the IntelliSense file is published, I can simply drop the file into place, and before committing and synchronizing the changes I can use a differencing tool to see what has changed. Ideally, I will notice if the new file is about to lay-waste to the changes I’ve put in…so let’s change the definition file.
I’ve basically added some content to the definition file to provide information about the request object for Custom APIs. The IntelliSense content I’ have added comes from a combination of the MSDN documentation and the Express.js library documentation, which is where these request and response objects originated. My content is not comprehensive – I’ve only documented the items that were immediately relevant to me, but there’s nothing to stop others from adding more content – the Express.js documentation for the request object can be found here and the documentation for the response object can be found here.
The content I added to the mobileservices.intellisense.js file is:
/* Custom API Augmentations */ service = { ///<field name="push" type="push">Returns an object used to access the the various push notification proxies.</field> push: push, ///<field name="tables" type="tables">Returns an object used to access the the tables in this instance.</field> tables: tables, ///<field name="mssql" type="mssql">Returns an object used to access the mssql instance.</field> mssql: mssql, } ApiRequest = function ApiRequest() { ///<summary>Faux type used only for providing IntelliSense in Custom API scripts. DO NOT CREATE INSTANCES.</summary> } ApiRequest.prototype = { ///<field name="headers" type="Object">Returns a collection of all the message headers, as a JSON object. Individual headers are obtained by calling the header function.</field> headers: headers, ///<field name="query" type="Object">Used to access the parsed query-string.</field> query: query, ///<field name="service" type="service">Provides access to mobile service-specific resources.</field> service: service, ///<field name="user" type="User">Returns the user object which contains information about the client sending the request.</field> user: user, header: function (headerValue) { /// <summary>Returns a JSON representation of the named header-value from the HTTP request headers sent in a custom API request.</summary> /// <param name="headerValue" type="string">The name of the header to locate.</param> } } ApiResponse = function ApiResponse() { ///<summary>Faux type used only for providing IntelliSense in Custom API scripts. DO NOT CREATE INSTANCES.</summary> } ApiResponse.prototype = { send: function (status, body) { ///<signature> ///<summary>Sends a response.</summary> ///<param name="body" type="Buffer">When a Buffer is given the Content-Type is set to 'application/octet-stream' unless previously defined with the set command.</param> ///</signature> ///<signature> ///<summary>Sends a response.</summary> ///<param name="body" type="String">When a String is given the Content-Type is set defaulted to 'text/html'.</param> ///</signature> ///<signature> ///<summary>Sends a response.</summary> ///<param name="body" type="Array">When an Array or Object is given the response will include the JSON representation.</param> ///</signature> ///<signature> ///<summary>Sends a response.</summary> ///<param name="body" type="Object">When an Array or Object is given the response will include the JSON representation.</param> ///</signature> ///<signature> ///<summary>Sends a response.</summary> ///<param name="status" type="Number">The HTTP response code. When a Number is given without any of the previously mentioned bodies, then a response body string is assigned for you. For example 200 will respond will the text 'OK', and 404 'Not Found' and so on.</param> ///</signature> ///<signature> ///<summary>Sends a response.</summary> ///<param name="status" type="Number">The HTTP response code.</param> ///<param name="body">A body element as defined in the other signatures.</param> ///</signature> }, set: function (field, value) { ///<signature> ///<summary>Set header field to value, or pass an object to set multiple fields at once.</summary> ///<param name="field" type="String">The header field name.</param> ///<param name="value" type="String">The value to set for the header field.</param> ///</signature> ///<signature> ///<summary>Set header field to value, or pass an object to set multiple fields at once.</summary> ///<param name="values" type="Object">A JSON Object consisting of header field/value pairs.</param> ///</signature> } }
With that in place, it is still necessary to include some “helper” XML comments in order for Visual Studio to “connect the dots” between the Custom API function signature and the new IntelliSense:
exports.post = function (request, response) { /// <param name="request" type="ApiRequest"></param> /// <param name="response" type="ApiResponse"></param>
And with that, we now have IntelliSense in our Custom API script:
Wrapping Up
I have it on good authority that the Mobile Services team is continuing to work on ways to enhance the script editing experience, so it is likely that some of these steps will only be temporary. But in the interim, the inclusion of these IntelliSense aids should make editing WAMS script files in Visual Studio considerably simpler.
DotNet Gator 