Your official information source from the .NET Web Development and Tools group at Microsoft.
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.
Here are a few other subtle tips:
Hope this helps!
Jeff KingProgram ManagerVisual Studio Web Tools
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.
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 :)
Any ideas why?
I'm using the rtm Team Suite trial version.
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!
/// <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?
/// <reference name="MicrosoftAjax.js"/>
doesn't do it. Neither does
<asp:ScriptManager runat="server" ID="ScriptManager1">
<asp:ScriptReference Name="MicrosoftAjax.js" Assembly="System.Web.Extensions" />
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.
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!