JScript IntelliSense: A Reference for the “Reference” Tag

JScript IntelliSense: A Reference for the “Reference” Tag

  • Comments 21

It should be no surprise that JScript Documentation Comments power much of what you see in JScript IntelliSense in VS2008.  Perhaps the most useful of these comments is the "reference" comment.  The "reference" comment allows you to "see" functions and objects outside of your current file in the completion list.  I've gotten quite a few questions about this feature so, I wanted to provide a reference for when and how to use it.  There are four usage patterns:

Referencing Another JS File

/// <reference path="path-to/another-script.js" />

If the "path" attribute points to another JS file, any objects or functions defined inside that file-or in a file referenced by that file-will show up in IntelliSense.  Yes, this implies a transitive closure.  The intent was to reduce the number of references you would need on any given file.  Thus, don't be surprised if more scripts show up to the party than you invited!

Referencing a Web Service

/// <reference path="path-to/wcf-service.svc" />
/// <reference path="path-to/asmx-service.asmx" />

If the "path" attribute points to a web service (either WCF or ASP.NET), any objects or functions defined in the generated proxy for that service will show up in IntelliSense.  Web service proxies in JScript are an ASP.NET AJAX feature.  Therefore it is critical that you reference "MicrosoftAjax.js" before you reference any web services.

Referencing a Web Page

/// <reference path="path-to/default.aspx" />

If the "path" attribute points to a page (an ASPX, HTML, or Master), IntelliSense will behave as if you were on the page.  This mode is really just syntactic sugar and behaves equivalently to manually copying each script reference from the page over to your script file.  The only difference is that you will not see any inline script blocks reflected in IntelliSense.  However, you will be able to reference any elements with an ID on the page.  Any scripts or elements included via a Master page will also be reflected.  This mode useful for scripts that are meant to be paired exclusively with a markup page, i.e. in a "code-beside" fashion.

Referencing an Embedded Resource

/// <reference name="resource-name" />
/// <reference name="resource-name" assembly="assembly-name" />

We recognized that scripts will frequently be embedded inside an assembly.  To reference such a script, set the "name" attribute to the resource name, and set the "assembly" attribute to the assembly name.  The "assembly" attribute is optional.  If left out, System.Web.Extensions will be assumed as the assembly.  This is why referencing "MicrosoftAjax.js" does not require an "assembly" attribute.

Other Hints

Here are a few other subtle tips:

  • Remember, reference statements must precede all other content in the file-even normal comments.
  • Make sure any dependencies are taken into account in the order of declarations. Most of the time, you will want "MicrosoftAjax.js" to be on the top.
  • You can use app-relative paths (~/folder/file) to make your references more robust.
  • Specifying ".debug.js" extension is optional. The editor will look for the ".debug.js" version of your script even if you only specified ".js". This intentionally behaves similarly to the ScriptReferences of the ScriptManager.
  • To combat the tedium of typing large amounts of these reference statements, try the dragging and dropping files from the solution explorer onto the editor to automatically generate these statements. It even works for DLLs.

Hope this helps!

Jeff King
Program Manager
Visual Studio Web Tools

Leave a Comment
  • Please add 8 and 2 and type the answer here:
  • Post
  • Not directly related, but is there a way to filter the JavaScript intellisense to not show IE-only syntax? IOW, I have a <div id='myDiv' /> in my page, I do not want window.myDiv to appear. Does VS2008 support this? If not, consider this a feature request :)

  • Hi Brock Allen: unfortunately it's going to have to be a feature request. :) It's behaved like that longer than I can remember and we didn't make any changes to that code this version.

  • It would be nice if this actually worked for classes in the namespaces created with Type.registerNamespace, that Microsoft told us to use when working with Microsoft AJAX.

    It would also be nice if the webcontrols on the webpage that embeds javascript files into the page also would be included in the Intellisense.

    Without these two things, it's hard for an API developer to actually make any use of any of this and expose the JS methods to the developer.

  • SharpGIS, in a couple of days Misual Studio 2008 RTM will be shipped.

    And Scott Guthrie promised us, that support most of JS Frameworks will be included.

    So, im believe him :)

  • I can't get the intellisense to work for anything except the build in JavaScript objects. I've tried both with the scriptmanager, regulare script tags and using the reference tag within a js file.

    Any ideas why?

    I'm using the rtm Team Suite trial version.

  • Is it possible to use <reference> on a virtual directory? I have websites with several virtual directories in order to share JavaScript. The structure is mainly for ease of development.

    I have tried pretty well every construct I can think of, and dragging the JavaScript file from the Solution Explorer inserts what looks like the correct path, but the Intellisense just does not pick up the content.

  • Thanks for the explanation.  

    A little off topic, Any I idea why intelliSense would not show documention comments?  I get color coding and intellisense on method name and parameter names but the comments are not shown.  Anything for me to look at? Thanks!

  • Adding

    /// <reference name="MicrosoftAjax.js"/>

    gives me perfect IntelliSense in an external script file.

    But how do I get the same experience in an inline script block?

    <script type="text/javascript">

       /// <reference name="MicrosoftAjax.js"/>

    doesn't do it. Neither does

       <asp:ScriptManager runat="server" ID="ScriptManager1">

           <Scripts>

               <asp:ScriptReference Name="MicrosoftAjax.js" Assembly="System.Web.Extensions" />

    Thanks

    Magnus

  • .NET: JScriptIntelliSense:AReferenceforthe

  • yeah i don't see intellisense for $get, $find, etc in inline script block inside aspx. It works fine in an external js using reference name=microsoftajax.js.

    please advise.

  • Hi Wahy: Do you have an asp:ScriptManager on your page?  That is required to see $get, $find, etc.

  • Hi Magnus Markling: an Explicit reference to "MicrosoftAjax.js" is not needed as the ScriptManager will add that for you by default.  If it's still not working, please contact me at jking-at-microsoft-dot-com and we can examine your specific case.  Thanks!

  • Hi DJames: While editing the the active document, any Doc Comments defined there will not show up.  You will only be able to see Doc Commented defined in other (referenced) files.  This is a VS2008 limitation.  We will see what was can do in the next version.  Thanks!

  • Hi Johan Nordberg: If you are still seeing issues, please contact me at jking-at-microsoft-dot-com and we'll investigate further.  Thanks!

  • Hi SharpGIS: Namespaces created with Type.registerNamespace will be reflected in IntelliSense if it comes from an external file.  Namespaces in the local file created with Type.registerNamespace will not appear because we do not evaluate that code.  It's pretty difficult to infer such things, but we'll see what we can do in the next version.  Dynamically registered scripts are not detectable by the IntelliSense engine since they only-resolve at runtime.  This is one more thing that's difficult to infer, but (again) we'll see what we can do in the next version.  Thanks!

Page 1 of 2 (21 items) 12