Andrew Whitechapel : VSTO Power Tools

Ribbon and Task Pane in Access Add-ins

andreww — Thu, 22 May 2008 19:38:00 GMT

In an earlier post, I looked at how you could morph a VSTO project for one application into a project for another application – specifically, how you could build a VSTO add-in for Access. Note that this is explicitly not supported. However, although this was only intended as an investigative exercise, I notice that some people have added comments to the post asking for further information about things like custom Ribbons. So, to continue the investigative exercise, I’ll look today at how you could build on a VSTO Access add-in to implement custom task panes and Ribbons. The following discussion builds on the Access add-in I discussed in the earlier post.

Recall that you have two options for building custom task panes and Ribbons: you can use the low-level approach of implementing the interfaces directly; or you can use the VSTO wrapper classes and designer support. Let’s look at both options. Many moons ago, I introduced the VSTO low-level support in a blog post, and the updated documentation for the technique is here. Documentation on the VSTO CustomTaskPane wrappers and Ribbon designer are here and here.

To build a custom task pane (regardless of whether or not I use the VSTO wrappers), I must first set up a custom UserControl of some kind (which I’ll call SimpleControl). Then, for the low-level approach, I need to write a class that implements ICustomTaskPaneConsumer. In the CTPFactoryAvailable method, I’ll simply cache the ICTPFactory object for later use, eg:

public class TaskPaneHelper : ICustomTaskPaneConsumer

{

internal ICTPFactory taskPaneFactory;

public void CTPFactoryAvailable(ICTPFactory CTPFactoryInst)

{

taskPaneFactory = CTPFactoryInst;

}

In my ThisAddIn class, I declare a couple of fields: one for this helper class, and one for the Office CustomTaskPane PIA object:

private TaskPaneHelper taskPaneHelper;

internal Office.CustomTaskPane taskPane;

Then, I must override the RequestService virtual method to return an instance of my helper class:

protected override object RequestService(Guid serviceGuid)

{

if (serviceGuid == typeof(Office.ICustomTaskPaneConsumer).GUID)

{

if (taskPaneHelper == null)

{

taskPaneHelper = new TaskPaneHelper();

}

return taskPaneHelper;

}

return base.RequestService(serviceGuid);

}

Finally, add code to my ThisAddIn_Startup method to instantiate the task pane:

private void ThisAddIn_Startup(object sender, System.EventArgs e)

{

if (taskPaneHelper.taskPaneFactory != null)

{

taskPane = taskPaneHelper.taskPaneFactory.CreateCTP(

"MyAccessAddIn.SimpleControl", "Contoso", Type.Missing);

}

Next, the Ribbon. In the Solution Explorer, I can right-click on the project and select Add New Item. From the New Item dialog, I select a Ribbon XML item (not the Ribbon Visual Designer item), and name the new class RibbonX. This generates some code in RibbonX.cs and some Ribbon XML. I follow the generated comments to move the override of CreateRibbonExtensibilityObject into the ThisAddIn class. Then, I’ll modify the RibbonX.xml to give me one ToggleButton:

<?xml version="1.0" encoding="UTF-8"?>

<tabs>

<toggleButton id="toggleTaskPane"

onAction="toggleTaskPane_OnAction"

label="TaskPane"

imageMso="ControlLayoutStacked"

size="large" />

</group>

</tab>

</tabs>

</ribbon>

</customUI>

Note: I used the ImageMso RibbonIDs VSTO Power Tool to get the imageMso value.

In my RibbonX class, I implement the button onAction handler to toggle the visibility of the custom task pane:

public void toggleTaskPane_OnAction(Office.IRibbonControl control, bool isPressed)

{

Globals.ThisAddIn.taskPane.Visible = isPressed;

}

That’s it. I can now press F5 to test-run my prototype.

Now that I’ve looked at how to do this using the low-level support, I’ll look at the alternative approach of using the VSTO wrappers and designers. First the custom task pane. If I’m using the VSTO wrappers, I can delete the TaskPaneHelper class altogether, including the TaskPaneHelper field in the ThisAddIn class, the override for RequestService and the code I previously added to ThisAddIn_Startup. I also need to change the type of my taskPane field from the Office PIA type to the wrapped VSTO type:

//internal Office.CustomTaskPane taskPane;

internal Microsoft.Office.Tools.CustomTaskPane taskPane;

The only other thing I need to do is to use the VSTO CustomTaskPanes collection object in my ThisAddIn_Startup method:

private void ThisAddIn_Startup(object sender, System.EventArgs e)

{

//if (taskPaneHelper.taskPaneFactory != null)

//{

// taskPane = taskPaneHelper.taskPaneFactory.CreateCTP(

// "Word2AccessAddIn.SimpleControl", "Contoso", Type.Missing);

//}

taskPane = this.CustomTaskPanes.Add(new SimpleControl(), "Contoso");

}

F5 again, and this should behave exactly as before.

Next, the Visual Ribbon designer. I can delete the previously-generated RibbonX.cs and RibbonX.xml, and the override for CreateRibbonExtensibilityObject. Instead, I’ll add another new item – this time, a Ribbon Visual Designer item, and I’ll name the class VisualRibbon. I can use the designer to put a ToggleButton on the custom tab, and set its properties (including using the same ImageMso RibbonIDs power tool for the OfficeImageId property).

The one slight anomaly is that I need to set the RibbonType property of the custom Ribbon to a string that matches the string that the host application will pass in when it calls the IRibbonExtensibility.GetCustomUI method. Previously, when I used the low-level support, this was irrelevant, because it is not actually used in the code anywhere. However, this value is used by Outlook because Outlook supports multiple custom Ribbons for multiple message classes. For this reason, the VSTO Ribbon Visual Designer allows you to set this property, and offers a dropdown list of the known valid property values. These include values such as “Microsoft.Excel.Workbook”, “Microsoft.Outlook.Appointment”, etc. Of course, there is no VSTO Access support, so the dropdown list does not include the value that Access will pass in. Access will pass in the value “Microsoft.Access.Database” – so you need to set this value manually in the code (in the VisualRibbon.Designer.cs, which contains the InitializeComponent method and other methods in the hidden part of the partial class):

this.RibbonType = "Microsoft.Access.Database";

Finally, I can implement the Click handler for my new ToggleButton to behave in the same way as in my low-level implementation:

private void toggleButton1_Click(object sender, RibbonControlEventArgs e)

{

Globals.ThisAddIn.taskPane.Visible =

((Microsoft.Office.Tools.Ribbon.RibbonToggleButton)sender).Checked;

}

That’s it – F5 to test.

As before, note that this is not a supported scenario: there are 2 reasons for this post. The first reason is to explore the possibilities off the beaten track of officially documented features in VSTO – purely in the interests of scientific curiosity. The second reason is to make an important point about the strategic design of VSTO add-ins. We’re very careful to build our tooling and runtime support in such a way that it does not block support for potential additional hosts. As I’ve shown, there’s nothing in the VSTO add-in class, the VSTO custom task pane wrappers, or the VSTO ribbon wrappers and designers that prevents their use with host applications that are not (yet) supported – even host applications that themselves do not yet support task panes or ribbons.

VSTO Power Tools

andreww — Thu, 06 Mar 2008 03:14:00 GMT

I announced the release of v1 of the VSTO/VSTA Power Tools last time, and they've been getting quite a bit of use so far. The downloads are here - these include an overview document. Note that the documentation for the individual tools is installed in the same folder where you install the tools themselves.

Phil Hoff, who was one of the developers working on the Office Interop API Extensions library has a number of very interesting blog posts, and I encourage everyone to check them out - there's lots of useful information in these posts, and I hope Phil will keep them up.

These steps explain how you can file bugs and suggestions for the VSTO/VSTA Power Tools. We review these on a regular basis, so if you find a bug or have a suggestion, please submit them:

1. Go to Microsoft Connect at http://connect.microsoft.com/default.aspx.

2. Sign up or log in to the site.

3. On the left menu, click Available Connections.

4. On the next page, click Visual Studio and .NET Framework.

5. On the next page, choose one of the following:

To see if your issue already exists, click Start Here. In the Search Feedback box, search for the issue. If the issue does not exist, click Submit Feedback. On the next page, click Bug Submission Form or Suggestion Submission Form.

-OR-

To submit a bug or suggestion, click Submit a Bug or Submit a Suggestion.

6. On the submission form, enter the required information. In the Description box, specify “VSTO/VSTA Power Tools”.

7. When you are finished, click Submit.

You can also post comments/bugs/feedback to this blog.

VSTO/VSTA Power Tools v1.0

andreww — Thu, 21 Feb 2008 23:03:00 GMT

As I announced at the Office Developers Conference in San Jose this week, we’re releasing a set of power tools that complement the developer’s experience when building Office-based or VSTA-based solutions. These tools are freely downloadable here. We’re releasing these tools independently of our normal Visual Studio release cycle – even though in many cases we are considering rolling them into Visual Studio itself in a later release.

These tools are unsupported – if we wanted to officially support them, we’d have to invest a lot more resources in thorough implementation and testing. If we were able to invest the required level of resources, we would most probably have included them in the product in the first place. So, it’s a delicate balance: they’re unsupported because we couldn’t test them very thoroughly – but on the upside, this does allow us to release them outside the normal VS release schedule. Here’s a summary of the tools in this release:

Tool	Description	Type of Tool
Open XML Package Editor	A graphical treeview-based editor for examining and editing Open XML Package files (including Word, Excel and PowerPoint documents).	Add-in to Visual Studio.
Ribbon IDs ToolWindow	A custom tool window that displays all re-usable built-in Office Ribbon IDs.	Add-in to Visual Studio.
Office Custom UI Manager	A set of classes for coordinating multiple instances of Ribbon, custom task pane, and custom form region objects.	Runtime class library source code.
Office Interop API Extensions	A set of C# classes for handling parameterized properties and optional/named parameters, as well as for LINQ-enabling Office collection objects.	Runtime class library.
SharePoint Feature Sweeper	A GUI tool that cleans up unwanted SharePoint features from the developer's environment.	Standalone Windows Forms application.
SharePoint Workflow Package Generator	A tool to package a SharePoint workflow project so that it can be deployed.	Console application.
VSTO/VSTA Pipeline Verifier	A GUI tool that reflects over custom pipeline assemblies to validate the complete VSTA pipeline.	Standalone Windows Forms application.
VSTO Developer Cleaner	A GUI tool that removes leftover build artifacts from the developer's computer.	Standalone Windows Forms application.
VSTO Troubleshooter	A diagnostic tool that examines a computer for the necessary pre-requisites for running VSTO solutions.	Standalone Windows Forms application.

We’re obviously very interested in getting customer feedback for these tools, including any bugs that surface – and even though they’re unsupported, we will do our best to accommodate feature requests and bug fixes in any later updates to the tools. We’re hoping that this strategy of releasing independent tools will allow us to respond in a more timely fashion to identified customer requirements.