Geeks With Blogs

News



Microsoft Store

Support This Site


AddThis Social Bookmark Button

Locations of visitors to this page

Subscribers to this feed

TwitterCounter for @sdorman

Creative Commons License


Scott Dorman Microsoft MVP, Software Architect, Developer, Author

I am a big fan of using XML comments in code and actually have a few Visual Studio macros which allow me to “inherit” the documentation from an overridden member. Every once in a while, I end up pulling in a comment with a filterpriority XML tag. This tag is very prevalent in the BCL but I have never been able to find documentation on what it actually means.

To see what I mean, let’s take a look at part of the definition for System.Object. In the XML comments, you will see that the class itself has a <filterpriority>1</filterpriority> and that the Equals method has a <filterpriority>2</filterpriority>.

   1: namespace System   
   2:  {
   3:      /// <summary>Supports all classes in the .NET Framework class hierarchy 
   4:      /// and provides low-level services to derived classes. This is the 
   5:      /// ultimate base class of all classes in the .NET Framework; it is the
   6:      /// root of the type hierarchy.</summary>
   7:      /// <filterpriority>1</filterpriority> 
   8:      [System.Runtime.InteropServices.ClassInterfaceAttribute(2)]
   9:      public class Object    
  10:      {    
  11:          /// <summary>Determines whether the specified 
  12:          /// <see cref="T:System.Object" /> 
  13:          /// instances are considered equal.</summary>  
  14:          /// <returns>true if objA is the same instance as objB or
  15:          /// if both are null
  16:          /// references or if objA.Equals(objB) returns true; 
  17:          /// otherwise, false.</returns>
  18:          /// <param name="objB">The second <see cref="T:System.Object" /> 
  19:          /// to compare. </param>
  20:          /// <param name="objA">The first <see cref="T:System.Object" /> 
  21:          /// to compare. </param>
  22:          /// <filterpriority>2</filterpriority>
  23:          public static bool Equals(object objA, object objB);
  24:       }
  25:   }

The only real mention I was able to find was this blog post, which is actually talking about the “Go to definition” feature of Visual Studio. One of the comments asks about the <filterpriority> tag. Unfortunately, when I saw this blog post and the comments, I misread the second comment and thought that it applied to the first comment about the <filterpriority>. As it turns out, the comment was talking about the “Go to definition” feature itself.

Since I wanted to know the answer, I posted a question on StackOverflow. The first answer seemed to indicate that this applied to the “All” and “Common” tabs in the VB.NET editors intellisense implementation, but (due to having misread the blog post comments) I dismissed that thinking this was a C# feature. A second answer just a few days ago said that this was somehow tied to the EditorBrowsableAttribute (and more specifically the values of the EditorBrowsableState enum. I couldn’t see how an XML comment could be the same as decorating the member with the attribute.

As a result, I started doing some more digging and came across a self-published book titled XML Document Guide, which actually documented the <filterpriority> tag (page 30). According to that book, the value of this tag is:

Used by the Visual Basic editor in order to determine whether a member should appear on the Common or All tab when the completion list is shown.

That led me to start doing some testing of my own to verify things.

The first thing I discovered is that it appears to have no effect on classes. This is contrary to what I would have thought since Microsoft places filterpriority tags on classes. Getting past that discrepancy, it became very clear that the filterpriority tag controls the IntelliSense visibility for both methods and properties whether they are instance members or static members. Testing on Visual Studio 2008 RTM provided the following results:

Filter Priority value

Method

 

Property

 

Instance

 Static

Instance

 Static

missing Common Common Common Common
0 Common Common Common Common
1 Common Common Common Common
2 All All All All
3 Hidden*  Hidden Hidden Hidden

* Initial testing on VS2008 SP1 showed this method available on the All tab.

Where things start to become really interesting is when you combine the filterpriority tag with the EditorBrowsableAttribute. This attribute specifies if a method or property is viewable in an editor and allows you to specify a state of Always, Advanced, or Never. At first glance this appears to cause the same behavior as the filterpriority tag with the benefit that any language editor will respect the attribute.

But what happens if you specify both the filterpriority tag and the EditorBrowsableAttribute? When tested on VS2008 RTM, the filterpriority tag took precedence over the EditorBrowsableAttribute and the results were exactly the same as if the attribute were not present. However, when using EditorBrowsableState.Never, the attribute took precedence over the filterpriority tag and none of the methods displayed in the IntelliSense list.

I did notice that the results did not seem 100% repeatable so, for now I would be a bit cautious relying on the filterpriority tag. I’m going to see if I can get someone from either the VB or Visual Studio teams to comment and provide some definitive information on how this tag behaves, but until then the only certainty is that it does control whether a member appears on the Common or All tab for the Visual Basic IntelliSense list.

DotNetKicks Image
Posted on Thursday, January 8, 2009 8:55 PM .NET (General) | Back to top


Comments on this post: XML Comments: filterpriority

# re: XML Comments: filterpriority
Requesting Gravatar...
Thanks for looking into this. I was wondering too. So as far as you can tell it does nothing in C#?
Left by mike nelson on Jul 15, 2009 5:18 AM

# re: XML Comments: filterpriority
Requesting Gravatar...
Hello,
Any update on this topic? Do you have any report on VS2005 and VS2010.
Left by Paul Selormey on Oct 28, 2009 2:43 AM

# re: XML Comments: filterpriority
Requesting Gravatar...
FilterPriority explained at MSDN.
http://msdn.microsoft.com/en-us/magazine/dd722812.aspx
Left by Anonymous Coward on Apr 15, 2010 3:48 PM

# re: XML Comments: filterpriority
Requesting Gravatar...
Looking forward, there are new possibilities for the way that you might interact with XML comments in code. The Visual Studio 2010 editor is rewritten using Windows Presentation Foundation (WPF) and allows for rich visualizations. The editor updates also involved moving to a new component system, the Managed Extensibility Framework (MEF), which makes it much easier to register add-ins with Visual Studio.
Left by William on Jul 14, 2010 6:08 PM

# re: XML Comments: filterpriority
Requesting Gravatar...
Guys,..
his is contrary to what I would have thought since Microsoft places filter priority tags on classes.
mlmleadsystempro

Left by Johns on Feb 08, 2011 1:57 AM

# re: XML Comments: filterpriority
Requesting Gravatar...
XML is too hard to learn but i am reading all articles like this.
Left by kale kapı on Feb 17, 2011 10:02 PM

# re: XML Comments: filterpriority
Requesting Gravatar...
This is such a excellent article to read. Expecting to see a lot more excellent articles from you shortly.
Left by kimono jiu jitsu on Feb 18, 2011 12:57 AM

# re: XML Comments: filterpriority
Requesting Gravatar...
Hi guys,.. ,....
nice article to read having great useful informative stuff,....i appreciate your effort,..thanks,..
Left by smith on Mar 29, 2011 12:50 PM

# re: XML Comments: filterpriority
Requesting Gravatar...
Hi guys,.. ,....
nice article to read having great useful informative stuff,....i appreciate your effort,..thanks,..

AC Compressor
Left by smith on Mar 29, 2011 12:51 PM

# re: XML Comments: filterpriority
Requesting Gravatar...
Useful ideas shared in this thread having great useful material which is much helpful one for many persons to get this informative stuff,..
Left by Allenc on May 10, 2011 10:26 AM

# re: XML Comments: filterpriority
Requesting Gravatar...
wow buddy
Left by Supalux on Jun 28, 2011 9:46 AM

# re: XML Comments: filterpriority
Requesting Gravatar...
No doubt that it is useful idea and i really like it. There are lot of possibilities. Keep sharing such a wonderful information.
Left by physical therapy business on Sep 30, 2011 1:23 AM

# re: XML Comments: filterpriority
Requesting Gravatar...
I am trying to learn the codes you listed. Thank you for your assistance.
Left by DPL Terapi on Jan 12, 2012 10:25 AM

# re: XML Comments: filterpriority
Requesting Gravatar...
I did recognize that the effects finished not appear 100% repeatable along these lines, for the time being I might be a touch careful depending on the filterpriority tag. I'm going to check whether I can get somebody from either the VB or Visual Studio groups to remark and give some authoritative data on how this tag acts, however until then the main sureness is that it does control if a part shows up on the Common or All tab for the Visual Basic Intellisense rundown.term paper for sale
Left by term paper for sale on Mar 13, 2014 3:23 AM

Your comment:
 (will show your gravatar)
 


Copyright © Scott Dorman | Powered by: GeeksWithBlogs.net | Join free