Wednesday, May 5, 2010

Leveraging Visual Studio JavaScript IntelliSense. Part 1

One of the most useful features of the Visual Studio 2008 and Visual Studio 2010 is JavaScript IntelliSense that allows developers write JavaScript code faster, with fewer errors and reduce learning time of some JavaScript frameworks. Many developers already enjoy its power when code JavaScript with Microsoft ASP.NET Ajax framework and jQuery. However many developers are still not familiar with that tool and even less developers realize that it can also be used with their own code.

As convenient and powerful the JavaScript IntelliSense is as it is not intuitive to get started with mainly because of its lack of well-organized documentation and non-intuitive error diagnostics. Another obstacle is that it does not support its own XML code comments that makes it hard to use to the full extent without learning and memorizing first.

This article aims to provide with a quick reference of the most useful features of the JavaScript IntelliSense to help make it an every-day tool for the JavaScript developers.

In short words JavaScript IntelliSense provides with two main features:
  1. It enables documentation and syntax support while coding for the core JavaScript elements and third-party JavaScript libraries;
  2. It allows adding documentation and syntax support to the code being developed so other developers can use it.
In this post I cover the first feature.

Enable JavaScript IntelliSense for third party JavaScript libraries

The IntelliSense support for the core JavaScript syntax is enabled by default. In order to enable IntelliSense for third party code one needs to satisfy the following requirements:
  1. Reference a third party JavaScript file in your code, and
  2. Make sure the third party JavaScript includes Visual Studio XML code comments
The second requirement is in fact optional because JavaScript IntelliSense will work even without XML comments but will provide with less information so it actually pays off checking out before choosing a third-party JavaScript library whether it has a VS IntelliSense support. Many of the most popular JavaScript libraries such as ASP.NET Ajax, jQuery, Bing Maps, etc. do support VS IntelliSense.

Referencing another JavaScript library in your JavaScript code

Simply use a reference directive in your JavaScript code. There are a few flavors of that directive depending on the location of a third party JavaScript code. A reference directive supports file-based, assembly-based, service-based, or a page-based script references. Below are the examples illustrating those scenarios:


A -path-to portion above can be both a file path to a local or network location or a web URL to both intranet and Internet resources. In the latter case keep in mind that the Internet resource will be accessed every time Visual Studio opens a JavaScript file with a reference so it is better to cache it locally which is also much safer. In case of a service-based reference the actual URL Visual Studio has to access will be 'service-url/jsdebug' or 'service-url/js' based on the solution configuration therefore make sure that the project a service belongs to compiles without errors.

It is not necessary to reference an original JavaScript code itself (for example if it's hosted somewhere outside of your development environment) if there is a VSDOC file provided as it is with jQuery or Bing Maps libraries for example.

A VSDOC file is a JavaScript file that only includes objects definitions and functions signatures with XML comments without actual code and is a preferred way to add extensive documentation to a JavaScript library without modifying the original JavaScript code. In case there are no XML comments in the code nor VSDOC file is available simply reference an original JavaScript file and Visual Studio will parse it and provide you with the best possible IntelliSense help. If you use Microsoft ASP.NET Ajax framework add the following reference to the top of your JavaScript code:


You may have noticed that this is a reference to an embedded resource but without assembly name. Such a reference only works for so called well-known assemblies that are listed in a web.config file such as in this case a System.Web.Extensions. If you use a JavaScript library that comes in a form of a DLL containing multiple JavaScript you may consider listing it in a web.config file and save on assembly name in multiple reference directives.

IntelliSense Rules

The JavaScript IntelliSense behavior is determined by the following rules:
  1. Private class members defined inside a class constructor are not visible in IntelliSense. If you need to have IntelliSense support for private members define public getter (get_...) and/or setter (set_...) methods for them with XML comments
  2. Class methods with names beginning with underscore are considered private and not visible even if they have XML comments
  3. Public class methods can be defined in a class prototype or in a standalone code.
  4. If XML comments are not provided only a method name and a list of arguments are displayed.

IntelliSense Errors

If you don't see IntelliSense support for a JavaScript library even though you have added all the reference check out the Visual Studio Errors tab. If IntelliSense cannot load a referenced file it will display a message like 'Could not load ...' in the Errors tab. The most common reasons for IntelliSense not being able to a load a referenced file are:
  • File is not found at the location or location/file name is invalid. If the file is located on the Internet or a network share there may be a problem accessing those locations from your machine.
  • A referenced JavaScript file contains errors. If IntelliSense can not successfully parse the file it will not load it.
  • If a referenced JavaScript is an embedded resource from one of the solution's projects the project is not compiled for some reason and the DLL is not found.

This is all for the first part. In the next post I will explain how to use XML comments in your own JavaScript code to IntelliSense-enable it. If you find something missing or incorrect in this post or have suggestions what else to cover please write a comment and I will get back to you ASAP.

More to read

3 comments:

  1. When I tried to apply this plugin development pattern Visual Studio Intellisense for jQuery stopped working. But I found a solution: Getting Visual studio jQuery Intellisense working again within jQuery plugin pattern http://www.bnomad.com/2010/07/getting-visual-studio-jquery.html

    ReplyDelete
  2. Great information here. Though the usage of a internet-based jQuery CDN path did not produce any intellisense nor did it produce any errors.

    Was there ever a part 2 on this topic?

    ReplyDelete
  3. Hmm the above scenario does not work in my solution. One class library defines a JavaScript file as Embedded Resource. The Embedded Resource is declared in the AssemblyInfo.cs file of the class library using the following line
    [assembly: WebResource("My.Web.Common.ControllerBase.js", "text/javascript")]

    In a JavaScript file of a MVC Host Application I want to references the ControlerBase.js file from the class library using the following line at the top
    ///

    --> No Intellisense at all.

    ReplyDelete