How to: Run SPCAF in Team City

SharePoint code analysis can be executed during a TeamCity build. This helps to ensure the correctness of the SharePoint code. During the Build, an overview, and summary of the code quality will be reported to the build log. Additionally, the SPCAF reports can be generated and you can add build steps to easily copy these reports to a specific folder on the build server, to a network share or somewhere else that fits your requirements.

There are various ways to integrate SPCAF in your TeamCity (or other) build server configurations. We will focus on how to do it using PowerShell since most build environments does post-processing using PowerShell. If you re an MSBuild person and feel comfortable using that, there s an article about  How to: Run SPCAF with MSBuild .

What can you expect from this guide?

By following along with the steps in this article you ll learn how to configure TeamCity to use the SPCAF PowerShell version in order to run analysis and collect the reports.

We will look at:

1. Where to find SPCAF PowerShell
2. Collecting the SPCAF PowerShell files in your source control as a Visual Studio Solution
3. Configure TeamCity and add a PowerShell build step to your build configuration
4. Run analysis with parameters that suit your specific project and build environment
5. Automatically fail the build if there are any Critical Errors

This is configurable and only your own team can decide what these rules would be for your specific projects.

Pre-requisites

• You need a TeamCity build server available and configured for packaging SharePoint Projects (More on this can be found here)
• You must already have basic knowledge of how to administer TeamCity and create and manage your build configurations.
• You need Visual Studio and a source control system where your projects are located.
• Basic knowledge of PowerShell is recommended if you want to make changes to the scripts to work with specifics in your own environments.

How To: Configure TeamCity to run the SPCAF PowerShell cmdlet

To run SPCAF through TeamCity, we ll be focusing on the PowerShell cmdlet because it gives us the full flexibility of the output and post-processing and can easily be extended with your own custom requirements.

Note: You do not need to install SPCAF on the build server! The SPCAF PowerShell assembly is pulled on each build from source control to avoid installing them on the build machines. By doing this they can be updated centrally in source control when a new SPCAF version is released and you can assure that all build servers are always using the latest version of SPCAF.

Step 1: Download SPCAF PowerShell

In order to start, we need to download the SPCAF PowerShell cmdets.

1. Download the latest SPCAF PowerShell release from here: http://url.spcaf.com/dl-spcaf-fp-ps
2. Save it and extract the files to a temporary location on your development machine.

We will add these files to a new Visual Studio solution in a later step.

Step 2: Save your license file

In order for the SPCAF PowerShell version to give you full functionality, an SPCAF Quality Gate license is required. When you have a Server license you will also have a License.lic file which contains your license key.

1. Save your license file into the same temporary folder as you saved the SPCAF PowerShell files

Step 3: Download SPCAF.TeamCity.ps1

As a helper script, there is an SPCAF.TeamCity.ps1 file included in the SPCAF PowerShell Cmdlet download which will aid you in executing SPCAF from TeamCity.

1. Get the file from the SPCAF PowerShell cmdlet download.
2. Save it to the same temporary folder as you saved the other files

Step 4: Setup a new SPCAF Visual Studio solution

After we ve downloaded the files we need, we ll create an empty Visual Studio solution and add the files to it and have it checked into our source control system.

Note: This project is not a requirement for running SPCAF PowerShell, but is a requirement for this walkthrough because we want to centrally manage the binaries of SPCAF so we don t have to install it on the build servers. You could just add them directly to your source control as well, but having them in Visual Studio makes it easy to edit the PowerShell scripts and simple replace the binary files.

1. Create an Empty Solution in Visual Studio and add all the files from your temporary location to it (for example all the files from C:\SPCAF-PS\). It should look similar to this:
   
   

   Note: You ll have the License.lic file, the SPCAF.PowerShell.dll file and a file called SPCAF.TeamCity.ps1

2. Check it into your source control system!

Optional Step: Add custom rules to your existing SharePoint solutions

An optional step is to also modify what rules are executed during analysis. A good practice if you have many different projects is to modify exactly what rules will be run for your specific solutions and projects, and keep the ruleset files in your actual SharePoint project. The reasoning behind this is of course that most projects will use different rules and configurations.

Tip:You can add a .spruleset files to the actual SharePoint solution as seen below. This way you can pass the path to this file in from the build configuration in TeamCity and execute these custom rules for this specific project. When you do the same thing with other projects, you can simply just change the parameter in TeamCity to point to a different file if needed.

Note: If you want to make this more automated, you could modify the PowerShell script to automatically look for any .spruleset files and just pass the name of the file through the script. That would require some PowerShell modifications though and is a task you will have to do yourself.

Step 5: Configure TeamCity

When we have reached this point, we already have checked in the required files for running the SPCAF PowerShell version and we ll start configuring TeamCity to utilize these files when building our SharePoint project.

Create a new TeamCity build configuration

In order to demonstrate all the required steps, we will walk through how to setup a new build configuration for your build project in TeamCity and configure it according to our requirements.

Important: It is already a pre-requisite to have knowledge of how to setup a basic Build Project and have it configured to your source control system. The following steps will create a new build configuration in one of your existing build projects. If you do not have a project, please create one first and connect it to your source control system   then continue with the steps below.

All the steps below are performed from the TeamCity web interface.

1. In the General Settings, click Create build configuration
2. Enter a name and description. For example:
   
   
   
3. Click Create
4. (pre-requisite) In the next dialog you need to attach it to your VCS (source control). Since you should already have a project in TeamCity, you should be able to just attach it to the same VCS. If not you will need to create a connection to your VCS first   make sure you have that configured and then continue.
5. Click on Build Steps in the left navigation of your build configuration, here:
   
6. Click Add build step andselect Visual Studio (sln) as the runner type. This enables us to build a Visual Studio solution with our SharePoint code:
   
   
   

   Note: : (1) is the name of your build step, it can be anything. (2) is the path to the .sln file you want to build. You may use the tree-icon to the right to browse to it. (3) is where you select what a version of Visual Studio should be built and (4) is required in order to tell the build engines that it should also package the projects, which will generate the .wsp/.app packages etc.

7. Click Save
8. Click on Triggers in the left menu
9. Click Add new trigger
10. Select Schedule Trigger and make sure you enter the details of when you want the build to run. For example:
    
    
    
11. In order to test and make sure our build can actually generate our .wsp packages from the project, click the Run button at the top right, like so:
    
12. Verify in the build log that your build step works. It should have generated your .wsp package for you. You can either see that in the working directory or in the build log.

Should your build fail at this point, you need to review your build log in order to verify what happened. If everything works as expected, continue to the next step in order to add a build step for the SPCAF PowerShell cmdlet.

Add Build Step: Run SPCAF PowerShell

In order to successfully integrate SPCAF using the PowerShell cmdlet into TeamCity, we ll be adding another build step to run a custom PowerShell script (the script you added to the project in the beginning of this article).

1. Start by going back to Build steps and click Add build step
2. Select PowerShell from the drop down list. This enables us to run a PowerShell file or script block when our solution has been packaged:
   

Note: (1) should be PowerShell. (2) is the platform target and should be x64. (3) is the location of the Script-file you already have checked in from the beginning of this article. (4) tells TeamCity that we want to run a file and not just a script block. (5) are the arguments that will be passed in from TeamCity to the PowerShell Script. See more about the arguments below.

PowerShell arguments

The arguments that we re passing to the script are mandatory and need to be implemented in the same order as described here. Here s a description of the parameters in the sample-script.

Note: This script and the passed parameters can and should be adjusted to your own environment. The PowerShell script can easily be modified and checked into source control in order for new changes to take effect   just remember that if you modify the parameters you ll need to update them in TeamCity as well.

Note: The values passed from TeamCity to the PowerShell script are examples and could (should) be modified and customized according to your own requirements. Since we re using the PowerShell approach, we can extend and modify any type of post-analysis processing exactly to our needs.

Add Build Failure Conditions

In the PowerShell script, there re two statements near the end which output to the pipeline whether or not any occurrences of Error or CriticalError has been found during analysis.

These statements look like this in the script:

Write-Host "SPCAF CRITICAL ERRORS FOUND: $totalCriticalErrors"
Write-Host "SPCAF ERRORS FOUND: $totalErrors"

Since we re writing that to the PowerShell pipeline, TeamCity can pick this up and perform actions on them according to your requirements.

In this example, I m adding a Build Failure Condition if any Critical Errors are reported, hence failing the build entirely.

Select to Edit you Build Configuration Settings and from there click the  Failure Conditions :

Then click the  Add failure condition and specify what your conditions are:

Make sure the first text box reads exactly as above. You can put any text you want in the second box (Failure message), which will then be displayed in the log and build a history of the failed build.

When you ve saved the failure condition, it could look like this if your build fails due to SPCAF Critical Errors:

Review report location

In this example, we have configured C:\Reports as the destination folder on the build server. That is to make it easy during configuration. You could of course, change it to a network path instead, making the reports accessible from your normal computers as well, or to dropbox and have them automatically upload to a shared dropbox folder. The possibilities are endless since we do everything from PowerShell.

In order to make sure, we can actually review the reports after a failed (or successful) build, go to your report location and verify that there s a folder which corresponds to the build time and date:

Inside that folder you will find all the generated reports, ready for review:

Note: If you had enabled more report types, they would have been added here automatically when the analysis is run.

Note: You may want to change the formatting of the folders and report names. This is all done from inside the PowerShell script and can be modified to your own likings.

Note: If you want to include the Build Number in the folder name, you could pass that parameter from TeamCity down to the PowerShell script, and have it included when creating the folder. This would ensure that you review the exact reports from a given build!