Implement ICustomTaskPaneConsumer in C++

The new extensibility interfaces introduced in Office 2007 are implementable via add-ins. Add-ins can be managed or unmanaged (native). If you're using VSTO, development is greatly simplified. However, if you want to build a native add-in to implement one of these interfaces, life is a little more complex – and there doesn't seem to be any documentation on how to do this. What follows here is an exploration of how to build a native (C++ ATL) "shared" COM add-in that implements a custom task pane. You'll see that it's pretty straightforward.

Note: I used VS 2008 to build this example, but the same approach will work with VS 2005.

To start, create a new Shared Add-in project, and select Visual C++/ATL as the target language. Specify a suitable Office host(s) for your add-in (I used Excel) – the remaining wizard options are self-explanatory. The interesting work comes after you've finished the wizard and you have a skeleton add-in project. The tasks required are:

·         Use the Implement Interface Wizard to implement the ICustomTaskPaneConsumer interface.

·         Clean up the wizard-generated implementation slightly.

·         Add an ActiveX control to your project, for use in the task pane.

·         Implement ICustomTaskPaneConsumer::CTPFactoryAvailable to create the task pane, using the specified ActiveX control.

The first thing to do is to implement the ICustomTaskPaneConsumer interface. To do this, in Class View, right-click on the CConnect class, and select Add | Implement Interface. In the Implement Interface Wizard, select the Microsoft Office 12.0 Object Library <2.4> from the list of available type libraries. If this typelib doesn't show up in the list, you can choose to implement interfaces from a specific file instead – and specify the path to the Office 2007 version of MSO.DLL as the location:

From the list of interfaces exposed in the Office typelib, select ICustomTaskPaneConsumer (double-click it, or select it and click the ">" arrow to add it to the list). This will update your CConnect class to implement ICustomTaskPaneConsumer, as shown below:

class ATL_NO_VTABLE CConnect :

       public CComObjectRootEx<CComSingleThreadModel>,

       public CComCoClass<CConnect, &CLSID_Connect>,

       public IDispatchImpl<AddInDesignerObjects::_IDTExtensibility2, &AddInDesignerObjects::IID__IDTExtensibility2, &AddInDesignerObjects::LIBID_AddInDesignerObjects, 1, 0>,

       public IDispatchImpl<ICustomTaskPaneConsumer, &__uuidof(ICustomTaskPaneConsumer), &LIBID_Office, 2, 4>











              COM_INTERFACE_ENTRY2(IDispatch, ICustomTaskPaneConsumer)







       HRESULT FinalConstruct()


              return S_OK;



       void FinalRelease()





       //IDTExtensibility2 implementation:

       STDMETHOD(OnConnection)(IDispatch * Application, AddInDesignerObjects::ext_ConnectMode ConnectMode, IDispatch *AddInInst, SAFEARRAY **custom);

       STDMETHOD(OnDisconnection)(AddInDesignerObjects::ext_DisconnectMode RemoveMode, SAFEARRAY **custom );

       STDMETHOD(OnAddInsUpdate)(SAFEARRAY **custom );

       STDMETHOD(OnStartupComplete)(SAFEARRAY **custom );

       STDMETHOD(OnBeginShutdown)(SAFEARRAY **custom );


       CComPtr<IDispatch> m_pApplication;

       CComPtr<IDispatch> m_pAddInInstance;


       // ICustomTaskPaneConsumer Methods


       STDMETHOD(CTPFactoryAvailable)(ICTPFactory * CTPFactoryInst)


              return E_NOTIMPL;



Depending on whether you imported the typelib based on its registration or its path, the Wizard will also add one of the following two lines to your stdafx.h (ignore the text wrapping here – each #import statement is all on one line without linebreaks):

// Import the Office 12 type library based on its path.

#import "C:\Program Files (x86)\Common Files\microsoft shared\OFFICE12\MSO.DLL" raw_interfaces_only, raw_native_types, no_namespace, named_guids, auto_search


// Import the Office 12 type library based on its registration.

#import "libid:2DF8D04C-5BFA-101B-BDE5-00AA0044DE52" version("2.4") lcid("0")  raw_interfaces_only raw_native_types, no_namespace, named_guids, auto_search

For consistency, change the wizard-generated full function implementation in the .h file, from this:

STDMETHOD(CTPFactoryAvailable)(ICTPFactory * CTPFactoryInst)


       return E_NOTIMPL;


… to a simple declaration, like this:


STDMETHOD(CTPFactoryAvailable)(ICTPFactory * CTPFactoryInst);

... and add the skeleton implementation to the .cpp file instead:

STDMETHODIMP CConnect::CTPFactoryAvailable (ICTPFactory * CTPFactoryInst)


       return E_NOTIMPL;



Also, you might need to modify the #import statement to avoid some name clashes, as shown below. Note: because the list of clashes can be quite long, I've put line breaks in the #import statement in this example:

#import "libid:2DF8D04C-5BFA-101B-BDE5-00AA0044DE52" version("2.4") lcid("0") \

       raw_interfaces_only raw_native_types, no_namespace, named_guids, auto_search \

       rename("DocumentProperties", "msoDocumentProperties") \

       rename("RGB", "msoRGB") \

       rename("IAccessible", "msoIAccessible")

Before you can instantiate a custom task pane, you need a control to put in it. You can use any registered ActiveX control. For simplicity, you can define a new one in your add-in project. To do this, in Class View, right-click on the add-in project, and select Add | Class. From the Add Class dialog, select ATL Control. In the ATL Control Wizard, type in a suitable name (eg, SimpleControl):


When you click Finish, the wizard will generate all the necessary code for a simple ActiveX control. Note the OnDraw implementation, which draws a rectangle and displays a simple string:



       LPCTSTR pszText = _T("ATL 8.0 : SimpleControl");


              (rc.left + rc.right) / 2, ( + rc.bottom) / 2,

              pszText, lstrlen(pszText));


With a suitable ActiveX control, you can now implement the CTPFactoryAvailable function to create a new custom task pane using the control. The first parameter to CreateCTP is the ProgId or CLSID of the ActiveX control. The second parameter is the title to use for the task pane. The third parameter is the IDispatch interface pointer of the parent window. The parent window is only useful in the case of Outlook, where it is the window for the Inspector or Explorer where you want the task pane to appear. In the simple case, you can 'omit' the parent window argument. To 'omit' the arg, you can't just pass NULL. Instead, you should set up a VARIANTARG of type VT_ERROR, with its value set to DISP_E_PARAMNOTFOUND. The fourth parameter is the address of the _CustomTaskPane interface pointer to be filled in by the call:

STDMETHODIMP CConnect::CTPFactoryAvailable (ICTPFactory * CTPFactoryInst)


       _CustomTaskPane* pTaskPane = NULL;

       HRESULT hr = S_OK;

       VARIANTARG vargParentWindow;

       vargParentWindow.vt = VT_ERROR;

       vargParentWindow.scode = DISP_E_PARAMNOTFOUND;


       hr = CTPFactoryInst->CreateCTP(


              CComBSTR(L"Contoso"), vargParentWindow, &pTaskPane);


       if (SUCCEEDED(hr))


              hr = pTaskPane->put_Visible(TRUE);


       return hr;


Set the debug properties of the add-in to specify the path to the Office host application to use as the debug command, and press F5 to build and run:


With the increasing coverage of VSTO for add-ins of all types and for most Office applications, the need to build Shared add-ins is lessening. However, if you need to build an unmanaged add-in, this is still your only option.


Comments (2)
  1. Wes Haggard says:

    Nice sample!

    Here are a couple code review comments 😉

    1) While importing I think it is better do it via typelib registration like you show and it is probably easier to just do an auto_rename instead of figuring out what needs renamed.

    2) Instead of building up vargParentWindow, consider using vtMissing.

  2. Garry Trinder says:

    Wes is correct, of course (thanks, Wes).

    vtMissing is a global variable of type _variant_t, declared in comutil.h, which gets #included (indirectly through comdef.h) when you use #import to generate a .tlh. Comutil.h is also where _variant_t and bstr_t are defined.

    So, the modified implementation below uses vtMissing in place of the manually-constructed VARIANTARG. To maintain consistency with this, I’ve also used the C++ compiler extensions bstr_t type in place of the ATL library CComBSTR type. There’s no particular reason to use one over the other here, other than neatness of using the same type of technique.

    While I was in there changing things, I also replaced the deprecated sprintf with the more secure sprintf_s (which requires the size of the buffer – I’ve also reduced the buffer size to something more sensible).

    STDMETHODIMP CConnect::CTPFactoryAvailable (ICTPFactory * CTPFactoryInst)


    _CustomTaskPane* pTaskPane = NULL;
    HRESULT hr = S_OK;
    //VARIANTARG vargParentWindow;
    //vargParentWindow.vt = VT_ERROR;
    //vargParentWindow.scode = DISP_E_PARAMNOTFOUND;
    //hr = CTPFactoryInst-&gt;CreateCTP(
    //  CComBSTR(L&quot;NativeTaskpaneAddIn.SimpleControl&quot;), 
    //  CComBSTR(L&quot;Contoso&quot;), vargParentWindow, &amp;pTaskPane);
    hr = CTPFactoryInst-&gt;CreateCTP(
        bstr_t(L&quot;Contoso&quot;), vtMissing, &amp;pTaskPane);
    char buf[255];
    // sprintf(buf, &quot;CTPFactoryInst-&gt;CreateCTP [hr=%ld]n&quot;, hr);
    sprintf_s(buf, 255, &quot;CTPFactoryInst-&gt;CreateCTP [hr=%ld]n&quot;, hr);
    if (SUCCEEDED(hr))
        hr = pTaskPane-&gt;put_Visible(TRUE);
    return hr;


    As Wes points out, using the registered typelib with #import is preferred over using the typelib path (assuming the typelib is registered). Also, auto_rename will automatically resolve the name clashes, provided you also remove the no_namespace attribute so that #import-generated code is defined within a namespace. In this example, the namespace will be "Office", so you also need a ‘using namespace’ statement for this (unless you want to fully-qualify a whole bunch of types).

    #import "libid:2DF8D04C-5BFA-101B-BDE5-00AA0044DE52"

    version(&quot;2.4&quot;) lcid(&quot;0&quot;) 
    raw_interfaces_only raw_native_types, named_guids, auto_search 
    //rename(&quot;DocumentProperties&quot;, &quot;msoDocumentProperties&quot;) 
    //rename(&quot;RGB&quot;, &quot;msoRGB&quot;) 
    //rename(&quot;IAccessible&quot;, &quot;msoIAccessible&quot;)

    In discussion with Wes, he’s also pointed out that both my #import and the wizard-generated IDispatchImpl<ICustomTaskPaneConsumer…> specify a version number for the typelib, which ties us to a particular version. Wes is planning to blog about the specifics of this, so I’ll leave that to him 🙂

Comments are closed.

Skip to main content