Showing messages to the user – Extending Visual Studio SharePoint development tools tip #6

While extending the new Visual Studio SharePoint development tools, you can create extensions that do various things: from retrieving content of a SharePoint Site and its properties to manipulating it and exporting into SharePoint Project Items (SPI). As some of these operations might take a while to run, it is considered a good practice to let the user know what the extension is doing at the moment.

If you are creating a custom extension for the new Visual Studio SharePoint development tools there are a couple of ways to let the user know of what the extension is doing at the moment.

Progress v0.1 – The Message Box

First of all there is the Message Box.

Message Box showing progress message

Showing a Message Box in the context of Visual Studio SharePoint development tools is really easy. You can either use the MessageBox.Show() method or its simplified version IExplorerNodeContext.ShowMessageBox().

[Export(typeof(IExplorerNodeTypeExtension))]
[ExplorerNodeType(ExplorerNodeTypes.SiteNode)]
public class MessageSiteExtension : IExplorerNodeTypeExtension  
{
    public void Initialize(IExplorerNodeType nodeType)
    {
        nodeType.NodeMenuItemsRequested += new EventHandler<ExplorerNodeMenuItemsRequestedEventArgs>(nodeType_NodeMenuItemsRequested);
    }

    void nodeType_NodeMenuItemsRequested(object sender, ExplorerNodeMenuItemsRequestedEventArgs e)
    {
        IMenuItem menuItem = e.MenuItems.Add("Show message");
        menuItem.Click += new EventHandler<MenuItemEventArgs>(menuItem_Click);
    }

    void menuItem_Click(object sender, MenuItemEventArgs e)
    {
        IExplorerNode node = e.Owner as IExplorerNode;
        node.Context.ShowMessageBox("Message Box", MessageBoxButtons.OK, MessageBoxIcon.Information);
    }
}

Note, that when working with SharePoint Commands you don’t have access to an instance of IExplorerNodeContext interface and can only use the MessageBox.Show() method.

While the Message Box is probably the most universal and simple way of communicating with the user it might be really annoying to see a Message Box every time the extension performs an operation. Additionally using the Message Box has a serious drawback as it stops the execution of the code as long as the Message Box is being displayed.

In the most scenarios you will probably end up using Message Boxes for communicating about errors and perhaps completed actions that took a longer time to execute. For all other situations both Visual Studio and Visual Studio SharePoint development tools provide some other useful APIs.

Logger – Communication à la Visual Studio SharePoint development tools

The new Visual Studio SharePoint development tools ship with the ISharePointCommandLogger interface which can be extremely useful for communicating the progress of an operation to the user. The messages sent to the logger are being displayed in the Output window of Visual Studio in the SharePoint Tools category:

Messages from the logger displayed in the Visual Studio Output window

Depending on the type of message being logged, the message can also appear in the Error List window:

Messages from the logger displayed in the Visual Studio Error List window

Using the Visual Studio SharePoint development tools logger is pretty straightforward. The instance logger is available through the context information provided to every SharePoint Command. Using the ISharePointCommandContext.Logger property you get a reference of the ISharePointCommandLogger interface which can be used to write messages:

[SharePointCommand(CommandIds.LogMessageCommand)]
private static void LogMessage(ISharePointCommandContext context)  
{
    context.Logger.WriteLine("Hello World", LogCategory.Message);
}

Using the ISharePointCommandLogger.WriteLine() method you can pass additional information about the message being logged including the type of message that you’re logging.

Note, that you can use the SharePoint Command Logger only from a SharePoint Command.

Status bar – used to persist

Another mechanism that you can use to communicate with the user is the Visual Studio status bar. This approach is being heavily used by the Visual Studio SharePoint development tools!

Message from Visual Studio SharePoint development tools in the Visual Studio status bar

Out of the box the Visual Studio SharePoint development tools don’t contain any wrapper to access the Visual Studio status bar, so in order to be able to easily set a message, you can create your own wrapper class.

References

In your project you need the following assembly references:

  • EnvDTE (Embed Interop Types: True)
  • EnvDTE80 (Embed Interop Types: True)
  • Microsoft.VisualStudio.OLE.Interop
  • Microsoft.VisualStudio.Shell
  • Microsoft.VisualStudio.Shell.Interop
  • Microsoft.VisualStudio.Shell.Interop.8.0

You can also paste the following snippet into your project file:

<Reference Include="EnvDTE, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a">  
  <EmbedInteropTypes>True</EmbedInteropTypes>
</Reference>  
<Reference Include="EnvDTE80, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a">  
  <EmbedInteropTypes>True</EmbedInteropTypes>
</Reference>  
<Reference Include="Microsoft.VisualStudio.OLE.Interop, Version=7.1.40304.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />  
<Reference Include="Microsoft.VisualStudio.Shell, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL" />  
<Reference Include="Microsoft.VisualStudio.Shell.Interop, Version=7.1.40304.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />  
<Reference Include="Microsoft.VisualStudio.Shell.Interop.8.0, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />  

Code

To simplify setting messages to the Visual Studio status bar you can create a helper method:

private static IVsStatusbar StatusBar;

internal static void SetStatusMessage(string message)  
{
    if (StatusBar == null)
    {
        StatusBar = Package.GetGlobalService(typeof(IVsStatusbar)) as IVsStatusbar;
    }

    StatusBar.SetText(message);
}

Then, in your code, you can simply call this method to set the text in the status bar:

SetStatusMessage("Hello World");  

Message displayed in the Visual Studio status bar

Summary

While creating extensions for the Visual Studio SharePoint development tools you have to consider communicating the progress of the execution of a command to the user. In the context of a Visual Studio SharePoint development tools extension you can do this in various ways. Depending on your scenario you might choose for one of the approaches described in this article.

Technorati Tags: SharePoint 2010,Visual Studio 2010

Comments

comments powered by Disqus