How to update projects to the current SPSF version/enable SPSF on existing projects?

This post is part of a series which shows how you get the most out of SPSF.

Introduction

After installing a new version of the SharePoint Software Factory it is recommended to update the Visual Studio projects which have been created with an earlier version in order to assure that changes/new features and bug fixes of SPSF kick in. This applies only to files which are used to configure SPSF or assure the build and deployment procedure. Other files in your solution (like xml, cs, images etc.) will not be touched.

Scenarios

The steps described in this post can be used for the following scenarios:

  • Upgrade a SharePoint solution already using any SPSF version to the newest version
  • Configure a standard VisualStudio SharePoint solution to use SPSF (meaning adding SPSF functionality)
  • Add a new standard SharePoint project into an SPSF solution, so that it is included in the deployment package
  • Fix an SPSF solution which doesn’t package or build as expected

Files affected by the Update

The upgrade process creates/updates some or all of following files:

 Files responsible for a correct build and packaging of the SPSF project

  • [SolutionDirectory]\SPSF.targets

Files used during the deployment of SharePoint solutions

  • [SolutionDirectory]\Deployment\Batches\Deploy.bat
  • [SolutionDirectory]\Deployment\Batches\Retract.bat
  • [SolutionDirectory]\Deployment\Batches\Undeploy.bat
  • [SolutionDirectory]\Deployment\Batches\Update.bat
  • [SolutionDirectory]\Deployment\Scripts\SPSD_Main.ps1
  • [SolutionDirectory]\Deployment\Scripts\SPSD_Base.ps1
  • [SolutionDirectory]\Deployment\Scripts\SPSD_Deployment.ps1
  • [SolutionDirectory]\Deployment\Scripts\SPSD_Utilities.ps1
  • [SolutionDirectory]\Deployment\Scripts\SharePointVersions.xml

Settings files for code analysis tools (if activated in the solution)

  • [SolutionDirectory]\Settings.spruleset (used by SPCAF/SPCop)
  • [SolutionDirectory]\Settings.StyleCop
  • [SolutionDirectory]\Settings.FxCop
  • [SolutionDirectory]\FxCop.targets

Following non-SPSF files will be modified during upgrade:

Files of the solution

  • [SolutionDirectory]\[solution].sln
  • [SolutionDirectory]\[project]\[project].csproj

Note: For projects which have been created with SPSF for Visual Studio 2010, the project “ApplicationDeployment” which contains the MSBuild tasks for the deployment package will be untouched. The new PowerShell deployment project of SPSF for VS2012 based on the SharePoint Solution Deployer PowerShell scripts will be added as new “Deployment” project. The original deployment project will not collect the WSP files anymore, but it will allow you to migrate your deployment settings and custom deployment targets to PowerShell. When you have done that, you can remove the “ApplicationDeployment” project from your solution.
The file named SharePointTargets.targets will be replaced by the new SPSF.targets file in the “ApplicationConfiguration” solution folder.

To update the VS solution perform the following steps:

Make a backup copy of your VS solution.

This is recommended to avoid breaking changes in your solution. If you are using source control you could skip this step as long as you have checked in all changes before you start the upgrade.

Update the Solution

Execute the recipe “SPSF Helpers -> Update solution to current SPSF version” from the context menu in the Solution Explorer.
In case the menus are not available follow the steps described in the post How to (re-)activate SPSF on existing projects? first.

UpgradeSolution

 

Follow the instructions of the wizard.

UpgradeSolutionWizard

 

After completion all changes and replaced files are listed in the output window of Visual Studio

UpgradeSolutionOutput

 

To verify everything went alright, check if the solution now has:

  • A solution folder called “ApplicationConfiguration” which includes all SPSF settings files
  • A solution folder called “Solutions” which will be used for all SharePoint projects
  • A project called “Deployment” which collects all WSPs on build and creates deployment packaged based on the SharePoint Solution Deployer PowerShell scripts

In case SPSF was not used for this solution before the SharePoint projects might still reside outside of the “Solutions” solution folder.

UpgradeSucceededSolutionExplorer

 

To fix this (and to make sure that the projects are configured correctly)

Update the SharePoint projects

If your SharePoint projects

  • are not placed in the “Solutions” solution folder,
  • are not creating a WSP package on build automatically,
  • do not run the SPSF Code Quality Checks on “Release” build or
  • are not built before the “Deployment” project when building the whole solution

you should perform the following steps for each SharePoint project in your solution (if SPSF for VS2012 was used initally to create the project, you could skip this step, though it doesn’t hurt).

Right click on the SharePoint project in the solution explorer to open the context menu and choose “SPSF Helpers -> Update Project to current SPSF version”

UpgradeProject

 

In the recipe dialog click “Finish”

UpdateProjectWizard

 

SPSF will make following changes to the project:

1. Move the project into the “Solutions” solution folder

UpdateProjectSucceeded

 

2. Checkout the csproj file and add following MSBuild lines to it

to let Visual Studio package the WSP on every build and to run the SPSF Code Quality Checks on “Release” build (only in case you have configured them and the necessary tools  like FxCop, StyleCop, SPDisposeChecker and SPCop/SPCAF are installed of course)

3. Add a build dependency to the “Deployment” project so that every time you build it the SharePoint wsp files are created beforehand

ProjectDependency

 

4. Use SPSF

Now you are ready to use SPSF, read about how to use the SPSF in the next post.