Update: Unwittingly, I hadn’t tested my Nuget approach on a server with no Visual Studio or TFS installations on it and I’ve missed a couple assemblies that are required when loading the TFS Object model. I’ve updated the line of code in my samples, but just in case, here is the new version of the line in question.
The update is the addition of two -or statements to the last inclusive where clause.
I’ve also slightly changed the Import-TfsAssemblies function to include a try/catch block for better error reporting.
With the release of Visual Studio 2015 on July 20, 2015, we can talk about and explore a lot of really cool things that are happening with Visual Studio (VS) and Team Foundation Server (TFS). One of the things that has been a bit of a pain when managing a TFS on-premises installation has been the necessity of installing Visual Studio to get the TFS client object model on your administrative workstation. With the explosive use of PowerShell to manage all things Microsoft, this has been a bit of a drag on using PowerShell for TFS work. There are PowerShell modules for TFS in the TFS Power Tools, but sometimes you need the power that comes with using the TFS Object Model. Which meant that you had to install Visual Studio. I'm really glad to say that is no longer the case. With the release of TFS 2015, the TFS Object Model is now available on Nuget! With our trusty nuget.exe, we can now get the TFS object model from a trusted source, without violating any license terms, to use in our own TFS PowerShell modules.
I'm not going to profess to be a PowerShell wizard so I hope I'm not breaking any community best practices too badly. I'm more than happy to adapt my implementation if I get feedback on better ways of doing things! It should also be noted that I'm using PowerShell 4. This is located in the Windows Managment Framework 4 download (http://www.microsoft.com/en-ca/download/details.aspx?id=40855), a free download from Microsoft. I don't **think **you'll have any problems upgrading from previous versions of PowerShell but I'm not going to any assurances.
Let's start walking through building a TFS PowerShell module!
Create A PowerShell Module
I'm not going to go into a lot of details, but the basic steps to creating your PowerShell module are:
- Navigate to %USERPROFILE%\My Documents\WindowsPowerShell\Modules
- Create a folder called MyTfsModule
- In the MyTfsFolder, create a file called MyTfsModule.psm1
It is important that the name of the Module folder and the Module file are the same. Otherwise, you won't be able to load your module. This one requirement tripped me up for a while when I started writing PowerShell modules.
Module-Specific Variables And Helper Functions
There are a few module specific variables that we need to set when the module loads and a Helper function that I use for getting/creating folders. You can put these at the top of your MyTfsModule.psm1 file.
First We Get Nuget
The first thing we need to do is get the Nuget.exe from the web. This is very easily down with the following PowerShell function
Ok! When this function is invoked, we should now see a nuget.exe appear at:
Using Nuget to get TFS Client Object Model
Now that we have nuget, we need to get the TFS Client Object model from nuget.
This function does a could things. First it cleans out the existing bin folder, if it exists. Then it goes to nuget to get all of the packages that are available there. They are:
I use a number of switches on my invocation of the nuget.exe.
- -OutputDirectory – This sets the output directory for the nuget activities
- -ExcludeVersion – This tells Nuget not to append version numbers to package folders
- -NonInteractive – Don't prompt me for anything
The next part seems a bit verbose, but I'm leaving it that way as an example of achieving my intent in case you want to achieve something else. I am intending to get all of the net45, non-portable, base language (non-resource) assemblies from the directory structure that is created by nuget when getting the packages. In order to do that I:
- Find all .dll files in the directory structure, recursively
- Exclude .dll files that have "portable" in their path
- Exclude .dll files that have "resource" in their path
- Include only .dll files that have "net45″, "native", or "Microsoft.ServiceBus" in their path
After I've narrowed it down to that list of .dll files, I copy them all to the TFSOMbin folder where they will be referenced from. This also allows them to satisfy their dependencies on each other as required when loaded.
Loading the TFS Object Models Assemblies
Now that we've retrieved the TFS Object model, and tucked it away in a bin folder we can find, we are now ready to load these assemblies into the PowerShell session that this module is in.
Putting the Object Model to Use
Now that we have the TFS Object Model loaded into this PowerShell session, we can use it! I'm going to show three functions. One that gets the TfsConfigurationServer object (basically your connection to the TFS server), one that gets the TeamProjectCollection Ids and a function that will get a list of all TFS Event Subscriptions on the server.
This function takes a Url and returns an instance of a Microsoft.TeamFoundation.Client.TfsConfigurationServer. This connection object will be authenticated (via Windows Integrated Authentication). If you don't have permission within the domain to administer the TFS server, you won't be able to use the functions provided by the object model. The other functions require this connection in order to do their additional work.
We are using a 3rd party tool that subscribes to build events and we needed to know if it was releasing those subscriptions properly and also discover where this tool was running. We thought that the easiest way to do this was to look at all of the subscriptions in the TFS Project Collections in our AppTier.
We are now all done creating our initial MyTfsModule implementation! We should be able to load it up now and give it a spin!
I've obscured the name of my running module and TFS server, but in those spots, just use the name of your module and TFS server.
The key takeaway from this post was that it is great that we can now get the TFS Object Model from Nuget. Still a bit of a pain to sort and move the downloaded assemblies around, but this is because we I am using PowerShell and not building some sort of C#-based project in Visual Studio which would handle the nuget packages much more elegantly.
I hope this post gives you the information you need to go off and create your own TFS PowerShell module without having to install Visual Studio first!
p.s. I do have a version of this module that loads the assemblies from the install location of Visual Studio. I'll visit that shortly in another blog post.