Creating a Custom Tool (Single File Generator) for Visual Studio 2010

A Single File Generator or “Custom Tool” is a COM “extension” for Visual Studio that takes a project file as input, and spits out some code. (One example is the .settings files) Visual Studio automatically includes the code in your project, and updates it every time you save.

I developed a tool that reads an Office 2010 Ribbon XML file and produces an interface will all the callbacks in your file (because implementing callback signatures is a bear).

Unfortunately, Microsoft’s documentation on the subject is incomplete and obsolete. If you search the web, you will find contradictory information…
I didn’t want my assembly in the GAC, nor did want to have to register the COM object globally. I didn’t want to create a setup project, or use any fancy generated code… I just wanted it to work.

So here are some tips that should get you going.

  1. First of all, there is no need to use the Visual Studio extensibility project template for this. Just create a standard Class Library in the .NET language of your choice.
  2. Add a reference to Microsoft.VisualStudio.Shell.10.0 and Microsoft.VisualStudio.Shell.Interop to your project. (If you do not have these, you probably need to download the Visual Studio 2010 SP1 SDK)
  3. In the Project Properties, in the Application tab, click “Assembly Information…” and check the “Make Assembly COM Visible” box.
  4. Do NOT select “Register for COM interop” on the Build tab
  5. On the signing tab, check sign the assembly, and select or create a key
  6. Add the following using statements to your class file:
    using System.Runtime.InteropServices;
    using Microsoft.VisualStudio.Shell.Interop;
    using Microsoft.VisualStudio;
    
  7. Add the ComVisible attribute
  8. Add a Guid to the class (use the Tools Menu-> Create GUID and select Item 5 for c#, item 6 for vb.net, hit copy)
  9. Make your class implement the IVsSingleFileGenerator interface.
  10. It should look like this:
        [ComVisible(true)]
        [Guid("FAKEGUID-FFF6-4FF3-FFF7-FFFFRFRFRF45")]
        public class Generator : IVsSingleFileGenerator
        {
    
  11. DO NOT USE THIS GUID. YOU MUST GENERATE YOUR OWN
  12. Implement the IVsSingleFileGenerator interface’s two methods – Generate and DefaultExtension (see the documentation for more details)
  13. Build it!
  14. Now for the part where the documentation falls apart – registering and using this bad boy.

  15. The easiest way to register this is using the Visual Studio local registry at HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\10.0
    Note: on 32-bit systems, this may be at HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\10.0 – I am using the 64-bit
    There should be plenty of sub-keys under this key. If there are not, perhaps you need to look in a different version, or bit-ness
  16. First, you need to add the COM information like so
    Windows Registry Editor Version 5.00
    
    [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\10.0\CLSID\{FAKEGUID-FFF6-4FF3-FFF7-FFFFRFRFRF45}]
    "InprocServer32"="C:\\Windows\\SysWOW64\\mscoree.dll"
    "ThreadingModel"="Both"
    "Class"="DemoSFGen.Generator"
    "Assembly"="DemoSFGen, Version=1.0.0.0, Culture=neutral, PublicKeyToken=faketokenfffff88"
    "CodeBase"="file:///C:\\Users\\username\\Documents\\Visual Studio 2010\\Projects\\sfgen\\sfgen\\bin\\Debug\\sfgen.dll"
    

    Replace the GUID after CLSID with the GUID you generated earlier; replace the Class with your Namespace.ClassName; replace Assembly with the information from your dll (I used ILSpy – I’m sure there’s an easier way); replace CodeBase with the full path to your dll.

  17. Next, add the registry info to tell Visual Studio about the Generator:
    Windows Registry Editor Version 5.00
    
    [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\10.0\Generators\{FAE04EC1-301F-11D3-BF4B-00C04F79EFBC}\DemoSFGen]
    "CLSID"="{FAKEGUID-FFF6-4FF3-FFF7-FFFFRFRFRF45}"
    "GeneratesDesignTimeSource"=dword:00000001
    @="Nice Name For your Generator"
    

    The GUID after \Generators\ corresponds to the languages in Visual Studio. See the docs for registering single file generators for a couple (or have a look in the registry).
    The Key name under the language guid (DemoSFGen in this case) is (I believe) how you will refer to the Custom Tool
    The value of CLSID needs to match your generated GUID

  18. Run Visual Studio, open a (different) project, and select an appropriate input file (text, xml, etc) In the properties for the file, add the name of the Custom Tool (“DemoSFGen”).
  19. Right click on the file, and select “Run Custom Tool”
  20. If everything worked, you will now be able to expand the file, and see your generated source underneath it. If there was a problem, Visual Studio may or may not display an error…

I know that Custom Tools aren’t the most often created things in the world, but hopefully these steps can at least get you up and running when you do try.

Undocumented behavior of Office 2010 Word Save As dialog with Sharepoint

Here’s another Office 2010 undocumented “feature”.

First a little background regarding required fields in sharepoint:
In Office 2007, in order to attach the Sharepoint properties to a document you had to first Save it into the document library. Word would allow you to save, but the document would remain checked-out to you until you filled in the necessary required properties, and checked it in.

If you were developing a system that automated adding documents to SharePoint, you could not even present the Document Information Panel to the user until the document was already in SharePoint. If the user decided to cancel… you had hanging files.

With Office 2010, Word (and I imagine other apps) will not actually complete the Save operation to a SharePoint Document Library when there are required fields. You get a warning and the document is _not_ placed in SharePoint, but the Fields from the Document Library are attached to your Word document.

In Word, if you want to display the “Save As” dialog box pre-populated to a SharePoint library you do something like this:

dynamic dlg = Application.Dialogs[Word.WdWordDialog.wdDialogFileSaveAs];
dlg.Name = "http://sharepointserver/doclib/filename.docx";
dlg.Show();

This will act the same as the normal “Save As” dialog.

If you want to handle the save process yourself, instead of dlg.Show(), use dlg.Display. This *should* take no action regardless if the user presses Ok or Cancel. If the destination happens to be SharePoint – intsead of doing nothing like it is supposed to – Word happily retreives the Sharepoint properties and attaches them to your document.

In addition to being handy, Word will attach the document properties to Read-Only and Protected files – which is something you cannot do using CustomXMLParts.
And it’s a heck of a lot easier than trying to build and attach them yourself.

While it is undocumented (and therefore subject to change), it is kind of impossible to work around — Word WILL attach the sharepoint properties, so you might as well take advantage of it.

UPDATE 3/20/2012: Unfortunately, I have discovered that this method is unreliable. On one of our user’s machines, the Save As dialog refuses to display the sharepoint folder at all. I don’t know why, but I wouldn’t recommend relying on this.

Viewing and editing Sharepoint properties on a Word document… again

I have posted before about a method of editing the SharePoint Document properties on a Word document in Office 2010 (and Office 2007). I just found something that completely blew my mind. I spent hours and hours battling with CustomXMLParts, Protected and Readonly documents, and a Save-As dialog… and found out that all that effort was pretty much wasted.

Behold:
_Document.ContentTypeProperties Property
Microsoft.Office.Interop.Word.Document.ContentTypeProperties

ContentTypeProperties is a collection of MetaProperty objects representing (possibly among other things) the SharePoint properties displayed in the server document properties panel. And you can edit them.

So instead of a mess of XML xpath, namespaces, exception handling and “_x0020_”‘s , if you want to edit a sharepoint list column called “Task Id”, you would do the following:

doc.ContentTypeProperties["Task Id"].Value = "task1";

(Yes, you still might need some exception handling…)

The CustomXMLParts will be updated appropriately, and when you save it to sharepoint, the properties will be populated.

Have a look at the members of the MetaProperty object:
.Name = sharepoint internal column name: “Task Id”
.Id = escaped column name: “Task_x0020_Id”
The other properties are what you would expect.

Please note that this will only work if the word document has been “touched” by SharePoint. See my next post for a quick (and undocumented) method of getting those properties attached in Word 2010.

Embedding vzaar video in SharePoint 2010 page

vzaar.com is a video hosting service (kind of like Brightcove, only cheaper) that can be used to stream and manage video content when you don’t want to, or cannot serve it up yourself. You could use youtube, but, well, do you really want to embed youtube in your corporate extranet?

In my case, we wanted to video embedded into a SharePoint 2010 page.

Turns out, sharepoint strips out the embed code pasted into the HTML editor for a page. After much searching (see previous post) I came across a method of embedding flash videos, that is made even easier for vzaar videos by the API.

1. Add a Content Editor web part to your page.
If the page is web part page, this is as simple as clicking any “Add Web Part” link in the page editor.
If it is a “wiki-style” page, you will need to go to the Insert ribbon tab, and select Web Part

2. Select the “Media and Content” category, then the “Content Editor” web part and click Add.

3. Open the Content Editor Web Part properties, paste the “basic embed code (api call)” from the vzaar video, click OK
(To get the basic embed code, in your vzaar video library click the Manage link next to the desired video, and scroll to the bottom)
(To open the content editor properties, either click the dropdown in the web part, or click on the web part and use the Ribbon tab)

That’s it. Your video should now show up embedded right in the sharepoint page.

Embedding flash video in SharePoint 2010 page

The SharePoint 2010 page editor allows you to edit the raw HTML for a page with one huge caveat: it strips out anything it considers unsafe. Including object tags you might use to embed a flash video.

There are quite a few articles / forum posts online with workarounds that either don’t work, or are far too complicated for the average power user.

Then I found this blog post:
Adding Flash Content to SharePoint 2010 / Office 365

While I don’t usually post about things other have already figured out, for some reason Bert’s article took me quite a while to find.

I will be posting a simplified version of his steps for use with the vzaar video hosting service soon.