Output Window Service |
The Output Window package provides support for extensions to create and use the Output Window in Visual Studio using MEF.
Library Status: Public
To ensure broad compatibility across a wide range of project configurations and Visual Studio versions, the Output Window Service is distributed through several different NuGet packages.
Output Window Service Extension: Installation of this package is required to ensure the Output Window Service functionality is available to your extension within Visual Studio.
Output Window Interfaces Library: Installation of this package is required if your Visual Studio extension uses or provides any Output Window functionality.
In the project which creates your VSIX file (i.e. the project which contains the source.extension.vsixmanifest file, add a NuGet reference to the Tvl.VisualStudio.OutputWindow package. After installing the NuGet package, you will need to configure your extension to inform Visual Studio of the dependency by including the following block in your source.extension.vsixmanifest file.
Important |
---|
At this time, two versions of the VSIX manifest file are available. Make sure to use the code snippet relevant to the version used by your project. A version 1 manifest starts with <Vsix Version="1.0.0", and a version 2 manifest starts with <PackageManifest Version="2.0.0". |
<Reference Id="Tvl.VisualStudio.OutputWindow.3EF11167-A319-43DB-B1B4-A9778A90FAE0"> <Name>Visual Studio Output Window Services</Name> <VsixPath>Tvl.VisualStudio.OutputWindow.vsix</VsixPath> </Reference>
<Dependency d:Source="File" DisplayName="Visual Studio Output Window Services" Id="Tvl.VisualStudio.OutputWindow.3EF11167-A319-43DB-B1B4-A9778A90FAE0" Version="[2.0.1,)" d:InstallSource="Embed" Location="Tvl.VisualStudio.OutputWindow.vsix" />
Note |
---|
A future release of this extension may include a feature to configure the source.extension.vsixmanifest file automatically. |
The Output Window Interfaces Library should be installed in any package which uses the Output Window Service. The library is available in the Tvl.VisualStudio.OutputWindow.Interfaces NuGet package, which supports extensions targeting any combination of Visual Studio versions starting with 2010.
This service allows extension developers to declare custom output window panes, as well as write content to the standard panes provided by visual studio (e.g. Debug or General).
Writing content to the output window consists of the following steps.
Get an instance of IOutputWindowService. This is typically performed by using the MEF [Import] attribute, as described in the documentation for IOutputWindowService.
Obtain the desired IOutputWindowPane from the output window service by calling TryGetPane(String). The sections below describe the predefined panes, as well as the process for creating custom panes.
Write the message(s) to the output window by calling WriteLine(String) or Write(String).
The output window service provides access to several output window panes defined by Visual Studio, as well as two additional panes created by this extension (used in a variety of other extensions created by Tunnel Vision Labs). These panes my be accessed by passing one of the PredefinedOutputWindowPanes fields for the name parameter to TryGetPane(String).
Custom output window panes may be declared by exporting the OutputWindowDefinition contract using MEF. Output window panes declared in this manner initially hidden from the Output Window each time Visual Studio starts. The pane will become available in the Output Window automatically the first time TryGetPane(String) is called with the name of the custom pane. For more information and examples, see the documentation for OutputWindowDefinition.
Since this extension exports a new MEF service for use across multiple extensions and multiple versions of Visual Studio, extremely careful consideration must be given to several implementation details to ensure consumers will not encounter conflicts in the future or be subjected to cumbersome workarounds.
Assembly Versioning: To ensure long-term compatibility of this extension with many other extensions, all communication between the MEF-exported Output Window service and consumers of the API is performed through a dedicated interfaces assembly, Tvl.VisualStudio.OutputWindow.Interfaces. Following the initial release of this extension, the contracts defined by this assembly (e.g. the strong name and API) will never change. If the source for this assembly is ever updated, it will only be in ways that are guaranteed to not cause problems for existing installations, such as updated XML documentation or updating the NuGet packaging to simplify the installation process.
Assembly Binding: Since the Tvl.VisualStudio.OutputWindow.Interfaces assembly does not appear in a <MefComponent> element within source.extension.vsixmanifest, there are a number of situations with traditional deployments where Visual Studio may be unable to locate the assembly at runtime. To avoid this situation, the Tvl.VisualStudio.OutputWindow extension created for the implementation of the Output Window Service registers its installation folder in the Visual Studio binding path using the [ProvideBindingPath] registration attribute. This feature ensures that the Output Window interfaces assembly will be available to all Visual Studio extensions, regardless of the manner in which they are deployed.