In this post, we’ll see how to implement a Vercue Extension using Visual Studio and C#.
Topics covered by this post:
What are Vercue Extensions
Implementing a button that runs an action on the selected Source
Implementing a button that runs an action on all available Sources
Run an async action
Run an action based on user-properties
Vercue can be extended to add UI elements and/or automation actions and macros.
For example, new command menu items can be added to the Sources and Log-Entries panels. New custom Actions can be implemented and used in automated Rules, and more.
Implementing such extensions is easy and fast, using Visual Studio and a .NET programming language, such as C#.
In this post, we will implement some custom menu-commands for a Source.
Extending the Source Menu
Sample 1: Run a command based on the Source’s built-in properties
First, we’ll see how to implement a command that executes an action on the Source’s built-in properties, such as its path (in case it is a Working-Copy).
A useful action we can implement will be a button that commits changes of a selected source with a predefined message. A one-click commit button. For example, committing a conflict-less reintegration-merge.
Step 1: Create the extension class library in Visual Studio
Create a new Visual Studio C# class library project, give it a meaningful name (“VercueExtension”, for example) and make sure the target framework is 3.5, to match Vercue’s framework version:
Add a reference to the Vercue.Library.dll file, which should be located under Vercue’s installation folder (C:\Program Files (x86)\Vercue\Vercue.Library.dll)
Step 2: Create the extension class
Add a new class and implement the Vercue.Extensibility.IExtension interface:
Step 3: Create the One-Click Commit method:
Step 4: Introduce the command to the UI:
Step 5: Build and Install
Build the project. Locate the output dll file and copy it to %appdata%\Vercue\Extensions.
Restart the application. Your new extension should be loaded and available from the Source’s context menu.
Notice that the command is available from the context-menu, the main menu, the Sources pane’s toolbar, the main toolbar and the tray-menu.
Sample 2: Run a command on all the available items
How about a button that runs svn-cleanup on all the Working-Copies?
The command runs on all the available Working-Copy sources, so it has to be always enabled.
The Enabler property of the command has to be an always-true predicate:
Build, copy, restart the application and you can start using your new cleanup action!
Notice that the svn-cleanup command is time-consuming. If you have many Sources – it can take minutes to complete. Let’s change the command to run on a background-thread so it doesn’t block the user-interface. In-addition, while the application keeps executing svn commands on the Sources (checking for updates), the Cleanup command might fail. Let’s also add some error-handling to the command:
Notice that this is only a sample. Error handling, user-notifications and command-availability are up to you to implement. For example – disabled the command until the cleanup is complete to prevent multiple clicks.
User-Properties and Values
Vercue allows the end-users to add custom properties and values to Sources. These custom values can be used in Rules conditions and Actions (Next post will discuss this feature).
Another use for such values is in UI commands.
Sample 3: Run a command based on user-values
Let’s see an example of a command that uses Source’s user-specific values.
A useful example can be a button that opens a Source’s project file. Referring to a .NET project, the file will probably be a .sln file (A Visual Studio solution), but the command may suit any type of file, as long as Windows knows how to open it.
The only important difference between this implementation and the previous one is the fact that we now use a user-property instead of a built-in one.
We want the command to be enabled only for Sources that have the “project” user-property.
Here’s the Enabler predicate for such condition:
Built and copy the dll to its destination folder.
Adding User-Properties to a Source
Double-click a Source, click the “User Properties” button.
In the Source User Properties dialog, add a key named “project” and set its value to the name of the project/solution file within the folder:
Click OK on all the dialogs and you can now test your command.
In-order to debug the extension – all you need to do is attach to the Vercue.exe process and click the command you just added. Place a breakpoint in your action method and it will break there.
More things to explore
- Log-Entries and Log-Entries Items: In addition to Source commands, an extension can add commands to the Log-Entries menu and to the Log-Entry Items menu using the UICommandExtensionInfo<SvnLogEntry> and UICommandExtensionInfo<SvnLogEntryItem> classes
- SelectedItems vs. AllItems: The ExtensionEventArgs object contains also an AllItems property which contains a list of all the items in the relevant collection, and not only the selected ones. For example, a instance of ExtensionEventArgs<SvnSource> will contain all the available Sources.
- Svn Commands: The Vercue.Extensibility.Utils.Svn class has various static methods that can be used to perform common svn actions, such as Update, Revert, Cleanup and Commit, which we used in this post. Explore the class and see what else is available.
In the next post, we will implement some automation extensions, such as custom Actions, Macros and Monitors.