Samples: Registering Extensions for VSTS.DBPro
Friday is at ZoDD, where I’ll try to bring you some working code samples that leverage features and functionality you can find in the currently released version of Visual Studio Team System 2005 for Database Professionals.
Today begins a series of posts that will deliver on a long-standing, but all-too neglected promise I’ve been making at the various conferences and presentations I’ve done over the last couple of months – namely, providing working samples, with explanations, for two key scenarios that highlight DBPro’s customization capabilities: a Custom Data Generator and a Custom Unit Test Condition.
But this first entry is going to have a very specific focus – how to build and register these customizations in Visual Studio. It may seem a little out of sequence, but both of these customization projects will end up using the steps I’m about to describe, so I figured I’d cover them up front, and get them out of the way – these are, at least to me, the less interesting parts of the projects.
Our customizations are fundamentally Visual Studio add-ons. This means that they need to be registered with Visual Studio as a whole, and if you’ve built other VS add-ons, then this is all going to seem boringly familiar. But for those of you to whom this seems a little more esoteric, follow along, and we’ll have you setting these babies up in no time.
These steps assume you have created a Visual Studio Class Library that you want to register as an extension in Visual Studio for use in DBPro. There are a couple of things you have to do to finish up the output and get it into VS.
First off, you have to build a signed DLL. To do this, open up the Project Properties window, select the Signing Tab, choose Sign the Assembly. You may choose to either specify and existing key, or just create a new one. Unless you have a specific key you want to use, just go ahead and select <New...> Now you can Build the DLL from the Build menu.
Once you have Built the DLL, you need to get it into the Global Assembly Cache, or GAC, because that’s where we expect to find our extensions. If you don’t already know, the GAC is generally under your WINDOWS directory (or WINNT if you’re on a server), as a directory called assembly. In order to get the assembly into the correct directory and registered, you use the gacutil command from a command prompt. If you use a Visual Studio command prompt by going to the Visual Studio Tools menu from the Start menu, the gacutil will already be in your path. If you just use a normal command prompt, you’ll want to add it to your path. It can generally be found at [Program Files]\Microsoft Visual Studio 8\SDK\v2.0\Bin .
Once you have both the gacutil and your freshly brewed DLL in your path, you can push it into the GAC using:
GACUTIL /if NameOfCustomExtension.DLL
Where NameOfCustomExtension is, of course, the name of the custom extension you just built. The /if will install it, and if it is already out there, override it.
Now that it’s in the GAC, we need something from the installed version. If you navigate to the GAC using Windows Explorer, the entries in the assembly directory will have a column called Public Key Token. Find the assembly that you just GAC’d, and copy its public key token – you’ll need it in a minute.
We’re down to the wire here. The last step we need to perform is to tell Visual Studio about our new assembly, and that it can be used in DBPro. We do this by adding an XML file with an extension of extensions.xml into the specific location where DBPro installs: by default, this is [Program Files]\Microsoft Visual Studio 8\DBPro.
The contents of the extensions file are fairly standard, fairly specific, and not very complicated. Here are the entries you’ll need for each individual library you publish. Create a document called NameOfCustomExtension.extensions.xml and open it up with your favorite XML editor – notepad will do just fine. Copy and paste the block below into your new doc. I’ve highlighted the portions that you’ll need to change for each individual DLL.
<?xml version="1.0" encoding="utf-8"?>
<extensions assembly="NameOfCustomExtension, Version=184.108.40.206, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" version="1" xmlns="urn:Microsoft.VisualStudio.TeamSystem.Data.Extensions" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:Microsoft.VisualStudio.TeamSystem.Data.Extensions Microsoft.VisualStudio.TeamSystem.Data.Extensions.xsd">
<extension type="NameOfCustomDLL.NameOfCustomExtensionFeature" enabled="true"/>
Most of these changes should be pretty straightforward – the bulk of all this is to point to the correct namespace for DBPro extensions. Obviously, the NameOfCustomExtension is the name of your DLL, just as above. Replace the Public Key Token with the one you copied from the GAC entry. As to the extension type, well, you could have several extensions in a single Assembly. You would need one of these entries for each of those extensions. We’ll see in detail how this all ties together when we build our first extension next week.
We’re almost done. The only remaining step is to make sure you shut down Visual Studio and reload it before you can expect to see your new features. Visual Studio loads this stuff when it first fires up. And, if everything went as planned, we should be all set!
We’ll be referencing this post in future customization posts, so keep it in mind. I’m still debating whether to start off with a custom Unit Test Condition or a custom Data Generator. In any case, we’ll step through the process and code of building one or the other next Friday.
See ya then!