How to Write Extensions for WebMatrix
This document provides the basic steps to get you started writing extensions for WebMatrix. The easiest path to take is to use the WebMatrix Extension Visual Studio Project Template. The template is called WebMatrix Extension Template and you can find it in the Templates section of the Extension Manager in Visual Studio or as part of the WebMatrix Extension Kit. The template allows you to create Visual Studio projects that contain a fully functional extension. Also, you can learn about the WebMatrix Extensibility API and explore the sample extension provided in the kit. Once you finish your extension and publish it in http://extensions.webmatrix.com, it will be available to users through the WebMatrix's Extension Gallery.
Getting to know the Extension Template for Visual Studio
The basic functionality of the template extension is to add a Ribbon button and handle activation of that button to open the current web site in the browser. Here is a list of the files and items implemented that you may find useful:
1. ReadMe.txt file: Contains the instructions for setting up the Debug properties to call WebMatrix.exe when running the extension in debug mode.
2. WebMatrixExtension.cs file: Contains an implementation of the abstract class Extension. This class provides the basic ingredients for creating an extension:
a. The abstract method “Initialize(IWebMatrixHost host, ExtensionInitData initData)” is called by WebMatrix at startup. Through ExtensionInitData, you can initialize elements such as Dashboard items and Ribbon controls. The method also allows you to store a reference to the IWebMatrixHost interface that your extension needs in order to access the rest of the WebMatrix extensibility functionality.
b. Methods for implementing custom installation steps: “HasInstaller”, “IsInstalled”, and “OnInstall”.
c. Other tools for implementing your extension, such as icon images and instantiation of classes like RibbonGroup, RibbonItem, and RibbonButton. The relationship among these objects will soon become apparent and will let you get started on more sophisticated constructs.
d. How to take advantage of accepted practices such as the use of delegates when setting up event handlers.
3. DelegateCommand.cs: Contains a definition of the DelegateCommand class, a simple implementation of the DelegateCommand (aka RelayCommand) pattern. It derives from the ICommand interface. It contains basic implementations of the constructors and required ICommand methods and events (“Execute”, “CanExecute”, and “CanExecuteChanged”).
Setting Up and Using the Extension Template
You can use the Visual Studio Extension Manager available under the Tools Menu, select the Online Gallery, click on the Templates tab and search for WebMatrix. Once it is displayed in the list, click download. Alternatively, you can use the WebMatrixExtension.zip file provided in the kit by following these steps:
1. Copy the WebMatrix extension Visual Studio project template (WebMatrixExtension.zip file) provided in the package and save it in your "%USERPROFILE%\Documents\Visual Studio 2010\Templates\ProjectTemplates" directory.
2. Run Visual Studio, and select File -> New Project. In the New Project dialog, select the Visual C# node, and then scroll down to find the WebMatrix Extension list item (see image below). Type a project name (ex: "MyExtension" -no spaces), and click OK.
The project template sets up the project with the configured environment and all necessary references (i.e., Microsoft.WebMatrix.Extensibility.dll). The template includes pre- and post-build steps for installing your extension into WebMatrix, and re-enabled in case of an extension crash. Note that:
It is assumed that you have already installed WebMatrix; otherwise, the APIs referenced won’t be available.
The project created contains a simple Ribbon-based extension that demonstrates some of the basic extensibility points.
The template's ReadMe.txt explains how to configure Visual Studio so that pressing F5 will automatically load the extension inside WebMatrix for a simple, seamless debugging experience with complete breakpoint support. Please make sure to follow the instructions it provides. See the image below:
3. Once you have followed the instructions in the ReadMe.txt file, you can press F5 to build the project and see it running inside WebMatrix.
Using the template with Visual C# 2010 Express
You can also use Visual C# 2010 Express for your development environment. Visual C# 2010 Express can be downloaded for free here: http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-csharp-express.
To create a startup program for your dll extension, follow these steps:
1. Visual C# Express does not allow you to create an external startup program. For debugging purposes, you can add a command line application project to the solution and have the command line application invoke WebMatrix.exe. In the project’s Program.cs file add:
static void Main(string args)
Process webMatrix = new Process();
webMatrix.StartInfo.FileName = @"C:\Program Files (x86)\Microsoft WebMatrix\WebMatrix.exe";
2. In the Solution Explorer, right click the new added project and select Set as StartUp Project.
3. Now you can build your project and press F5 to see your extension loaded inside WebMatrix.
Inspecting your new Extension
1. Open the WebMatrixExtension.cs file and notice that the template generated the <ExtensionName> class which derives from Extension; this class simplifies the work of interfacing with WebMatrix. It also shields you from the work of directly using MEF to implement your Extension.
2. For your extension to be loaded by WebMatrix, it must be located in the following directory: ("%USERPROFILE%\AppData\Local\Microsoft\WebMatrix\Extensions\20RC\<ExtensionName>"). The template already provides the pre- and post-build steps to place your extension in this directory.
3. You can provide content for the Ribbon by adding instances of the relevant classes (RibbonButton, RibbonMenuButton, RibbonGroup, etc.) to the Extension’s RibbonItems collection. This is done only at initialization time through the Initialize method in the Extension class. Once these items are initialized, you cannot change them. You can show and hide Ribbon content as needed, but you can't add or remove items after initialization. There are simple, concrete subclasses for each relevant object (RibbonButton, RibbonMenuButton, RibbonButtonGallery, etc.) so you don't need to spend time implementing them. Using the "helper implementations" is completely optional. Here is sample code from the WebMatrixExtension.cs file:
1. protected override void Initialize(IWebMatrixHost host, ExtensionInitData initData)
3. _webMatrixHost = host;
5. // Add a simple button to the Ribbon
7. new RibbonGroup(
8. "My Group",
9. new RibbonItem
11. new RibbonButton(
12. "My Button",
13. new DelegateCommand(HandleRibbonButtonInvoke),
4. Notice that to create a RibbonButton you need a label, an ICommand implementation, and a small/large image. The sample in the template includes some images that have been configured to provide a working example. Wiring up the images correctly is standard WPF, but the pack URI syntax can be a little tricky. It's common to forget to change the build type of image files to "Resource" - so that has already been done for you. For its ICommand implementation, the template sample uses a simple DelegateCommand class (also included). The sample DelegateCommand is very much in line with other implementations of DelegateCommand or RelayCommand. (Feel free to use whatever version you'd like; the sample DelegateCommand exists simply to avoid introducing a dependency on a third-party library.) As you'd expect, the ICommand's CanExecute and CanExecuteChanged methods are used to dynamically enable/disable the button, and the button's Execute method is called when the button is clicked.
Submit your Extension to the Extension Gallery
Finally, once you are ready to share your extension with the WebMatrix Team, you can upload it here: http://extensions.webmatrix.com .
In summary, the extension template provides you with a basic working extension that you can start with. Also, review the Snippets example included in the package. If you examine it in detail, it will clarify many of the questions you may have and also demonstrate other WebMatrix extensibility points. Once you are ready to share your extension, upload it to the gallery.