Extending the packaging process of the Visual Studio SharePoint development tools
The new Visual Studio SharePoint development tools ship with a broad support for the process of developing SharePoint solutions. One part of that process is packaging SharePoint artifacts into a WSP package and deploying it to a SharePoint server. By know you probably know that the Visual Studio SharePoint development tools are highly extensible, but did you know that you can even extend the way how the Visual Studio SharePoint development tools package SharePoint artifacts?
Looking at the plumbing of every SharePoint project created using the new Visual Studio SharePoint development tools, you will see, that the project file uses a custom MSBuild target file called Microsoft.VisualStudio.SharePoint.targets. This file contains all the information that the tools need to turn your SharePoint project into a WSP package.
If you have worked with the tools or at least have read about them, you probably know, that the tools are very flexible. Comparing to other tools that we know from SharePoint 2007 projects, the Visual Studio SharePoint development tools allow you to layout your SharePoint artifacts in any way that you want it (comparing to using the 12 folder we used a lot with SharePoint 2007 tools). Additionally, to increase your productivity, the tools ship with Replaceable Parameters – tokens that you can use in your project files, that will be replaced in the build process and that allow you to include for example the fully qualified name of your assembly.
The build process, based on the MSBuild definition, does the heavy lifting and automatically replaces all the tokens and puts all the files in the right place so that a WSP package can be built and you can focus on the actual solution instead of the plumbing.
Extending the Visual Studio SharePoint development tools packaging process 101
While the build process is very powerful and will probably suffice for most of you, there are scenarios when you could want to extend the way the Visual Studio SharePoint development tools create the WSP package out of your project. There are two locations in the build process that you can use to add your custom logic. Both are represented by an MSBuild Target that you can override in your SharePoint project.
First of all there is the BeforeLayout target. As the name says, it allows you to define some custom logic just before the Visual Studio SharePoint development tools start laying out the files. As I already mentioned, you can layout the files in your SharePoint project in any way you want to. In the layout process the tools use the metadata for every SharePoint Project Item (SPI) to put it at the right place for the packaging process. The BeforeLayout target allows you to alter the SPI’s before they will get copied to the intermediate location.
The second place is marked by the AfterLayout target. This target is being executed after Visual Studio SharePoint development tools have copied all files to the intermediate folder (where from they will be picked up by the packaging task) and just before the actual packaging happens. If there is anything that you would like to change about your files before they will be put in a WSP, that’s the place to do it.
Extending the packaging process Hands-On
The very first thing that you need to do, in order to extend the packaging process, is to create a custom MSBuild targets file. It can be as simple as:
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" />
Please note that the above code snippet is the minimal content that your custom targets file has to have and it doesn’t do anything yet. You can save your file anywhere on the file system but it is a good practice to save it within your project’s folder tree and, in case you’re using a source control system, add it to source control as well.
The next step is to hook up your custom targets file with the build process. You can do this in your project file (.csproj for C# projects). You can edit it either using your favorite text editor or from Visual Studio click right on your project and choose Unload Project.
Once the project has been unloaded (its icon is grey), you click right on the project again and choose Edit Project.csproj from the menu.
Once you get to the contents of your project file, you have to scroll down to the bottom of the file and find the Microsoft.VisualStudio.SharePoint.targets file:
Just below you can add the link to your own targets file:
After you saved your project file, you can reload the project by click right on the Project and choosing Reload Project from the menu.
Please note that every change to either the project file or a targets file requires you to reopen your solution in order to see the changes.
While the our custom targets file is now hooked up with the build process it doesn’t do anything yet. Let’s change this by adding to it the following code:
<Target Name="BeforeLayout"> <Message Importance="high" Text="About to move the files around..." /> </Target> <Target Name="AfterLayout"> <Message Importance="high" Text="Files moved. Let's package!" /> </Target>
If you save the targets file, close and then reopen the solution and choose Package from the Project menu you should see your custom messages in the project build output:
Although this all, as well as what you could achieve with it, might seem a little vague at this moment, it offers you really great extensibility possibilities. In my next article I will give you an example why you might need this kind of extensibility in your projects. In the meanwhile, if you are interested in getting to know how Visual Studio SharePoint development tools do the packaging, I would recommend you to take a look at the Microsoft.VisualStudio.SharePoint.targets file located in C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\v10.0\SharePointTools.