- | rssFeed | My book on MSBuild and Team Build | Archives and Categories Saturday, 08 June 2013

Introducing VsixCompress–a NuGet package to compress your Visual Studio Package

A few weeks ago I blogged about a Visual Studio extension, Farticus, which I’m working on with Mads Kristensen. In that post I described how the default compression of a .vsix (the artifact that is created for a Visual Studio Package) is not as small as it could be. It’s better to get a fully compressed VSIX because when users install the component the download time can be significantly reduced. In that post I described how you could use the Zip task from the MSBuild Extension Pack to have a fully compressed .vsix file. I will now show you how I’ve simplified this.

Icon for package VsixCompressVsixCompress

Since my previous post I’ve created a NuGet package, VsixCompress which simplifies this greatly. If you have an existing Visual Studio package and want to have a fully compressed .vsix file then all you need to do is install the VsixCompress package.

image

 

After you install this package the following happens.

  1. NuGet package is downloaded and installed to the packages folder
  2. The project is edited to include an import for a new .targets file
  3. The build process is extended to compress the .vsix file automatically

After installing this package once you build the generated .vsix is much smaller than before. In the default case where you select to create a new C# VS Package the created .vsix is 17kb. After adding VsixCompress the resulting .vsix is only 9kb. That’s almost half the size. That’s all you need to know for local development. If you have a build server setup then there are a couple of additional steps. Let’s go over those now.

Build Server Support

I have blogged before about issues of shipping build updates in NuGet. To briefly summarize, when leveraging NuGet Package Restore you have to be careful if any of those NuGet packages have build updates. When using Package Restore the NuGet packages which contain the imported .targets file(s) are restored after the build starts. What this means is that the .targets files will never be imported (or an old copy is imported in the case the file exists from a previous build). The only way to work around this is to restore the packages before the .sln/.csproj file themselves are built. You can read the full details at http://sedodream.com/2012/12/24/SlowCheetahBuildServerSupportUpdated.aspx. I have a NuGet package, PackageRestore, which can help here. Take a look at my previous post How to simplify shipping build updates in a NuGet package. Now that we’ve discussed all the details that you need let’s discuss what my plans are going forward with this.

Plans going forward

I’m hoping to add the following features over the course of the next few weeks.

FYI VsixCompress is open source so you can take a look at the code, or better yet contribute at https://github.com/sayedihashimi/vsix-compress.

Please let me know what you think of this!

Sayed Ibrahim Hashimi | http://msbuildbook.com | @SayedIHashimi

extensibility | Visual Studio | VSIX Saturday, 08 June 2013 01:42:57 (GMT Daylight Time, UTC+01:00)  #     | 
Thursday, 06 June 2013

How to simplify shipping build updates in a NuGet package

Have you ever wanted to ship build updates in a NuGet package? If so then you may have noticed that there are issues if you need to import a .targets file which is contained in a NuGet package. To be brief, the issue is that by the time the .targets file is being restored with NuGet it’s already too late because the build has already started. So we need an easy way to invoke NuGet package restore for a given project before the build for the solution/project starts. In this entry you will see how we can use a generated build script to help with this.

A few months back I discovered this issue and blogged about it at SlowCheetah build server support updated. The solution that I implemented was to create a new build script, packageRestore.proj, which is placed in the root of the project when the SlowCheetah NuGet package is installed. If you want to invoke the package restore from a build server then you can just add packageRestore.proj to the list of items to build before the .sln/.csproj file which you are intending to build. I’ve now refactored this into its own NuGet package, PackageRestore.

 

Here is how you can try it out.

  1. Create a new project
  2. Add a few NuGet packages to the project
  3. Enable NuGet package restore
  4. Add the PackageRestore package (the command you can use is Install-Package PackageRestore –pre)
  5. Close solution
  6. Delete packages folder
  7. Execute the command msbuild.exe packageRestore.proj

After executing the command you will see that the packages folder along with all its content will be restored. For CI servers when you define your build script all you do is build packageRestore.proj before you build the target .sln/.csproj file.

If you are shipping build updates through NuGet and want to be able to enable package restore in a similar way a SlowCheetah then when you create your NuGet package add PackageRestore as a dependency.

 

This is an open source project so you can view the source, and help contribute, at https://github.com/sayedihashimi/package-restore.

 

Sayed Ibrahim Hashimi | http://msbuildbook.com | @SayedIHashimi

msbuild | nuget | PackageRestore Thursday, 06 June 2013 06:57:37 (GMT Daylight Time, UTC+01:00)  #     | 
Wednesday, 05 June 2013

How to publish a VS web project with a .publishSettings file

The easiest way to publish a Visual Studio web project from the command line is to follow the steps below.

  1. Open VS
  2. Right click on the Web project and select Publish
  3. Import your .publishSettings file (or manually configure the settings)
  4. Save the profile (i.e. .pubxml file)
  5. From the command line publish with the command line passing in PublishProfile

For more details on this you can see ASP.NET Command Line Deployment. This is pretty simple and very easy, but it does require that you manually create the .pubxml file. In some cases you’d just like to download the .publishsettings file from your hosting provider and use that from the command line. This post will show you how to do this.

In order to achieve the goal we will need to extend the build/publish process. There are two simple ways to do this; 1. Place a .wpp.targets file in the same directory as the web project or 2. Pass an additional property indicating the location of the .wpp.targets file. I’ll first go over the technique where you place the file directly inside of the directory where the project is. After that I’ll show you how to use this file from a well known location.

One way to do this is to create a .wpp.targets file. This .wpp.targets file will be imported into the build/publish process automatically. This .targets file will enable us to pass in PublishSettingsFile as an MSBuild property. It will then read the .publishsettings file and output the properties needed to execute the publish process.

.wpp.targets in the project directory

Let’s take a look at the .targets file and then we will discuss it’s contents. Below you will find the contents of the full file.

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> 
  
  <!--
  When using this file you must supply /p:PublishSettingsFile as a parameter and /p:DeployOnBuild=true
  -->  
  <PropertyGroup Condition=" Exists('$(PublishSettingsFile)')">
    <!-- These must be declared outside of a Target because they impact the Import Project flow -->
    <WebPublishMethod>MSDeploy</WebPublishMethod>
    <DeployTarget>WebPublish</DeployTarget>
  
    <PipelineDependsOn>
      GetPublishPropertiesFromPublishSettings;
      $(PipelineDependsOn);
    </PipelineDependsOn>
  </PropertyGroup>

  <Target Name="GetPublishPropertiesFromPublishSettings" BeforeTargets="Build" Condition=" Exists('$(PublishSettingsFile)')">
    <PropertyGroup>
      <_BaseQuery>/publishData/publishProfile[@publishMethod='MSDeploy'][1]/</_BaseQuery>
      <!-- This value is not in the .publishSettings file and needs to be specified, it can be overridden with a cmd line parameter -->
      <!-- If you are using the Remote Agent then specify this as RemoteAgent -->
      <MSDeployPublishMethod>WMSVC</MSDeployPublishMethod>
    </PropertyGroup>

    <ItemGroup>
      <_MSDeployXPath Include="WebPublishMethod">
        <Query>$(_BaseQuery)@publishMethod</Query>
      </_MSDeployXPath>

      <_MSDeployXPath Include="MSDeployServiceURL">
        <Query>$(_BaseQuery)@publishUrl</Query>
      </_MSDeployXPath>

      <_MSDeployXPath Include="SiteUrlToLaunchAfterPublish">
        <Query>$(_BaseQuery)@destinationAppUrl</Query>
      </_MSDeployXPath>

      <_MSDeployXPath Include="DeployIisAppPath">
        <Query>$(_BaseQuery)@msdeploySite</Query>
      </_MSDeployXPath>

      <_MSDeployXPath Include="UserName">
        <Query>$(_BaseQuery)@userName</Query>
      </_MSDeployXPath>

      <_MSDeployXPath Include="Password">
        <Query>$(_BaseQuery)@userPWD</Query>
      </_MSDeployXPath>
    </ItemGroup>

    <XmlPeek XmlInputPath="$(PublishSettingsFile)"
             Query="%(_MSDeployXPath.Query)"
             Condition=" Exists('$(PublishSettingsFile)')">
      <Output TaskParameter="Result" PropertyName="%(_MSDeployXPath.Identity)"/>
    </XmlPeek>
  </Target>
</Project>

You can place this file in the root of your project (next to the .csproj/.vbproj file) with the name {ProjectName}.wpp.targets.

This .targets file is pretty simple. It defines a couple properties and a single target, GetPublishPropertiesFromPublishSettings. In order to publish your project from the command line you would execute the command below.

msbuild.exe MyProject /p:VisualStudioVersion=11.0 /p:DeployOnBuild=true /p:PublishSettingsFile=<path-to-.publishsettings>

Here is some info on the properties that are being passed in.

The VisualStudioVersion property indicates that we are using the VS 2012 targets. More info on this at http://sedodream.com/2012/08/19/VisualStudioProjectCompatabilityAndVisualStudioVersion.aspx.

DeployOnBuild, when true it indicates that we want to publish the project. This is the same property that you would normally pass in.

PublishSettingsFile, this is a new property which the .targets file recognizes. It should be set to the path of the .publishSettings file.

 

The properties at the top of the .targets file (WebPublishMethod and DeployTarget) indicate what type of publish operation is happening. The default values for those are MSDeploy and WebPublish respectively. You shouldn’t need to change those, but if you do you can pass them in on the command line.

The GetPublishPropertiesFromPublishSettings target uses the XmlPeek task to read the .publishsettings file. It then emits the properties required for publishing.

OK this is great an all, but it still requires that an additional file (the .wpp.targets file) be placed in the directory of project. It is possible to avoid this as well. Let’s move to that

.wpp.targets from a well known location

If you’d like to avoid having to place the .wpp.targets file in the directory of the project you can easily do this. Place the file in a well known location and then execute the same msbuild.exe call adding an additional property. See the full command below.

msbuild.exe MyProject /p:VisualStudioVersion=11.0 /p:DeployOnBuild=true /p:PublishSettingsFile=<path-to-.publishsettings> /p:WebPublishPipelineCustomizeTargetFile=<path-to.targets-file>

Once you do this you no longer need to create the Publish Profile in VS if you want to publish from the command line with a .publishsettings file.

 

FYI you can find the complete sample at https://github.com/sayedihashimi/publish-samples/tree/master/PubWithPublishSettings.

 

Sayed Ibrahim Hashimi | http://msbuildbook.com | @SayedIHashimi

msbuild | web | Web Publishing Pipeline Wednesday, 05 June 2013 18:01:34 (GMT Daylight Time, UTC+01:00)  #     | 
Saturday, 01 June 2013

Hijacking the Visual Studio Build Process

Have you ever wanted to use Visual Studio to manage project artifacts but wanted to have a fully custom build process? The recommend way to do this is to build a Custom Visual Studio Project System, but there is a much easier way for lightweight needs. In this post I’ll show you how to take an existing project and “replace” the build process used? For example, wouldn’t it be cool if you could develop a Chrome Extension with VS? When you do a build it would be great to generate the .zip file to for the Chrome Gallery in the output folder. Doing this is way easier than you might think.

Before I go over the steps to do this let me explain the “contract” between Visual Studio and MSBuild. The primary interactions around build in Visual Studio include the following actions in VS. Including what VS does when the action is invoked.

For more details you can read Visual Studio Integration (MSBuild). The easiest way to completely customize the VS build process is to do the following:

  1. Create the correct project based on the artifacts you plan on using (i.e. if you’re going to be editing .js files then create a web project)
  2. Edit the project file to not import any of the .targets files
  3. Define the following targets; Build, Rebuild and Clean

After that when you invoke the actions inside of VS the correct action will be executed in your project.

Let’s look at a concrete example. I’ve been working on a Chrome extension with Mads Kristensen the past few days. The entire project is available on github at https://github.com/ligershark/BestPracticesChromeExtension. When it came time to try out the extension or to publish it to the Chrome store we’d have to manually create it, which was annoying. We were using a standard web project to begin with. Here is how we made the workflow simple. Edited the project file to disable the Import statements. See below.

<Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" 
    Condition="false" />
<Import Project="$(VSToolsPath)\WebApplications\Microsoft.WebApplication.targets" 
    Condition="false and '$(VSToolsPath)' != ''" />
<Import Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v10.0\WebApplications\Microsoft.WebApplication.targets" 
    Condition="false" />

For each of these targets I added/updated the condition to ensure that the .targets file would never be loaded. The reason why I did not simply remove these is because in some cases VS may get confused and try to “upgrade” the project and re-insert the Import statements.

After that I added the following statements to the .csproj file.

  <PropertyGroup>
    <LigerShareChromeTargetsPath>$(BuildFolder)\ligersharek.chrome.targets</LigerShareChromeTargetsPath>
  </PropertyGroup>
  <Import Project="$(LigerShareChromeTargetsPath)" Condition="Exists($(LigerShareChromeTargetsPath))" />

Here I defined a new property to point to a custom .targets file and a corresponding Import statement. Now let’s take a look at the ligershark.chrome.targets file in its entirety.

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <UseHostCompilerIfAvailable>false</UseHostCompilerIfAvailable>
  </PropertyGroup>
  <ItemDefinitionGroup>
    <AppFileNameItem>
      <Visible>false</Visible>
    </AppFileNameItem>
    <AppFolderItem>
      <Visible>false</Visible>
    </AppFolderItem>
  </ItemDefinitionGroup>
  
  <UsingTask AssemblyFile="$(BuildLib)MSBuild.ExtensionPack.dll" TaskName="MSBuild.ExtensionPack.Compression.Zip" />
  
  <Target Name="Build">
    <MakeDir Directories="$(OutputPath)" />
    
    <ItemGroup>
      <_AppCandidateFilesToZip Remove="@(_AppCandidateFilesToZip)" />
      <_AppCandidateFilesToZip Include="@(Content);@(None)" />
    </ItemGroup>
    
    <FindUnderPath Path="$(AppFolder)" Files="@(_AppCandidateFilesToZip)">
      <Output TaskParameter="InPath" ItemName="_AppFilesToZip" />
    </FindUnderPath>
    <Message Text="App files to zip: @(_AppFilesToZip->'%(RelativeDir)%(Filename)%(Extension)')" />

    <PropertyGroup>
      <_AppFolderFullPath>%(AppFolderItem.FullPath)</_AppFolderFullPath>
    </PropertyGroup>

    <Message Text="Creating package .zip at [%(AppFileNameItem.FullPath)]" Importance="high" />
    <MSBuild.ExtensionPack.Compression.Zip 
      TaskAction="Create" 
      CompressFiles="@(_AppFilesToZip)" 
      ZipFileName="%(AppFileNameItem.FullPath)" 
      RemoveRoot="$(_AppFolderFullPath)" 
      CompressionLevel="BestCompression" />
  </Target>
  
  <PropertyGroup>
    <RebuildDependsOn>
      Clean;
      Build;
    </RebuildDependsOn>
  </PropertyGroup>
  <Target Name="Rebuild" DependsOnTargets="$(RebuildDependsOn)" />
  <Target Name="Clean">
    <!-- delete all the files in the output folder -->
    <ItemGroup>
      <_FilesToDelete Remove="@(_FilesToDelete)" />
      <_FilesToDelete Include="$(OutputPath)**\*" />
    </ItemGroup>
    <Message Text="Deleting files: @(_FilesToDelete)" />
    <Delete Files="@(_FilesToDelete)" />
  </Target>
</Project>

As you can see I defined the following targets; Build, Rebuild, and Clean. This is what we discussed earlier as the requirements. Now when I click the Build button in VS a .zip file containing the Chrome Extension is created in the bin\ folder. Additionally no other step (i.e. any typical build step) is performed here. The only thing happening is what is defined in the Build target here. Similarly when I Rebuild or Clean the Rebuild or Clean target is invoked respectively. This is  a pretty neat way to modify an existing project to completely replace the build process to suit your needs.

There are a few things in the .targets file that I’d like to point out.

UseHostCompilerIfAvailable

In the .targets file I have set the property declaration <UseHostCompilerIfAvailable>false</UseHostCompilerIfAvailable>. When you are working with a project in Visual Studio there is a compiler, the host compiler, that Visual Studio has which can be used. For performance reasons in most cases this compiler is used. In this case since we do not want any standard build actions to be executed this performance trick is undesired. You can easily disable this by setting this property to false.

After this MSBuild will always be invoked when performing any build related action.

Visible metadata for Item Lists

When using MSBuild you typically represent files as values within an item list. One issue that you may encounter when modifying a project which will be loaded in VS is that the files inside of those item lists will show up in Visual Studio. If you want to disable this for a particular value in an item list you can add the well known metadata <Visible>false</Visible>. For example you could have the following.

<ItemGroup>
    <IntermediateFile Include="cache.temp">
        <Visible>false</Visible>
    </IntermediateFile>
</ItemGroup>

If you don’t want to add this to every value in the item list then you can set the default value using an ItemDefinitionGroup.  For example take a look at the elements below.

<ItemDefinitionGroup>
  <AppFileNameItem>
    <Visible>false</Visible>
  </AppFileNameItem>
  <AppFolderItem>
    <Visible>false</Visible>
  </AppFolderItem>
</ItemDefinitionGroup>

After this declaration is processed if the Visible metadata is accessed for AppFileNameItem or AppFolderItem on a value which does not declare Visible, then false is returned.

 

The rest of the content of the .targets file is pretty straightforward. This post shows a basic example of how you can take an existing Visual Studio project and completely replace the build process.

 

This project is open source at https://github.com/ligershark/BestPracticesChromeExtension.

 

Sayed Ibrahim Hashimi | http://msbuildbook.com | @SayedIHashimi

msbuild | MSBuild 4.0 | Visual Studio | Visual Studio 2012 Saturday, 01 June 2013 18:47:16 (GMT Daylight Time, UTC+01:00)  #     |