FogBugz plugins are .NET assemblies that run on the FogBugz server. Plugins interact with FogBugz in two ways: interfaces and APIs. Together, they allow plugins to extend and expand the power of FogBugz.
Interfaces
All FogBugz plugins implement one or more interface. Interfaces control when and how FogBugz calls into the plugin; for example, the methods of the IPluginBugDisplay interface will be called whenever a bug is being displayed or edited, allowing a plugin to add its own display elements to the bug page. A complete list of the predefined interfaces with examples and links to the class library documentation can be found here.
APIs
FogBugz plugins also have access to a variety of plugin APIs (contained in the FogCreek.FogBugz.Plugins namespace) which allow plugins to communicate with FogBugz. For example, an API method might load a CBug object (a case), make changes and commit it back to the database. APIs allow plugins to request a wide variety of data from FogBugz and manipulate it in various ways. More information on the APIs that plugins can use can be found in the FogBugz Class Library Documentation.
FogBugz plugins can be written in any .NET language using whatever tools you prefer. This article uses C# and Microsoft Visual C# Express Edition. It assumes you have installed and are familiar with FogBugz 7 and Visual C# 2008 Express Edtion.
We highly recommend that you install FogBugz locally on your development machine and test your Plugin there, rather than testing it on your live FogBugz server.
Start your plugin project by doing the following in Visual C# 2008 Express:
Reference the FogBugz Assemblies
Every plugin will need references for the FogCreek.FogBugz and the FogCreek.Plugins libraries. They're all located in your FogBugz install directory under Website/bin/
/path to FogBugz/Website/bin/FogBugz.dll
/path to FogBugz/Website/bin/FogCreek.Plugins.dll
To add the references, go to Project > Add Reference..., then select the "Browse" tab and navigate to the files.
Required Assembly Attributes
Open AssemblyInfo.cs, located in the Solution Explorer under HelloWorld > Properties. Add the following required Assembly Attributes:
using FogCreek.Plugins;
[assembly: AssemblyFogCreekPluginId("PluginName@YourDomain.com")]
[assembly: AssemblyFogCreekMajorVersion(2)]
[assembly: AssemblyFogCreekMinorVersionMin(0)]
You can also include a title, description, company, and version, which will show up when your Plugin is installed.
[assembly: AssemblyTitle("HelloWorld")]
[assembly: AssemblyDescription("A timeless classic. Now on FogBugz 7.")]
[assembly: AssemblyCompany("Your Company Name")]
[assembly: AssemblyVersion("1.0.0.0")]
Write the Code
You're now ready to write the plugin class in HelloWorld.cs. Start by adding the namespaces we will use:
using FogCreek.FogBugz;
using FogCreek.FogBugz.Plugins;
using FogCreek.FogBugz.Plugins.Api;
using FogCreek.FogBugz.Plugins.Interfaces;
To start, every FogBugz plugin must inherit from the Plugin class. This is the starting point for your Plugin. FogBugz will instantiate at most one Plugin object from each Plugin Assembly, and call interface methods on this object only.
public class HelloWorld : Plugin
{public HelloWorld(CPluginApi api) : base(api)
{
}}
Our constructor simply calls the constructor of the base class we inherit from (Plugin), passing it the api instance.
To let our plugin add a new page to Fogbugz and put a link to it in the Extras menu, we need to implement two Plugin Interfaces: IPluginPageDisplay and IPluginExtrasMenu. You can see a complete list of interfaces that Plugins can implement in the FogBugz Plugin Interfaces.
public class HelloWorld : Plugin, IPluginPageDisplay, IPluginExtrasMenu
We must now define the following methods required by these interfaces: PageDisplay(), PageVisibility() and ExtrasMenuLinks().
PageDisplay() returns the HTML we want to display, which is inserted within the normal FogBugz page layout. The PageVisibility() method returns a value from the PermissionLevel enumeration, determining who can view our page. We want all normal, logged-in users to see it, so we return PermissionLevel.Normal.
public string PageDisplay()
{
return "<h1>Hello, world!</h1><p>This is my page.</p>";}
public PermissionLevel PageVisibility()
{return PermissionLevel.Normal;}
Next we add a link to this page in the FogBugz Extras menu in the ExtrasMenuLinks() method. CNavMenuLink is the FogBugz standard navigational menu link class. The URL of our plugin's page is set by the api method Url.PluginPageUrl().
public CNavMenuLink[] ExtrasMenuLinks()
{return new CNavMenuLink[] {new CNavMenuLink("Say Hello", api.Url.PluginPageUrl())};}
That's it, you've written a plugin!
Compile your solution in Visual Studio and follow the instructions here to install your plugin. If you built in Debug configuration (the default), you'll find your plugin assembly file under:
/path to your Project/HelloWorld/bin/Debug/HelloWorld.dll
Install your new plugin according to these directions and test it out by selecting "Say Hello" from your Extras menu.
You should see something like this:
For more details such as automatic uploading of your plugin upon compliation and a full sample plugin from start to finish, see the plugin developer's Quick Start Guide. Full Plugin Developer Documentation is also available, covering every inch of the roughly 56 interfaces and 33 APIs with specifications and example code.
If your plugin is only for your use, you're done! If, however you wish to sell your plugin or share it for free, head over to the Plugin Gallery.