How to run analysis during TeamBuild

SharePoint code analysis can also be executed during a TFS Team Build. This helps to ensure the correctness of the SharePoint code. During the Team Build all found errors and warnings are listed in the build result. Additionally the SPCAF reports can be generated and saved to the output directory.

SPCAF supports the Team Build with the following products:

  • TFS 2010
  • TFS 2012
  • TFS 2013
  • Team Foundation services (TFS Online)

To support TFS 2010 and TFS 2012 SPCAF comes with 2 different build activities which can be integrated into the workflow of a Team Build, depending on the version of TFS. The build activities can be found within the installation directory of SPFAC in subfolder "TeamBuildActivities".

  • SPCAF.BuildActivity.TFS2010.dll
  • SPCAF.BuildActivity.TFS2012.dll

Note: The build activities should not be copied directly into the installation folder of SPCAF because SPCAF searches during analysis within the installation folder for custom rules. As the activities depend on Team Build assemblies they cannot be loaded and SPCAF cannot execute.

Note: If you are not familiar with configuration of team builds in TFS please request somebody to help you. If you like you can reach out to one of our consulting partners who can also help you to analyse the results or implement custom rules.

The following steps provide the general instructions for the Team Build. Some standard TFS configuration steps are skipped.

Preparation

To run SPCAF on the build server the SPCAF assemblies must be available on the build server. You don't need to install SPCAF on the server!

  • 1. Open Source Control of TFS and navigate to folder "BuildProcessTemplates" of your team project
  • 2. Create a subfolder "CustomAssemblies" and check in
  • 3. Within this folder create a subfolder "SPCAF"
  • 4. Copy only the following assemblies from SPCAF installation directory to that folder:
    • ICSharpCode.Decompiler.dll
    • ICSharpCode.NRefactory.CSharp.dll
    • ICSharpCode.NRefactory.dll
    • Jurassic.dll
    • log4net.dll
    • Microsoft.Deployment.Compression.Cab.dll
    • Microsoft.Deployment.Compression.dll
    • Mono.Cecil.dll
    • Mono.Cecil.Pdb.dll
    • Mono.Cecil.Rocks.dll
    • Spark.dll
    • SPCAF.Dependencies.dll
    • SPCAF.Engine.dll
    • SPCAF.Inventory.dll
    • SPCAF.Metrics.dll
    • SPCAF.Rules.dll
    • SPCAF.Integration.CSSLint.dll
    • SPCAF.Integration.CSSLintRunner.exe
    • SPCAF.Integration.JSHint.dll
    • SPCAF.Integration.JSHintRunner.exe
    • SPCAF.Sdk.dll
    • SPCAF.Sdk.XmlSerializers.dll
    • log4net.config
    Do not deploy the assemblies
    • Autofac.Portable.dll
    • De.TorstenMandelkow.MetroChart.dll
    • SPCAF.Client.Core.PortableInfrastructure
    • SPCAF.VSPackage
    • SPCAF.VSPackage.Common
  • 5. Also include the License.lic file with your license (can be found in users AppData directory)
  • 6. Copy the assembly from folder "TeamBuildActivites" in the SPCAF installation directory to that folder in TFS
  • 7. Copy the folder "RuleSets" to the folder in TFS

You should end up as shown in the following screenshot:

Configure Build Controller to load the SPCAF Assemblies

Now we need to tell the Build Controller that during a build the SPCAF assemblies should be loaded.

Add SPCAF Build Activity to the Process Template

You have 2 options: You can manually add the Build Activity in the xml file or you can use the designer in Visual Studio.

Manually add build activity

Copy an existing process template, open it in an editor and add the following fragments to the xml to include the SPCAF assembly with the build activity to the template.

<Activity
  mc:Ignorable="sad"
  x:Class="TfsBuild.Process"
  xmlns:this="clr-namespace:TfsBuild;"
  ...
  xmlns:sb="clr-namespace:SPCAF.BuildActivity;assembly=SPCAF.BuildActivity.TFS2010"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
  <x:Members>
  ...

To integrate the SPCAF activity into the build process we recommend to add the activity after the finished build and finished tests.
Search for activity with DisplayName "If TestStatus = Unknown" and place the SPCAF activity "RunSharePointCodeAnalysis" after this activity.

...
<If ... DisplayName="If TestStatus = Unknown" mtbwt:BuildTrackingParticipant.Importance="Low">
  ...
</If>
<sb:RunSharePointCodeAnalysis
  DisplayName="Run SharePoint Code Analysis SPCAF"
  SettingsFile="{x:Null}"
  TempFolder="{x:Null}"
  FailBuildOnError="False"
  IgnoreExceptions="False"
  InputDirectory="[BinariesDirectory]"
  LogExceptionStack="True"
  OutputFilename="[System.IO.Path.Combine(BinariesDirectory, &quot;SPCAFResults\\SPCAFResults.xml&quot;)]"
  ReportGeneratorTypes="HTML;XML;DGML;DOCX"
  LogFile="[System.IO.Path.Combine(BinariesDirectory, &quot;SPCAFResults\\spcaf.log&quot;)]"
  TreatWarningsAsErrors="False" />
<If ... DisplayName="If TreatTestFailureAsBuildFailure And (TestStatus = Failed)" ...

NOTE: Because in TFS 2013 the default build process template is a little bit different we need to add a variable to store the path to the Binaries Directory. Open the tab "Variables", add a variable named "BinariesDirectory" with the type "String", you can leave the scope in its default setting (for more information visit Joost Haneveer: How to run SPCAF analysis during TeamBuild in TFS 2013).

Add Build Activity with Designer in Visual Studio

If you don't want to add the build activity to the process template in XML you can use a visual designer in Visual Studio.

  • 1. Make a copy of an existing Process Template e.g. DefaultTemplate.xaml in TFS an name it for instance DefaultTemplateSPCAF.xaml
  • 2. Create a new project of type Class library in Visual Studio and delete the default created Class.cs
  • 3. Add the copied Process template 'DefaultTemplateSPCAF.xaml' to the project via "Add Existing Item" and navigate to the folder with DefaultTemplateSPCAF.xaml. Important: Select "Add As Link" in the dialog to add only a link to the file.
  • 4. Add the necessary reference to the project:
    1. Microsoft.TeamFoundation.Build.Workflow.dll
    2. Microsoft.TeamFoundation.VersionControl.Client.dll
    3. Microsoft.TeamFoundation.VersionControl.Common.dll
  • 5. Add reference to SPCAF.BuildActivity.TFS2010 (or ".TFS2012) to the project from the previously created folder "CustomAssemblies"

See below the Visual Studio project with all references, the linked DefaultTemplateSPCAF.xaml

  • 6. Open the process template in designer.
  • 7. Add the SPCAF build activity to the toolbox: Right click in toolbox and select "Choose items...". In tab System.Activites Components select "Browse..." and select the assembly SPCAF.BuildActivity.TFS2010 (or ".TFS2012) from the folder "CustomAssemblies". The Build Activity appear in the toolbox.
  • 8. In the process template navigate to Activity "Try Compile, Test and Associate..." and open the try block. Drag the SPCAF build activity add the end of the Sequence.

You should end up with the following setup:

  • 9. Configure the build activity to your needs (see parameters below).
  • 10. Save the process template and check in.

Parameters of Build Activity

The following parameters can be configured for the build activity.

ArgumentDescriptionSample Value
DisplayNameRequired String. Title of activity, used in logfiles."Run SharePoint Code Analysis SPCAF"
SettingsFileOptional String. Name of settings file in folder "/RuleSets" or full path to a different ruleset file.
TempFolderOptional String. Path to temp folder. If not set SPCAF uses a standard temp folder.
FailBuildOnErrorOptional Boolean. Default FALSE. If TRUE the build fails if SPCAF detects errors.FALSE
IgnoreExceptionsOptional Boolean. Default TRUE. TRUE to ignore exceptions during analysis. Settings this value helps to ensure that the build finishes successfully also in case of exceptions.TRUE
InputDirectoryRequired String. Path to WSP solutions. Can be a folder name or a list of files (separated by ';').BinariesDirectory
LogExceptionStackOptional Boolean. Default FALSE. In case of problems with SPCAF setting this value to TRUE adds more information to the logfile which describes the error in detail.FALSE
OutputFilenameOptional String. Defines the ouptput filename of the reports. Typically the output folder should be in the BinariesDirectory. After successful build the whole BinariesDirectory is copied to the DropLocation. Alternatively the DropLocation or any other folder can be used to save the results.System.IO.Path.Combine(BinariesDirectory, "SPCAFResults\\SPCAFResults.xml")
LogFileOptional String. Defines the path to the log file.System.IO.Path.Combine(BinariesDirectory, "SPCAFResults\\spcaf.log")
ReportGeneratorTypesOptional String. Defines which reports should be createdHTML;XML;DGML;DOCX
TreatWarningsAsErrorsOptional Boolean. Default FALSE. If TRUE all warnings will be evaluated as errors.FALSE
ThrowExceptionOnErrorOptional Boolean. Default FALSE. If TRUE an exception will be throw in case of critical errors or errors.FALSE
VerbosityOptional String. Detail level of output (e.g. minimal, default: normal).normal

The build activity returns the following values after analysis.

ArgumentDescription
CriticalErrorsInteger. Contains the number of critical errors after analysis.
ErrorsInteger. Contains the number of errors after analysis.
CriticalWarningsInteger. Contains the number of critical warnings after analysis.
WarningsInteger. Contains the number of warnings after analysis.
InformationInteger. Contains the number of information after analysis.

Create a new Build Definition

Now we can use the new process template in a new Build Definiiton

  • 1. Create a new Build Definition in TFS
  • 2. In the build definition goto tab "Process" and select "New.." and "Select an existing XAML file" and choose the DefaultTemplateSPCAF.xaml
  • 3. For building SharePoint projects a special setting is needed: Go in process tab to "3. Advanced" and change the parameter "MSBuild Arguments" to "/p:IsPackaging=true". This ensure that during the build process the WSP files are created.
  • 4. Run a build with the new Build Definition. To check if SPCAF was configured correctly check the log. There you can find the output of the analysis.
  • 5. In case of found errors and warnings during analysis the result can be found in the Build Summary.
  • 6. Navigate to the DropLocation. There you should find the create SPCAF reports.
comments powered by Disqus