Craig Skibo's WebLog : Coding

Toys and Thanksgiving

CraigSkibo — Fri, 26 Nov 2004 21:39:00 GMT

So here we are the day after we try our best to gorge ourselves on turkey, stuffing, and many other foods. Hopefully everybody had a good holiday. Today is the traditional start of the shopping spree for the Christmas holiday. Me, I got my shopping done early. Usually the day after Thanksgiving I lock the doors and don’t leave the house, trying to avoid all the traffic and people going nuts trying to get the latest, greatest toy.

I got all my shopping done last week. For Christmas 4 years ago I built a computer for my parents and brother, but last week it stopped working. So I went out to the Dell website and ordered them a new one – so they got their present a few weeks early.

Of course, I also needed to buy myself a few toys. Tuesday I signed up for the new Audiovox 5600 cell phone. There have been some problems switching from my old provider to the new one – they said it could be 6 hours to port my number from the old provider to the new one, but after talking with customer service they said it could take up to 6 days. So right now I need to carry 2 phones with me, the old one and the new one. They also pro-rated the number of minutes I have available, meaning I only have 60 minutes left this month. I also got a Bluetooth headset, which is very cool. Clamp it onto your ear, press a button, and say “Call name in your contacts list”, and it dials. I also connected my Bluetooth GPS receiver to the phone, and I was able to see on the map where I was located.

Last week I got a new Tablet PC for work. Actually, I got it about a month ago. When I first took it out of the box I noticed a small scratch on the screen. So I started testing out the inking features, as I was moving the pen across the screen I noticed the scratch getting bigger. The screen was cracked and it was getting worse. It had to go back to repair the screen.

So how does these new toys relate to VS? Well, I have some ideas for small projects for the phone. I have not done too much with the Smart Device tools in VS, now I will get a chance to play. Also, I have been looking at writing an inking tool for VS, allowing you to make notes in source code using the pen. I have not written anything substantial yet, just some early prototypes. But I will let you know how it goes…

Properties: How they work, why they exist

CraigSkibo — Fri, 26 Nov 2004 21:18:00 GMT

From talking with people, it appears that one area of confusion is over the use of the Properties object. How should you use it, how do the contents of this collection get generated, and why does it exist?

To start off, there is a Properties object available in a few places. The two most common places are from DTE.Properties and from Project.Properties. DTE.Properties is indexed, meaning that there are a number of different Properties objects that can be found. When Visual Studio starts, it goes to the registry key and enumerates all the property category keys from HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\VerMaj.VerMin\AutomationProperties. The categories (Environment, FontsAndColors, Projects, etc.) are used for the first argument to DTE.Properties. Under the top level key, you can then see a list of sub-categories which is passed as the second argument to DTE.Properties. For example, the Environment category has the subcategories Documents, General, Keyboard, TaskList, etc. If you are using Project.Properties, then the contents of the Properties object is hard coded and not dynamic (except if the object has an extender), the project decides what is returned. For languages such as C#, VB, and J#, the object that is wrapped is in the VSLangProj series of libraries (VSLangProj, VSLangProj2, VSLangProj80, depending on the version you are using), and the type is ProjectProperties.

How is a Properties collection generated? When a Properties collection is requested by the user, the method IVsExtensibility::get_Properties is called, passing in an IDispatch object. get_Properties will get the ITypeInfo for this IDispatch object then start walking all the properties available that are not marked hidden or restricted. Then, one Property object is generated for each property (with the get/set operations coalesced into one) on the IDispatch object. Something new in VS 2005 is the aggregation of extenders onto a Properties collection. An extender is a way of attaching your own object onto another object for display in the Properties window. VS 2005 will now look for any extenders on an IDispatch property object and also add those into the Properties collection. These new extender properties have the name Extender.PropertyName name in the properties collection. When you call Properties.Item(SomeName), the GetIDsOfNames of the ITypeInfo method is called, passing in SomeName as the ID to retrieve, then the Property object for that ID is returned. Calling Property.Value will, behind the scenes, call IDispatch.Invoke passing in the ID for the property, the value contained in a VARIANT (or System.Object for you .NET users) is also passed to the Invoke call if setting the value, or the VARIANT is returned if the get version of the property is called.

Where is the type info for these property IDispatch objects? In VS 2002/2003, they live in a few different places. The property objects for objects found off of DTE.Properties(…, …) can be found in EnvDTE – but you may need to look a bit to find them. All the types are marked hidden and restricted, as they are only to be used by code internal to VS. Most also have the format _CategoryNameSubCategoryName, where, as you would expect CategoryName is the category name of the property, and SubCategoryName is the subcategory name. Examples are _EnvironmentGeneral and _EnvironmentDocuments. Some of the text editor properties follow the same format, but rather than starting with an underscore, they start with IVs. Examples: IVsTextEditPerLanguage and IVsTextEditGeneral.

So why do we jump through all these hoops to get this to work? We try to keep the object model static between different versions, that means no big changes that will break code. But the tools options dialog box, the UI that properties wraps, changes a lot between different versions. If we just returned an object that you could program, then the next version your code would most likely not work because the interface shape changed, causing a crash. By wrapping this object with a Property object, if you try to get or set a no longer supported property you will get an exception or bad HRESULT returned to you, but you will not crash (unless you do not catch the returned error).

Application compatibility also caused another problem. When we change an object that is wrapped in a Properties collection, we also need to change the type library / PIA that contains the types. Changing a type library is not good and can cause some compatibility problems, but changing a PIA is downright evil. Just changing a PIA will cause anything that uses that type to no longer load (unless you use binding redirects, which is also a pain). So for VS 2005 we left all the property objects in the EnvDTE library, however we created a new typelibary, dteproperties.tlb, that contains all the new types. Since you really have no need to reference this library from your code, we can now change the property objects over time without causing any side-effects to your apps.

Visual IL

CraigSkibo — Mon, 12 Jul 2004 20:08:00 GMT

After a lot of time spent working on my IL editor and IL project, I finally have a workable version ready for you to try out, if you would like. The MSI file that is linked below, includes code for a project and an editor. The project has templates to create a class library, console application, and a windows form application, supports an automation model, and to make IL development easier, you can even import existing DLL or EXE assemblies into your project (it will be decompiled and the generated IL file will be imported into the project). You can also build your project and then debug the generated code. The language service will do colorization of the IL file, supports statement completion and parameter info for opcodes and keywords, will find TODO comments and add an entry to the task list, and referencing external assemblies is as easy as using the Add Reference dialog box - right click the document and choose Insert Assembly Reference.

System Requirements:

Visual Studio 2005 Beta 1
You must have the VSIP Beta 1 SDK installed, without this the editor and project packages will refuse to load.

Known bugs:

The automation model for the project is not complete.
Renaming a document that is open does not work correctly. You can properly rename them if the file is not open.
If you open a file inside an IL project, close the project, then reopen it, the open file will not reopen.
Parameter tips for all opcodes and keywords do not have descriptive text.
Project and Project Item templates have some bugs. Specifically, there are no replacements done on the templates. For example the Windows Application template has the module name set to WindowsApplication1.exe. The assembly name for a console application is set to Project17. This is because I have not written wizards for generating projects yet.
After running the installer to install, you need to run the command “devenv /setup” from the command prompt to make sure the project and editor are properly installed.

I also found a few bugs in Visual Studio that cause problems with the project:

If you open a C#, VB, J#, etc. application then try to add a project to project reference in the C#, VB, or J# app to the IL project, it will fail to build. I am working with the VS project group to make sure this is fixed before VS final ships.
Parts of the automation model for the IL project will throw a cast exception. This is because of a bug in the EnvDTE PIAs, and should be fixed at least before Visual Studio final ships.

Note that this version will time bomb Aug 1, causing any projects to not load and any IL files you open will appear as if you did not have the packages installed. The reason I did this is because I will be updating the code over time with bug fixes and I would like people to look at the latest code. The time bomb will gently nudge (OK, force) people to use the latest bits. Also, this version does not have source code included. I am not sure when this will be released, after all, this will be the headline sample included with the next version of our book, and we would like to present the code with the text of the book.

Remember that this will be just a sample. While I tried to make it as useable as I could, it is not as full-featured as C#, VB, C++, etc. and does not include features such as a WinForm designer, all the smart tag functionality, etc. This is a beta quality sample, and while I tried to find and fix as many bugs as I could find, there may be the occasional bug which could cause data loss; so use at your own risk. If you do find a bug, please post it here and I will try to fix it as soon as possible.

You can download the code from http://workspaces.gotdotnet.com/VisualIL. When running the installer, the installation key is all 1 values.

New Add-in sample – Add Code Wizard

CraigSkibo — Tue, 27 Apr 2004 04:38:00 GMT

I originally wrote this sample for the wizards chapter of our book, but it really did not fit into the flow of the rest of the chapter. It was a tough cut, but it had to be done. I forgot about it until recently while doing some hard disk clean-up.

So what does this sample do? Visual Studio allows you to create wizards and templates for adding new projects or adding items to a project, but it does not allow you to create templates and wizards for bits of code within a file. This Add-in enables that. Suppose you have a C++ project and you want to insert a new class into an existing file. Simply open your file, make it the active document, and select the Tools | Add Code Wizard menu item. You will be presented with an Add Item-esque dialog box where you can select a template. If the template has the .vsz extension, then the file is launched as a wizard. If the file is of any other type, then it is inserted into the text document.

The sample contains a demo wizard which will insert a class into a C# file, but it will prompt you for the name of the class first (a template file does not do any replacements like changing the class name). To create your own template, simply drop a template file into the appropriate sub-folder in the Templates directory. For example, suppose you used the default install location to install the Add-in into, you can create a new template for the C# file type at “C:\Program Files\Default Company Name\AddCodeWizardAddInSetup\Templates\cs\General”. Have a file type that is not represented by the default templates? Simply create a new folder – for example, you can add a template for .aspx files by creating a “C:\Program Files\Default Company Name\AddCodeWizardAddInSetup\Templates\aspx\General” folder. Also, anything after the file extension portion of the path will appear as a folder on the left side of the Add Code dialog box.

The code and an msi file can be found on GotDotNet Workspaces (http://www.gotdotnet.com/community/workspaces/), just search for Add Code Wizard. Eventually this will probably become a VS Power Toy, but for now it is a beta tool. Have any enhancements, templates, or wizards you would like to add? Send them along and I will try to add them.

Visual Studio Developer Center

CraigSkibo — Tue, 23 Mar 2004 22:15:00 GMT

If you have not noticed, the Visual Studio Developer Center on MSDN is now live. You will be able to find articles, whitepapers, etc. about programming both Automation and VSIP for Visual Studio. Visit the Developer Center at http://msdn.microsoft.com/vstudio/extend.

News, an update, and a tip

CraigSkibo — Mon, 22 Mar 2004 19:45:00 GMT

If you have a MSN Watch, then basketball is now available as a channel. Now if I only liked basketball… Where is baseball and hockey?

An update to my last post: as I suspected, the .NET Framework was not the cause of my performance problems in my Visual Studio language service. When you would scroll through a text document with about 200 lines of code, it would take a few seconds to redraw with each click in the vertical scroll bar – not exactly a well-performing application. A few modifications to the source, and everything is running smoothly now. I am rolling my own tokenizer for a language service and I had one method, IsAtBeginning, which was causing all the problems. IsAtBeginning is given a text string pszText, start at position nIndex, and a second string pszLookFor. IsAtBeginning would check to see if the text given in the variable pszLookFor is at that position nIndex in pszText. Also, the function needs to make sure that the character at nIndex-1 and the character at nIndex+Length of pszLookFor+1 is not a character that keeps the string at that location from being a special token. For example, if pszLookFor is the IL keyword .subsystem, then the function should return true when:

pszText = “.subsystem” and nIndex = 0

pszText = “ .subsystem” and nIndex = 1

pszText = “.subsystem ” and nIndex = 0

pszText = “.subsystem(” and nIndex = 0

pszText = “ (.subsystem” and nIndex = 0

and return false when:

pszText = “X.subsystem” and nIndex = 0

pszText = “X.subsystem” and nIndex = 1

pszText = “.subsystemX” and nIndex = 0

After some experimentation (which included commenting out all of my tokenizer and one by one adding bits of code back), I tracked down the problem to the IsAtBeginning function. Examination of that function showed that I was doing some unnecessary string manipulation – I translated the C++ code “if(!wcsncmp(pszText+nIndex, pszLookFor, wcslen(pszLookFor)) {…}” Into a number of C# string.Substring calls, which is not as efficient. The moral of the story: I always like to blame my code as the culprit before blaming somebody else’s. I could have said it was a problem with the .NET Frameworks, but after some investigation it was my fault.

Here is the code I use now (I am sure there is more optimization I could perform, but for now this is what I am using):

static string specialIDChar = "#$@?_";

bool IsAtBeginning(string text, int index, string lookFor)

{

//If the char before or after is a space, tab, or non alphanumeric,

// (meaning that there is not a character infront of it disqualifying it as our token) then verify

// that the text is what we are looking for:

int lenLookFor = lookFor.Length;

int lenText = text.Length;

if((lenText - index) < lenLookFor)

return false;

char before = (index == 0) ? ' ' : text[index-1];

char after = ((lenText - index) > lenLookFor) ? text[index+lenLookFor] : ' ';

if((specialIDChar.IndexOf(before) != -1) || (specialIDChar.IndexOf(after) != -1) || char.IsLetterOrDigit(before) || char.IsLetterOrDigit(after))

return false;

if(text.Substring(index, lenLookFor) == lookFor)

{

return true;

}

return false;

}

Now the tip: I was recently working on a pet project, a blog reader. The architecture is that I have an engine that manages syncing to and holding blog data, while there is a user control that manages display of the data. The engine defines a couple delegates that the user interface connects to so that it can be informed when a blog is being updated. I have been using serialization to save data to disk, but suddenly I was running into problems where I was getting an exception when trying to save data to disk because the control used to display data was not marked with the [Serializable] attribute. After some investigation, I found that the problem was with the delegates. It turns out that when the control connected to the events fired by the blog engine, and I tried to serialize the engine, it also tried to serialize anything connected to the events thrown by the engine. The solution in this case was to disconnect all events before serializing. This may not work in all cases, but for what I was doing (serializing in the destructor of the class, when any events would not need to fire any longer), it worked just fine.

Adventures in writing managed VSIP packages

CraigSkibo — Tue, 09 Mar 2004 22:48:00 GMT

It has been a little too long since I last made a post. A lot has been going on since the last time I wrote, mostly I have been working on getting bugs fixed for the “Whidbey” build of VS, and work has been proceeding on a new wizards tool for VS (while my last post said I would have some information about this wizard, we decided to wait for any announcements about it). Another task that has consumed my time is my IL editor/project sample. As you may know, I have been working on an IL editor and project system sample. If we get a Whidbey version of our book, then any chapters about VSIP will discuss these samples, and I am looking into getting them into a future version of the VSIP SDK. All major work on these samples were completed over the weekend, and only some minor bugs remain. As I mentioned before, the samples that I have been working on were written using ATL, but after some careful thought I decided that they should be converted to C#. So last night I got the latest build of the Everett Extras (interop assemblies for programming the Everett VSIP model – for now I am doing my development against the Everett version of VS) and sat down to convert my existing code from C++ to C#.

Converting the text editor took me a total of about 4 hours. 4 hours! I was expecting it to be much more complicated than it turned out to be, and most of those 4 hours were spent trying to track down an exception that was being thrown within my colorizer because of a bounds checking bug in my C++ code. I did not have any prior experience using the VSIP Extras SDK before last night, so I cannot say that it was easy because I knew how to use the Extras IAs, it was easy because there were only minor differences between the C++ and C# code.

The process was not flawless, however. I was bitten a few times because of some of the odd data types that the IAs seems to use and the conversion of those types to managed types. For example, there are a number of System.IntPtr objects that are passed back and forth, usually when a WCHAR* type is used on the unmanaged side. In this case you want to call System.Runtime.InteropServices.Marshal.PtrToStringUni to convert to a managed string (not PtrToStringBSTR like I was using at first, which would cause an immediate crash). I also had some problems setting up a service provider, I had to try overriding a number of different methods to get it working correctly – and there may be code in the Extras helpers to handle doing that in a cleaner way (don’t forget the Marshal.QueryInterface method, this will help you a lot when trying to implement your service provider). There also has been a noticeable slowdown when switching to a managed language, but most of that is, I believe, a problem with my code and not so much related to managed code. I am doing a lot of string manipulations in the colorizer, and a quick look over the code reveals many places where I can use StringBuilders rather than strings to speed up my code. I was also using a lot of pointers to keep track of positions into strings for optimizations, and when I converted to C# I had to undo those changes.

The next few days will be spent doing some optimizations on the code, and then I will start working on converting the project code to C#. When this experiment is done the packages will be written in both C# and VC for side by side comparisons, and maybe I will try converting to the other languages also. I don’t know of any packages written using VB and J#, and maybe as a proof of concept of using the IL editor/project I can convert them to IL.

Just as I was getting ready to post this, mail was circulated describing how to proffer a service from managed code using code such as this

container.AddService(service.GetType(), service, false);

inside the Initialize method of a package. I noticed that method last night and tried to use it, but I could not get it to work correctly. I will try it again with my code and see where I went wrong.

Adventures in writing managed VSIP packages

CraigSkibo — Tue, 09 Mar 2004 22:27:00 GMT

Just as I was getting ready to post this, mail was circulated describing how to proffer a service from managed code using code such as this

container.AddService(service.GetType(), service, false);

inside the Initialize method of a package. I noticed that method last night and tried to use it, but I could not get it to work correctly. I will try it again with my code and see where I went wrong.

Using the clipboard

CraigSkibo — Sat, 14 Feb 2004 20:45:00 GMT

Sorry that I have not made a post in a while, but I have been very busy at work lately fixing bugs in the Whidbey object model, as well as working to get a new way of writing wizards ready (more info on that in a few days).

Not too long ago I was browsing the net, and found a code snip that I sent to somebody describing how to use the clipboard from a macro. Because of the way the Macros IDE runs macros on behalf of Visual Studio, there are some problems when trying to access some features of the .NET frameworks. An example of this problem is when trying to access the clipboard. If you were to run this code:

Sub GetCBData()

Dim o As System.Windows.Forms.IDataObject

Dim s As String

o = System.Windows.Forms.Clipboard.GetDataObject()

s = o.GetData(System.Windows.Forms.DataFormats.StringFormat)

MsgBox(s)

End Sub

You would get back an “Object reference not set to an instance of an object.” exception. How do you work around it? You will need to create a new thread, and set the clipboard from within that thread. Here is a class to do just such a thing:

Public Class MacroClipBoard

Dim str As String

Function GetFromProxy() As String

Dim t As New System.Threading.Thread(AddressOf GetFrom)

t.Start()

t.Join()

Return str

End Function

Sub CopyToProxy(ByVal s As String)

str = s

Dim t As New System.Threading.Thread(AddressOf CopyTo)

t.Start()

~~While (t.IsAlive)~~

~~'Do nothing. Wait for the thread to do its work.~~

~~End While~~

t.Join()

End Sub

Sub GetFrom()

Dim o As System.Windows.Forms.IDataObject

o = System.Windows.Forms.Clipboard.GetDataObject()

str = o.GetData(System.Windows.Forms.DataFormats.StringFormat)

End Sub

Sub CopyTo()

System.Windows.Forms.Clipboard.SetDataObject(str, True)

End Sub

End Class

To use this class, you would run code such as this:

Sub testcb()

Dim macroCB As New MacroClipBoard

macroCB.CopyToProxy("Some random string")

MsgBox(macroCB.GetFromProxy)

End Sub

This code only works with string data types, but you could easily modify it to return other types such as bitmaps.

Edit 2/16: I made a small change to the CopyToProxy function, replacing the strike-through text with “t.Join()”

The 54 commandments of COM object model design.

CraigSkibo — Fri, 23 Jan 2004 19:51:00 GMT

There are a plethora of books, tutorials, whitepapers, etc. on the market describing how to use an existing object model. But I have never seen any real description of how to design a COM object model (the .NET framework has design guidelines, but I have not seen one for COM), even though it is a question that I occasionally see on newsgroups, mailing lists, etc. I thought I would share the list of rules that we follow when developing the Visual Studio COM object model. There are a few blemishes in our object model, mostly caused by legacy code in our code base, where we do not follow these rules, but we try to follow them as close as possible. These rules may be applicable to your COM object model (with some changes, such as your root object probably will not be called DTE), and some are applicable to .NET development (translate HRESULTs to exceptions). I encourage you to make a list of rules such as this when you design an object model, it makes defining the objects much easier and consistent.

1. No UI is shown to the user when calling a method except in the case where the method name implies that UI will be shown. (Examples of this exception are ExecuteCommand and PromptToSave).

2. UI is never shown when calling a property (BUG: ItemOperations::PromptToSave)

3. Retrieving the value of a property should not cause side-effects to the object model. For example, calling the get_FullName property should not cause the file to be saved to disk.

4. All objects use only OLE Automation types.

5. When methods/properties take a numerical index, that index must be 1 based (first item is 1, not 0).

6. Item on collections objects is a method, not a property.

7. _NewEnum on collections objects is a method, not a property.

8. Items that are accessed from a collection have a property called Collection that returns the collection that generated the object, except in the case of a ‘2’ interface.

9. All objects that are not accessed from a collection have a property called Parent that returns the object that created the item, except in the case of a ‘2’ interface.

10. All objects have a DTE property that returns the DTE object, except in the case of a ‘2’ interface.

11. All collections end in an ‘s’, or the plural form of the object it is a container of.

12. All collections have the properties/methods (in addition to Parent & DTE) Count, Item and _NewEnum.

13. All event objects are returned from the DTE.Events[2] object.

14. A failure HRESULT should never be returned from a property. If a property returns an object and an object is not available to be returned, then the property must return S_OK and NULL. If a string should be returned but a string is not available, then the empty string (“”) should be returned. If the value is numeric, return 0, and if the value is an enumeration then a enumerated value such as None should be returned. The only time it is permissible to return an error code from a property is if the object has been zombied, and there is no such property value to return. (Undetermined scenario: what if the property takes an argument?)

15. If a method returns an object, and an object is not available to be returned because an index was supplied and that index does not exist, the HRESULT E_INVALIDARG is returned.

16. If a method returns an object, and an object is not available for reasons other than an indexing problem, the HRESULT E_FAIL is returned and the out parameter is set to null/NULL/Nothing.

17. A method should avoid taking an automation object as an argument; instead, the method should accept the argument which could be passed as the index to the collection’s Item method. This avoids the case where the user spoofs an object. An example where we violate this rule and why it is bad: Commands.AddNamedCommand. The user could implement the interface AddIn (either because they don’t understand the model or they are up to no good), and pass this interface as the first arg to AddNamedCommand. Internally, we could use this interface in ways the bad passed-in version does not expect, and we would fail (fail either with a bad HRESULT, or catastrophically).

18. If a pointer is passed to a method, and that pointer is invalid (because it is NULL, etc), then the HRESULT E_INVALIDARG is returned except in the case where the argument is returning data back to the caller, then the HRESULT returned is E_POINTER.

19. All enumerations have the form: [Product Abbreviation][EnumType]. For example, the enumeration for the state of a window (Normal, Maximized, and Minimized) is called vsWindowState.

20. The values in a enumeration have the form:[Product Abbreviation][Enum type abbreviation][Value]. For example, the name of the window minimized state is vsWindowStateMinimized.

21. All general objects have a Kind property that returns a GUID that uniquely identifies the object type (for example, there is a Kind on Window, Project, ProjectItem and ProjectItems)

22. If a general object can return one or more specific objects, then those objects are returned from an Object method that takes a string parameter, or an Object property that takes no arguments. The string argument is used if the object can supply more than one object type. It is suggested that even objects that have only one specific object take a string parameter (for compatibility in the future when multiple objects are available). The string should be case insensitive. An example of this is the Document.Object method, which can return a TextDocument (if the TextDocument parameter is passed).

23. Properties that return a complete path to a file on disk are called FullName.

24. Properties that return the modified state of an item (an item that has not yet been committed to disk) are called Saved.

~~25.~~ All methods that set an item to the item with focus are called Activate. By convention, calling Activate on an item does not necessarily make its container active. For example, calling Activate on a tool box item does not make the tab that contains that item active. Similarly, making an item active does not make the tool box window active.

26. The name of a method that removes an item from a collection is Delete if that item is a UI element (example: ToolBoxTab)

27. The name of a method that removes an item from a collection is Remove or Delete. Use Remove if it is non-destructive, Delete if it is destructive. Example: Solution.Remove removes a project from the solution, but does not delete it from disk. Commands.Delete removes the item from the collection, and destroys any data associated with that command causing it to no longer be available to the user.

28. All Remove & Delete methods are on the specific item’s object, not its collection.

29. The method to add an item to a collection is called Add. It is located on the Collection that creating a new item will add it to.

30. Properties (not to be confused with the Properties object, these are properties with a lower case p) should not take arguments, they should be methods.

31. All collections are returned via properties except if the item takes an index, then the collection is returned with a method. These properties are named the same as the object they return.

32. Any item that creates a user interface element does not make that element visible. Rather, the element object is returned, and the Visible property on the element can be used to make it visible. All other methods/properties that affect UI is made immediately. Example: CreateToolWindow does not show the window, you must specifically call Visible.

33. The most meaningful visible name of an Object is a property, and it is given a dispid of DISPID_VALUE making it the default value (for example, the Name of an object is made the default).

34. All objects should contain a default method or property. If the object is a collection, the default method should be the Item method. If the object is a collection item, then the default property should return the name of the object.

35. If an object has a default property, you should be able to use that default property as the index in the collection Item method.

36. Once a type library for an automation object has been shipped, under no circumstances shall that type library or the PIA wrapper around that type library be modified. It is set in stone. That same exact type library and PIA will be shipped for all future versions of the product.

37. If new functionality is needed after shipping an object model, then any interface definitions are placed in a new idl file, type library, and PIA.

38. If new functionality is needed to add to an existing interface, then a new interface is created in a new type library, the name of the interface is the OldInterfaceNameX (where X is a consecutive number beginning with 2), and the new interface derives from the old interface.

39. If a method needs to be modified by the addition or removal of new arguments, rules 37, 38, and 39 are to be applied, the method name should be OldMethodNameX (where X is a consecutive number beginning with 2), and the new method should follow, as closely as possible, the same order of arguments as the old method. For example void Foo(int bar, int baz) becomes void Foo2(int bar, int baz, int blah).

40. If a new interface is added to an object (such as an OldInterfaceName2 interface), then the new interface is accessible by casting an instance of the object to the new interface.

41. Care should be used to make sure that the COM DISPIDs of InterfaceName and InterfaceName2 do not conflict.

42. If a new interface is added to an object, all methods and properties should return an instance of the old interface, not the new one. Example: Windows2.CreateToolWindow2 returns a Window object, not a Window2 object.

43. Except to get to an extended version of an object, casting an object to get to an automation interface should be avoided. Another exception to this rule is for service-level interfaces, such as IDispatch, ISupportErrorInfo, LifetimeInformation etc.

44. No interfaces begin with the letter I unless the name of what is being modeled begins with an I. For example, IncrementalSearch is OK, but IWindows is not. The exception to this is if the interface is to be implemented by the user. Example: IDTExtensibility2, IDTCommandTarget, etc.

45. If your type library defines an interface that the user must implement, then that interface begins with the letters IDT, as in IDTWizard, IDTExensibility2, IDTToolsOptionsPage.

46. If a ‘2’ interface is added, the methods / properties DTE, Item, Parent, _NewEnum, Collection or any other method or property that has a name the same as the ‘1’ interface is not added to the new interface. These methods / properties are inherited from the ‘1’ interface.

47. If an interface (called Interface’) has an .Object method / property, any Parent properties on the object returned (called Interface’’) should return the Interface’ object, not the Parent of Interface’.

48. No arguments of a method (except the return argument, i.e. those marked with the IDL attributes [out, retval]) are to use Hungarian notation. They should (again with the exception of [out, retval] arguments) use Pascal casing.

49. Property, method, interface, and coclass names should use Pascal casing.

50. Dispinterfaces should start with the name _disp, and use camel casing (eg: _dispSolutionEvents)

51. Interfaces which shadow coclasses should have the same name as the coclass, except prepended with the underscore character. Example, _DTE the interface, DTE the coclass.

52. All interfaces must at least have the IDL attributes odl, dual, oleautomation, object, uuid, and helpstring.

53. All methods and properties must use at least the IDL attributes id and helpstring.

54. All automation consumable interfaces must derive from either IDispatch, or another interface which derives from IDispatch.

Use VSASSERT to help debug

CraigSkibo — Tue, 13 Jan 2004 22:03:00 GMT

Here is a second tip for debugging that requires a slight .h file change. If you have the VSIP SDK installed and you need advanced assert help, use VSASSERT. VSASSERT is a nifty utility that is installed with the VSIP SDK that will put up an assert message. The advantage of this assert technology over the CRT or ATL’s assert is that you can hide all the VS asserts for that instance of VS, selectively choose to hide a particular assert, copy the assert text to the clipboard, break into the debugger at the line of the offending assert, etc. To use this assert, you need to #include the file vsassert.h into your code, and then for the debug build of your code link to vsassert.lib. Then, rather than using VC’s assert mechanism, you use VS’s like so:

VSASSERT(false, "This is a failed assert.");

Even though the assert ships with the VSIP SDK, your code does not need to be VSIP related to use VSASSERT, the code can be a VSIP package, an Add-in, or even code that is not related to VS, you just need to be using C++.

Now to the problem: To use VSASSERT, you will need to change a header file to get everything to work. If you were to compile anything that #includes vsassert.h, you will get the following error message:

c:\Program Files\VSIP 7.1\EnvSDK\common\inc\vsassert.h(249): fatal error C1017: invalid integer constant expression

You can fix this by opening vsassert.h, and on line 249 change the text from:

#if DEBUG

#ifdef _DEBUG

This simple change will fix up the problem, and you can start using a much better assert tool. (And yes, there is a bug tracking this to have somebody fix it)

Fix debugging QIs in ATL code

CraigSkibo — Mon, 12 Jan 2004 23:28:00 GMT

I have been doing a lot of VSIP package writing lately. While I was writing a project for VS I wanted to find out which interfaces VS is looking for on my package so I could implement those interfaces. I decided to turn on ATL’s QI tracking feature to make tracking down these interfaces easier. You can turn this feature on with a simple bit of code such as the following in the stdafx.h file:

#ifdef _DEBUG

#define _ATL_DEBUG_QI

#endif

What will happen is, with this code, every time an object in your project has its QueryInterface method called, it will dump a line of text such as the following into the VS output window:

CProjectHier – IUnknown

This means that the method CProjectHier::QueryInterface was called and it was passed an IID of IID_IUnknown (meaning that the caller wants the IUnknown interface). When the QI is called and it cannot supply the requested interface, it dumps out a line of text such as:

CProjectHier - IVsPersistHierarchyItem – failed

Because I have not yet implemented IVsPersistHierarchyItem on the CProjectHier class, ATL kindly tells me that the QI failed. I can then browse the text of the output window, see which interfaces I need to implement, and then implement them. Great! It saves me the time of wading through MSDN!

However, there is a bug in this mechanism. Since the bug is in a debugging feature and not in something that will affect production code (you should not ship code with this feature on, hence the #ifdef _DEBUG in the code above), this is not a serious problem. When ATL looks up the interface name of the IID that is passed to QI, it looks in the registry under HKEY_CLASSES_ROOT\Interface\{IID}, and takes the default value under this key as the name of the interface. These values are placed there when you register a typelib with the system; the API call LoadRegTypeLib will look at all the interfaces, coclasses, etc. in a tlb and place the correct entries under HKCR\Interface.

Many of the interfaces for the VSIP SDK are not defined in a tlb, they are defined only in .h or a metadata assembly if you are using the Extras SDK, and since they are not in a tlb the IIDs for an interface are never registered. The ATL code has a small bug in it that if the IID for the interface is not registered then it will print something like this for a successful QI:

CProjectHier –

or something like this if the QI failed:

CProjectHier – - failed

As you can see here, the name of the interface is missing. You can easily change the code in ATL to fix this. First, browse to the ATL include directory (“C:\program Files\microsoft visual studio .net 2003\vc7\atlmfc\include” if you used the standard install path) and open the file atlbase.h. Next, search for AtlDumpIID and replace it with the following code:

#if defined(_ATL_DEBUG_INTERFACES) || defined(_ATL_DEBUG_QI)

__forceinline HRESULT WINAPI AtlDumpIID(REFIID iid, LPCTSTR pszClassName, HRESULT hr) throw()

{

USES_CONVERSION_EX;

CRegKey key;

TCHAR szName[100];

DWORD dwType;

DWORD dw = sizeof(szName);

LPOLESTR pszGUID = NULL;

if (FAILED(StringFromCLSID(iid, &pszGUID)))

return hr;

OutputDebugString(pszClassName);

OutputDebugString(_T(" - "));

LPTSTR lpszGUID = OLE2T_EX(pszGUID, _ATL_SAFE_ALLOCA_DEF_THRESHOLD);

#ifndef _UNICODE

if(lpszGUID == NULL)

{

CoTaskMemFree(pszGUID);

return hr;

}

#endif

// Attempt to find it in the interfaces section

if (key.Open(HKEY_CLASSES_ROOT, _T("Interface"), KEY_READ) == ERROR_SUCCESS)

{

if (key.Open(key, lpszGUID, KEY_READ) == ERROR_SUCCESS)

{

*szName = 0;

if (RegQueryValueEx(key.m_hKey, (LPTSTR)NULL, NULL, &dwType, (LPBYTE)szName, &dw) == ERROR_SUCCESS)

{

OutputDebugString(szName);

}

else

{

goto Error;

}

else

{

goto Error;

}

// Attempt to find it in the clsid section

else if (key.Open(HKEY_CLASSES_ROOT, _T("CLSID"), KEY_READ) == ERROR_SUCCESS)

{

if (key.Open(key, lpszGUID, KEY_READ) == ERROR_SUCCESS)

{

*szName = 0;

if (RegQueryValueEx(key.m_hKey, (LPTSTR)NULL, NULL, &dwType, (LPBYTE)szName, &dw) == ERROR_SUCCESS)

{

OutputDebugString(_T("(CLSID\?\?\?) "));

OutputDebugString(szName);

}

else

{

goto Error;

}

else

{

goto Error;

}

else

OutputDebugString(lpszGUID);

if (hr != S_OK)

OutputDebugString(_T(" - failed"));

OutputDebugString(_T("\n"));

CoTaskMemFree(pszGUID);

return hr;

Error:

OutputDebugString(lpszGUID);

OutputDebugString(_T("\n"));

return hr;

}

#endif // _ATL_DEBUG_INTERFACES || _ATL_DEBUG_QI

Now, when an interface name cannot be found, it will display the IID of the interface in the name’s place. It is still not as convenient as printing the name of the interface, but at least you will get something. You can then search over the header files for that IID to see what interface you need. This is much better than putting a breakpoint on your COM map and watching every single QI, then checking to see if it succeeds or fails.

And remember, this code is not just for VSIP (although that is how I found the problem), you can use this code for all projects.

Custom command bitmaps 101

CraigSkibo — Thu, 08 Jan 2004 23:28:00 GMT

This is the tutorial I promised on how to create buttons with custom UI in the VS object model.

A common question that I get is how can you add a custom bitmap to a command placed on a tool bar and have that bitmap support transparency. Getting this to work is not very complicated, but getting everything just right so the transparency works can be a little tricky.

To make this work, you are going to need VS with VC for the DLL that contains the bitmap, and an Add-in written in any supported language; such as C#, VB, or VC. The first step is to run the Add-in wizard, making sure to select the option to create a command and put a button on the tool bar (check the first checkbox on page 4 of the wizard). After finishing the wizard, right click on the solution node and select Add | New Project. Select Visual C++ Project in the tree on the right of the Add New Project dialog box, and Win32 Project on the left of this dialog box. Enter a project name; I suggest something like ProjectNameUI, where ProjectName is the name of the Add-in you are creating.

In the wizard that appears, select Application Settings, and then select the DLL radio button. After pressing the Finish button, a VC DLL project will be added to the solution, the starting point for a Satellite DLL project. To create the resources, right click on the project you just added, select Add | Add New Item, and add a new “Resource File (.rc)” item to the project. This will add a resource file to the project and show the Resource View tool window. Right click the top node of the resource added, select Add | Add Resource, select Bitmap, and then click the New button. This will add a bitmap to the resources. By default, the bitmap is too big for our needs, so open the properties window and type 16 into both the Height and Width properties. You can also enter the value 1 for the ID property.

Using the drawing tools, draw your bitmap, but do not use the lime green color, we will use this for the transparent color. To set the correct transparent color, select lime green in the Colors tool window then select Image | Adjust Colors. In the dialog box shown, enter 0 for red and blue, and 254 for green, then press OK. You can now fill in the transparent areas with the lime green color. With your bitmap created, you are now ready to make the modifications to the Add-in so it can load the Satellite DLL and the custom bitmap.

In the Add-in source code, find the AddNamedCommand method call, which by default should look something like this:

Command command = commands.AddNamedCommand(addInInstance, "MyAddin9", "MyAddin9", "Executes the command for MyAddin9", true, 59, ref contextGUIDS, (int)vsCommandStatus.vsCommandStatusSupported+(int)vsCommandStatus.vsCommandStatusEnabled);

You will want to modify the true value so that it reads false, and change the value 59 to the value you entered for the ID value in the properties window, which, if you are following along with this tutorial, is the value 1.

The last steps are to make the changes so that your Add-in can load the Satellite DLL. When the Add-in wizard was run, a file named ReCreateCommands.reg was created in the project directory. If you open this file, it will look like this:

REGEDIT4 [HKEY_CURRENT_USER\SOFTWARE\Microsoft\VisualStudio\7.1\AddIns\MyAddin9.Connect]

"CommandPreload"=dword:1

Add these entries, supplying the appropriate Satellite DLL name where appropriate (the name of the project I created was MyAddin9), then merge the file ReCreateCommands.reg into the registry:

"SatelliteDLLName"="MyAddin9UI.DLL"

"SatelliteDLLPath"="C:\\Documents and Settings\\craigs\\My Documents\\Visual Studio Projects\\MyAddin9"

Lastly, you need to put the Satellite DLL in the correct location. In the value given by SatelliteDLLPath in the .reg file, create a folder with the name of the VS locale you are running. For example, I am running US English VS, so I created a folder named C:\Documents and Settings\craigs\My Documents\Visual Studio Projects\MyAddin9\1033 since 1033 is the code for US English. Then copy the Satellite DLL into that folder.

After following these steps, you will have a button on the tool bar which uses a custom bitmap, and has a transparent color.

Commands and UI

CraigSkibo — Sat, 13 Dec 2003 07:30:00 GMT

(Copied from weblogs.asp.net/craigskibo)

Today was a big source code check-in day. I sent well over 50 files to be checked into our source code control system, and I will be here late sending off a lot more. What kind of things did I change? Well, one of the most asked for features is the ability to add different UI types to a CommandBar, and with different settings.

For example, today when you call Commands.AddNamedCommand we will create a command. You can then add UI to a command bar for that command with the Command.AddControl method. But that UI element is always a button, not combo boxes, not menu controllers (the split drop-down button like that for the undo / redo command), etc. The change for Whidbey allows you to specify which control type should be used. This is the enum that contains the different control types available (this list is subject to change, either with the addition or subtraction of additional elements):

enum vsCommandControlType

{

vsCommandControlTypeSeparator = 1,

vsCommandControlTypeButton = 2,

vsCommandControlTypeMenuButton = 4,

vsCommandControlTypeSwatch = 8,

vsCommandControlTypeSplitDropDown = 16,

vsCommandControlTypeDropDownCombo = 32,

vsCommandControlTypeMRUCombo = 64,

vsCommandControlTypeDynamicCombo = 128

} vsCommandControlType;

The second problem that people have with the AddNamedCommand/AddControl combination is in how all commands you create have both text and a picture, you cannot change the UI to have just text, just the bitmap, etc. This is the enum that we have defining the different types available (again, subject to change):

enum vsCommandStyle

{

vsCommandStylePict = 1,

vsCommandStyleText = 2,

vsCommandStylePictAndText = 3,

vsCommandStyleContextUseButton = 4,

vsCommandStyleTextMenuUseButton = 8,

vsCommandStyleTextMenuControlUseMenu = 16,

vsCommandStyleTextCascadeUseButton = 32,

vsCommandStyleComboNoAutoComplete = 64,

vsCommandStyleComboCaseSensitive = 128

} vsCommandStyle;

Of course, we have fixed a number of the usability problems developers would have when developing Add-ins. In versions of VS prior to Whidbey, if you would run the Add-in wizard, press F5, then kill the debugged process, you command would be lost and you would need to run devenv /setup to reset the state (which would also reset any of your customizations). We changed when we save data saying that the UISetup stage of your Add-in ran from startup to shutdown, fixing this common problem. We also decided today on a few other enhancements to make developing Add-ins easier, stay tuned for more details…

Commands and UI

CraigSkibo — Sat, 13 Dec 2003 03:46:00 GMT

enum vsCommandControlType

{

vsCommandControlTypeSeparator = 1,

vsCommandControlTypeButton = 2,

vsCommandControlTypeMenuButton = 4,

vsCommandControlTypeSwatch = 8,

vsCommandControlTypeSplitDropDown = 16,

vsCommandControlTypeDropDownCombo = 32,

vsCommandControlTypeMRUCombo = 64,

vsCommandControlTypeDynamicCombo = 128

} vsCommandControlType;

enum vsCommandStyle

{

vsCommandStylePict = 1,

vsCommandStyleText = 2,

vsCommandStylePictAndText = 3,

vsCommandStyleContextUseButton = 4,

vsCommandStyleTextMenuUseButton = 8,

vsCommandStyleTextMenuControlUseMenu = 16,

vsCommandStyleTextCascadeUseButton = 32,

vsCommandStyleComboNoAutoComplete = 64,

vsCommandStyleComboCaseSensitive = 128

} vsCommandStyle;