Placing and Referencing the IntelliSense Definition File
- Providing the path to the file within the script files themselves is a bit more work, since every script file needs to be modified;
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
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.)
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.)
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.
Insert (Update uses the same XML comments):
With the comments in place that describe the types of the incoming parameters, the server-side scripts now get IntelliSense within Visual Studio:
Working with IntelliSense in Custom API Scripts
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:
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:
And with that, we now have IntelliSense in our Custom API script:
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.