I'm pleased to feature an article by Italian author Alessandro Del Sole, who runs http://www.visual-basic.it (see also Alessandro's Blog). You can find the original Italian version of this article on Alessandro's site. If you have questions please contact Alessandro.
Rob
As you know, Microsoft Document Explorer (DExplore.exe) is the Help viewer for Visual Studio documentation since .NET 2002 version. It allows you to browse .HxS help compiled files according to Microsoft Help 2.x standard. In a single instance of this application (you cannot open 2 copies of DExplore Viewer) you can browse any help file on your pc.
But not many people know that it’s possible to work with Document Explorer via managed code, from within your own applications. To realize this job you have some possibilities, strictly related to .NET Framework. You can call Document Explorer writing code according to these choices:
In this article we will analyze the first three choices, while the last one requires very advanced acknowledgments of programming the Visual Studio IDE. If you want to know more about this topic, you can download the Visual Studio 2005 SDK and check inside its documentation.
At this point, you can take a look into the source code I prepared for this article, which is made of three Visual Basic 2005 projects: the first project (ProgrammingDExplore) can interact with Document Explorer while Visual Studio is running, the second project (ExploitDExplore) works with Document Explorer with no Visual Studio instances; the third project (HelpModule.vb) is a macro module.
Why would you need to interact with Document Explorer? Suppose you have realized and deployed some documentation for your application and that it is compiled in .HxS format. At this point, you would need to implement a Help menu in the main form of the application to show the help content. To allow your user to be able to view your application help contents you must provide the capability of opening in Document Explorer using managed code. Reading this article you’ll learn also some advanced practices on how to program Visual Studio 2005 IDE.
Microsoft Document Explorer relies on the .NET Framework. It references a type library which in 2005 version of Visual Studio is called VsHelp80.Olb, while in the previous version it is called VsHelp.Tlb. This library exposes the required objects to work with Document Explorer. It’s very important you also know that VsHelp80.Olb uses and extends VsHelp.Tlb. When running the demo projects, you will notice that when Document Explorer runs without Visual Studio instances, DExplore’s GUI is that referring to .NET Framework versions prior to 2.0 (if installed). As we told before, this is due to VsHelp80.olb referencing old versions.
Visual Studio 2005 Integrated Development Environment relies on the .NET Framework and other particular assemblies whose job is to manage the environment. The main assemblies managing the IDE are EnvDTE80.dll and EnvDTE.dll and reside in C:\Program Files\Microsoft Visual Studio 8\Common7\IDE\PublicAssemblies folder. Since they are managed assemblies like any other .NET assembly, they can be referenced inside your own applications and you can use them to manage the behavior of Visual Studio writing some lines of code. This can appear very unuseful if related to Console or Windows Forms applications, since these techniques imply that an instance of Visual Studio is running. But if you think that Visual Studio 2005 can be extended by the so-called Packages (e.g. custom windows or plug-ins), you can understand how the IDE can be extended because of the capability to write code that interact with the managed assemblies that maintain the IDE, by creating integrated .dll components. In a very similar way you can show the Visual Studio 2005 documentation writing some lines of code, by opening Document Explorer. In this way you can also learn some important basical concepts that allow you to understand how it is possible to interact with the entire IDE. The sample project called ProgrammingDExplore replies the actions made by Visual Studio to show the Help system, using Visual Basic 2005 code.
The main form of the project contains several buttons; each of them is about a peculiar aspect of the documentation.
Describing the user interface is not very useful here (you can easily analyze it downloading the project), while it’s
very important to analyze the code that follows (and that is commented below).
Public Class Form1 'Declares an object that will receive the instance of the Help Window Dim helpObj As ObjectPrivate Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load 'Retrieves the instance about Visual Studio processes Dim dte As EnvDTE.DTE dte = CType(System.Runtime.InteropServices.Marshal.GetActiveObject("VisualStudio.DTE.8.0"), EnvDTE.DTE) 'Retrieves the instance of the Help window helpObj = dte.Help End Sub Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click 'Shows Favorites helpObj.favorites() End Sub Private Sub Button2_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button2.Click 'Shows Index helpObj.index() End Sub Private Sub Button3_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button3.Click 'Shows the How Do I? window helpObj.howdoi() End Sub Private Sub Button4_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button4.Click 'Shows search results helpObj.searchresults() End Sub Private Sub Button5_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button5.Click 'Shows the topic specified in URL 'Notice that the URL below is about the Italian MSDN. You should replace it with a valid URL for your culture helpObj.displaytopicfromurl("ms-help://MS.VSCC.v80/MS.MSDN.v80/MS.VisualStudio.v80.it/dv_radcon/html/f3f63195-82c6-48e8-a4a0-612810e7d093.htm") End Sub Private Sub Button6_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button6.Click 'Looks for the specified keyword inside the index and shows results helpObj.displaytopicfromkeyword("ClickOnce") End Sub Private Sub Button7_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button7.Click 'Shows contents helpObj.contents() End Sub Private Sub Button8_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button8.Click 'Shuts down Document Explorer helpObj.close() End Sub End Class |
The above code makes these jobs:
Each button’s code uses methods belonging to the helpObj object and each of them makes a particular action onto Document Explorer. Try to launch the application and click every button, while Visual Studio is still running. If you try to run the executable with no active istances of Visual Studio you will get an error message. For a complete list of methods you can call to work via code with Document Explorer, you can visit the MSDN web page shown at the end of this article.
By using these programming techniques you can begin to understand how interact with the Visual Studio IDE and these are the basis for the very important concept called Visual Studio Extensibility, the capability of the IDE to be extended by add-ins, which reference the IDE managing assemblies. Something very similar to what we’ve done above.
It’s possible to run Document Explorer from VB code without instances of Visual Studio 2005 running. This can happen because of a COM interface, provided by two type libraries: VsHelp80.Olb and VsHelp.Tlb. Notice that the first one is available only from 2005 version of Visual Studio. When creating a new application, simply add a reference to VsHelp80.Olb library; this will automatically reference the second one.
The second Windows Forms sample project (ExploitDExplore) is made of just one window with just one button. It shows how to use some of the objects exposed by the two type libraries. The primary object for working with Document Explorer is DExploreAppObj. The first step is to instance a new DExploreAppObj object, then you can call its methods. Here is the source code, which will be commented below:
Public Class Form1 'A new instance of VsHelp; this allows to work with Document Explorer
Dim h As New VsHelp.DExploreAppObj()
Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
'The URL above shows informations about beginning Windows Forms applications
'in the Italian documentation for VB Express. Replace with one of your culture.
displayTopic("ms-help://MS.VSExpressCC.v80/MS.NETFramework.v20.it/dv_mancli/html/0a52c679-286e-4615-9368-865410458609.htm")
End Sub
Private Sub displayTopic(ByVal URL As String)
'Sets the collection. The collection below is about Visual Basic Express (Italian)
h.SetCollection("ms-help://MS.VSExpressCC.v80", "")
'Shows the specified topic
h.DisplayTopicFromURL(URL)
End Sub
End Class |
As we said before, after adding a reference to VsHelp80.Olb, we need a new instance of DExploreAppObj (in the example is called h for shortening J ). The displayTopic method shows the help topic specified in the URL argument. This argument must be a valid documentation address (topic URLs appear in Document Explorer’s address bar in a similar way as web-sites addresses appear in Internet Explorer). First of all we have to set the help collection For further studies about collections you can read this article on HelpWare. Once you made this, you can call every help topic.
Code for the only button calls the displayTopic method, passing as an argument the “Introduction to Windows Forms applications” URL of Italian Visual Basic Express documentation. I think you would change this URL with one familiar to your culture.
Similarly to what we saw about the previous sample project, the h object exposes methods to manage Document Explorer, like Close, Index, Contents, HowDoI, Favorites. You can see a the complete list of methods by using Visual Studio’s Intellisense.
Now, build the project, shut down Visual Studio 2005 and launch the executable. In this scenario Document Explorer is open stand-alone even if, as we said before, it will use .NET Framework run-time previous versions. If you have installed just .NET 2.0 you should get an exception.
Remember that in a real life scenario you’ll have to remember to release objects and resources (in this case, disposing h). Since this object comes from a COM library, you have to write the following lines of code:
System.Runtime.InteropServices.Marshal.ReleaseComObject(h) h = Nothing |
I guess the most of you know that macros let you store sequences of activities and repeat these sequences by simply calling its shortcut. The Express Editions of Visual Studio 2005 do not allow macros. To create a new macro there are two ways: the first one, using keyboard and mouse; the second one, writing Visual Basic code inside a special IDE, called Visual Studio Macro IDE.
Interacting with Document Explorer writing a Visual Basic macro is surely the simplest way, since the Macro IDE automatically references the appropriate assemblies that Visual Studio relies on and automatically retrives its active instance. Obviously, this technique requires Visual Studio running too. To create a new Visual Basic macro, run Visual Studio 2005, choose the “Tools” menu and then select the Macro|Macro IDE command. A new VB code file should appear. If it does not, double click on the MyMacros node of the left-sided treeview.
You can notice how in the new module the Macro IDE automatically adds some Imports directives, about namespaces contained in the environment assemblies. Write the following code inside the module body:
Imports System Imports EnvDTE Imports EnvDTE80 Imports System.Diagnostics PublicModule HelpModule Sub HelpObject() 'Retrieves an instance of Document Explorer from within Visual Studio. Dim vsObject As Object = DTE.Help 'vsObject implements methods to call Help windows and topics MsgBox("Shows help favorites.", MsgBoxStyle.Information) vsObject.Favorites() MsgBox("Shows help index.", MsgBoxStyle.Information) vsObject.index() MsgBox("Shows How Do I? window", MsgBoxStyle.Information) vsObject.HowDoI() MsgBox("Shows search window for a given keyword", MsgBoxStyle.Information) vsObject.DisplayTopicFromkeyword("ClickOnce") End Sub End Module |
With some lines of code less, we can assign an istance of Document Explorer (DTE.Help) to an Object field and use its own methods, as shown in the next lines. If you want to see how the code works, press CTRL+F5 to start the new macro without debugging. Document Explorer will run and will execute the actions specified by each method.
Further informations about programming the Visual Studio 2005 Help system via managed code can be found at the following address on the MSDN Library: http://msdn2.microsoft.com/en-us/library/microsoft.visualstudio.vshelp80.help2(vs.80).aspx.
Italian version of this article at http://www.visual-basic.it
If you need to show help topics contained just in .HxS files, Visual Studio 2005 assemblies give you the right solution. Once you learn the concepts shown in this article, you will be able to interact with other IDE’s feautres via managed code. You can find important documentation inside the Visual Studio 2005 SDK, which I suggest you to download. If you have questions please contact me or visit my Italian blog.