CI

Running Unit Tests as part of Continuous Integration of VSTS / VSO

Tue, 05 Jul 2016 09:00:00 GMT

In my previous blog I explained how to setup from scratch and deploy to Azure using VSTS. As I mentioned in the blog I left the configuration of Unit Testing for another time.

In this article I will explain how you set up and run your Unit Tests as part of CI/CD process using VSTS.

There are a few ways to setup Unit Tests depending on what you want to achieve. We can run the Unit Tests from a PowerShell script or we can use the Visual Studio Test build step which VSTS team created for us. Let’s start with PowerShell first.

We’ll use the same project as in the previous post – OfficeInventory. The Unit Test project is a standard .NET library using xUnit library. The process will be similar if you use a different Unit Test library, like NUnit.

Configuring PowerShell

When using xUnit you should make sure that the console runner is added as package so it will be restored during the build. We will use the console application to run the Unit Tests.

At the root folder of the project – the same level with .sln I added the Scripts folder. The folder will contain run-unittests.ps1 PowerShell script.

We provide two input parameters to the script, the xunit console application path and the path we want to search for the tests projects.

param (
    [Parameter(Mandatory=$true)][String] $xunitConsole,
    [Parameter(Mandatory=$true)][String] $sourceDirectory
)

Next we’ll search for all the Unit Tests files we want to test excluding Java Script projects.

$assembliesToTest = (Get-ChildItem "$sourceDirectory" -Recurse -Include "*Test*.dll" -Exclude "*JavaScript*" -Name | Select-String "bin")

Now that we have all the Unit Test files we want to run let’s execute them.

foreach ($testFile in $assembliesToTest) {

  $fileNameOnly = Split-Path $testFile -Leaf
  $unitTestFileName = Join-Path $sourceDirectory ($fileNameOnly + "-XunitTestResult.xml")

  $fullNameTestFile = Join-Path $sourceDirectory $testFile

  & $xunitConsole $fullNameTestFile -xml $unitTestFileName
}

In the $unitTestFileName we store the result of our Unit Test execution. We’ll use this in the Publish Test Result build step.

Here’s the full PowerShell script

param (
    [Parameter(Mandatory=$true)][String] $xunitConsole,
    [Parameter(Mandatory=$true)][String] $sourceDirectory
)

if (!(Test-Path $xunitConsole))
{
    throw "xunit.console.exe does not exist. Please check $xunitConsole file."
}

$assembliesToTest = (Get-ChildItem "$sourceDirectory" -Recurse -Include "*Test*.dll" -Exclude "*JavaScript*" -Name | Select-String "bin")

$atLeastOneTestRun = $false

Write-Host "[Debug] ************* Running Unit Tests *************"

foreach ($testFile in $assembliesToTest) {
    Write-Host "[Debug] *************** Testing $testFile ***************"

  $fileNameOnly = Split-Path $testFile -Leaf
  $unitTestFileName = Join-Path $sourceDirectory ($fileNameOnly + "-XunitTestResult.xml")

  $fullNameTestFile = Join-Path $sourceDirectory $testFile

  & $xunitConsole $fullNameTestFile -xml $unitTestFileName
  $atLeastOneTestRun = $true
}

if ($atLeastOneTestRun -eq $false) {
    Write-Output "Unit Tests didn't run!"
	exit(1)
}

The script is ready, lets add the build steps. Edit the configuration build and in the Add tasks select PowerShell Scripts.

And after that add Publish Test Results.

Close the dialog and make sure both tasks are added after the Build task and before the Publish Artifact task.

Select the PowerShell tasks and configure the following

- Type: File Path

- Script filename: scripts/run-unittests.ps1

- Arguments: -xunitConsole "$(Build.Repository.LocalPath)\packages\xunit.runner.console.2.1.0\tools\xunit.console.exe" -sourceDirectory "$(Build.Repository.LocalPath)"

Select the Publish Test Results and configure these parameters

- Test Result Format: XUnit

- Test Results Files: **/*-XunitTestResult.xml

Now it’s time to run the build. You can see the Tests Results in the Summary page.

Configuring the Visual Studio Test step

For this configuration we will use a Visual Studio Test task. First of all, make sure that the Unit Test project has xunit.runner.visualstudio package if you are using the xUnit framework.

Add a new build step as in the below image. That will be a Visual Studio Test step

You don’t have to do anything in this step, the default parameters will work ok, unless you need more features, like code coverage, running JavaScript, etc.

The default configuration will include all the projects containing the name tests and exclude the obj folder.

Conclusion

In this post I explained two ways you can run your Unit Tests during the build process using VSTS / VSO.

First way is to execute a PowerShell script which will find all the tests you want to run and using a Publish Tests Results to publish the tests. If you’re using xUnit you need to make sure you have xunit.runner.console included as a NuGet package.

The second option is easier but is not as flexible. In this case you need to have xunit.runner.visualstudio NuGet package.

A logging library for operations or a C# feature which Java developer will appreciate

Wed, 16 Mar 2016 10:25:33 GMT

This blog is not about how Java is better than C# or vice versa. It's about using existing features a language offers you - every language has its own strength.

I went to London Continuous Delivery meetup a few weeks ago where Sean Reilly presented a logging library with operations in mind - opslogger. The library is created in Java and one of the questions was when it will be ported in .NET. In .NET we don't have to create a library for this purpose, we can extend existing libraries applying what C# language offers. If you’re a .NET developer then extension methods shouldn’t be new to you but if you’re an ops guy show this article to your devs.

The main idea of the library is that it does logging for operations. I really liked it and agree with the fact that people who look after our apps are left behind in terms of what to log. Although I think the logging is for both operations and developers. The first look after the performance and the behaviour and the latter came to the scene for troubleshooting.
The library is very opinionated, for example, you can't use different levels - there is just one level. You either log or you don't. There's no log rotation, and I agree with what Sean is saying that devops know how to configure it so you don't need a tool to do that. But, how about the applications you deploy on clients machines? In .NET world that will be Windows Forms and WPF applications. You need log rotation and you need different levels - you don't want to log everything every time on a client machine. Also, I like having different methods for logging: debug with some message and object to be serialized as parameters and a different method to log exception with Exception instance. For example:

Log.Debug("Request info", request);
Log.Error("Exception when executing payment", ex);

The idea I liked in the framework is that you don't log random messages but you have a set of predefined identifications plus your log message. For example, every time the application starts you log:

APP-001 Application started.

The code in the opslogger library looks like this:

logger.log(START_APP, "Application started.");

and START_APP is an enum with value "APP-0001"

If you're a .NET developer you know we can easily implement the same approach using existing logging libraries and extension methods. We have nice logging libraries with a vast amount of features. Why should we create one just for logging specific messages? What opslogger library does is that it uses a set identification messages.

I used to use log4net in the past, but I switched to NLog. If you're still using log4net I definitely recommend to have a look at NLog. In this example I will use NLog.

I have created a sample ASP.NET MVC application to prove the idea. You can find it on github.

We're going to extend NLog with a set of predefined methods with specific messages. For example:

 public static class LoggerExtension
    {
        public static void ActionInit(this ILogger logger, string message)
        {
            logger.Debug($"APP-001 {message}");
        }
        public static void Performance(this ILogger logger, string message)
        {
            logger.Debug($"PERFORMANCE-001 {message}");
        }
    }

And we'll use it like that:

Logger.ActionInit("HomeController Index");

Have a look at log output below. You can see that it's easy to search for particular messages. Let's say you want to filter all the performance logs, in this case you use PERFORMANCE-001 tag and depending what system you use to store logging you can have a nice filter/view of the data.

2016-03-10 14:04:26.1665|DEBUG|NLogExtension.Controllers.HomeController|APP-001 HomeController Index

2016-03-10 14:04:26.1860|DEBUG|NLogExtension.Controllers.HomeController|Get all users

2016-03-10 14:04:26.8906|DEBUG|NLogExtension.Controllers.HomeController|PERFORMANCE-001 Getting users in: 700

2016-03-10 14:04:26.8946|DEBUG|NLogExtension.Controllers.HomeController|Searching for active items

2016-03-10 14:04:27.1998|DEBUG|NLogExtension.Controllers.HomeController|PERFORMANCE-001 Searching active items in: 301

2016-03-10 14:04:27.2478|DEBUG|NLogExtension.Controllers.HomeController|Sample debug message

2016-03-10 14:10:06.0037|DEBUG|NLogExtension.Controllers.HomeController|APP-001 HomeController Index

2016-03-10 14:10:06.0322|DEBUG|NLogExtension.Controllers.HomeController|Get all users

2016-03-10 14:10:06.7354|DEBUG|NLogExtension.Controllers.HomeController|PERFORMANCE-001 Getting users in: 700

2016-03-10 14:10:06.7464|DEBUG|NLogExtension.Controllers.HomeController|Searching for active items

2016-03-10 14:10:07.0559|DEBUG|NLogExtension.Controllers.HomeController|PERFORMANCE-001 Searching active items in: 300

2016-03-10 14:10:07.0559|DEBUG|NLogExtension.Controllers.HomeController|Sample debug message

2016-03-10 14:10:07.5652|DEBUG|NLogExtension.Controllers.HomeController|APP-001 HomeController About

2016-03-10 14:10:08.8938|DEBUG|NLogExtension.Controllers.HomeController|APP-001 HomeController Contact

As you can see we can achieve the same output as opslogger with any logger library we want in a very flexible way.

Continuous Integration and Deployment of Azure Web App using VSTS / VSO

Thu, 25 Feb 2016 14:02:31 GMT

A new addition to the Microsoft’s Visual Studio Team Services (former VSO) continuous integration and deployment is the Release tool. The CI/CD process I’m describing here applies to VSTS but at some point it will be released to TFS as well. Microsoft invested its effort into building a nice continuous integration and deployment pipeline. The new online VSTS build and release tools are much better than the old XAML builds. I have been working with TeamCity for a very good number of years and I was surprised with Microsoft’s new addition. I started working with Build and Release tools very earlier for one of our clients - since private previews. It was called Visual Studio Online at that time. My experience is that they are moving very fast. I ported a few of our TeamCity builds and deployment configurations over to VSTS and it was easier than I expected. Taking into the account that I almost had zero documentation I progressed very quickly.

In this article I will explain how you can build and deploy a Web site into Azure Web App. VSTS contains a template for Azure Web Sites which makes our life easier. It contains Cloud Services and IIS Web Applications also. And if there’s anything you need which is missing you can always use PowerShell.

The solution we’re going to deploy represents an ASP.NET MVC Application but a WebForms application will have the same approach. For the sake of simplicity I created an ASP.NET MVC Application and named it OfficeInventory.

Create a build configuration

Open Build tab in VSTS and click the plus button:

Select an Empty template in the popup windows and click Next. There is a Visual Studio Template but it will add build steps which we don’t need, like Visual Studio Test and Index Sources.

In the next step select the source settings. Default agent in this case will be Hosted, unless you’ve installed your own agent. With the hosted agent you have 240 free minutes per month. Check Continuous Integration check box and click Create.

First we’ll configure the build and after that we’ll add build steps.

Repository configuration

We’ll come back and update the build and publish build steps but for the moment open the Repository tab. You should have already source settings in place. The settings I’m explaining below refer to a Git repository. If you want the build process to download all the source code every time it builds select true for the Clean dropdown. Depending how big your project is this may slow down the build process. If you want to tag your source code then select the appropriate value in the Label sources. Adding tags to you build will make sense when you create NuGet packages but it will provide less information for normal builds. By default Label format contains the build number. I will explain later how to set it.

Variables configuration

The Variables tab contains our variables definition we can use during the build process. We can use them in the following format:

$(VariableName)

Let’s add the following variables:

BuildConfiguration	Release
BuildPlatform	Any CPU

Triggers configuration

In the Triggers tab we can configure when to run the build. You can set it up to run as Continuous integration and include filters based on branch names. When you check Batch changes option it will include several check-ins if they are from the same committer. You can run the build on a schedule as well. Adding the schedule will help when you want to run builds which takes more time, like testing.

General

In the General tab you can change the Agent Queue, build authorisation, badge displayed on external web site etc. We’re interested in setting the Build Number.

I like setting the build number following the classic approach: major.minor.build.revision. In this case, if I want the build number to be 1.0.3.[RevisionNo] then I use the format 1.0.3.$(Rev:r). If you prefer to use a different system to name your builds, like using date, then find more information online at this MSDN link.

Retention

The Retention tab allows to specify for how many days you can keep the build details, including test results. The default value is 30 days and at the moment you can’t change that.

Build steps

We have created an empty build, now lets add the configuration we need. Click Add build step… in the list of Tasks select Build on the left hand side and search for Visual Studio Build. Click the Add button. Next select Utility on the left hand side and click the Add button of the Publish Build Artifacts. Now you can close the popup.

Build solution

Let’s go back to the Build tab and select Visual Studio Build. We need to provide settings on the right hand side. First of all, you may want to add a meaningful name to this step, so click on the pencil in the right hand side, above all the settings and enter the name you want.

The Solution text box contains **\*.sln – you can leave it like that or click on the ellipsis button and select the solution file from the tree.

MSBuild Arguments – we need to create a package which we’ll deploy later in Azure Web App. In order to do this we’ll use the command line

/p:DeployOnBuild=true /p:WebPublishMethod=Package /p:PackageAsSingleFile=true /p:SkipInvalidConfigurations=true /p:PackageLocation=$(Build.StagingDirectory)\OfficeInventory

Pay attention to the PackageLocation parameter. This is where our package will be copied. We’ll use this path in the next step to publish the package. We use Build.Staging variable which is a predefined build variable. The package will be copied to staging directory of our build and in the OfficeInventory folder. The staging folder is generated by the build agent. Find more information about build and release variables at Use variables.

For the Platform and Configuration provide the variables we’ve created before: $(BuildPlatform) and $(BuildConfiguration).

Check the Clean checkbox if you want to start the build with all the files removed from previous builds.

Publish package

The next step is to publish the package so we can use it during the Release process. Select the Publish Build Artifacts step. In the Path to Publish enter $(Build.StagingDirectory)\OfficeInventory. For the Artifact Name provide a name you want. In my case it’s OfficeInventory. In the Artifact Type select Server unless you want to copy the package to a shared folder.

Now it’s time to save if you haven’t yet and run the build.

Release

Open the Release tab. As I’m writing this blog the Release is in public preview.

Click on the Plus button and select Azure Website Deployment. It will add a new environment with Azure Deployment and Visual Studio Test tasks for that environment.

Delete the Visual Studio Test because we’re not going to configure it – I will post another article about configuring Unit Testing.

You can rename the environment if you want to. Usually you’ll create a few environments, like Dev, Testing, Staging, etc.

Click on the Artifacts tab then click on the Link an artifact source. Select the build you want to link to. There is nothing to add on the Configuration tab so click on the Triggers tab. Check the Continuous deployment and select the artifact and the environment. In the General tab I will change the default name format to Office Inventory - 1.0.0.$(rev:r)

In order to deploy to Azure you need to configure the Azure subscription first. Click on the Manage link on Azure Subscription of the Azure Web App Deployment task. This will open a new page. On that page click on the New Service Endpoint and Select Azure from the list. This will open a modal windows where you need to enter Azure details. The easiest way to get that information is hovering you mouse on the exclamation icon and click on the publish settings file link. That will download the Azure publish settings file. That file is an XML file so open it in your favourite editor. I prefer to use Certificate Based instead the Credentials type because I don’t want people to enter their credentials. In any case, extract the information you need from the publish settings file, like Subscription Id, Name, etc. and click OK.

Let’s go back to the Environments page and click on the Refresh button on the right hand side of the Azure Subscription. Enter the name of your Azure Web App, select the location and the slot (Production or Staging). Click on the Ellipses button select the package.

Now we’re ready to deploy. Save the release and click on the Release button and next Create Release.

NOTE: You can rename the Tasks if you click the pencil on the right hand side of the task Title.

Now you can add multiple environments and continuously deploy to them.

Visual Studio Online - output colouring by tag

Wed, 23 Sep 2015 06:09:32 GMT

I started being more involved in continuous integration and deployment using Visual Studio Online which is ‘the new‘ TFS hosted in Azure.

I've discovered an interesting and useful feature when using it PowerShell. When you use Write-Host if you add [Debug], [Warning] and [Error] in your output string then you get a nice colour in the Console and Logs pages of the build result.

Have a look at the below images.

In this example the following output was used:

Write-Host "[Debug] Debug value"
Write-Host "[Warning] Warning value"
Write-Host "[Error] Error value"

As you can see the Console doesn't shows the value in square brackets.

This worked for me in both Azure hosted and local hosted agent. I guess it should be the same on the TFS hosted on premises.

Azure Mobile Service deployment with Team City part 7. Deployment to Test environment

Fri, 04 Sep 2015 06:05:21 GMT

The last step in these series of posts is deploying from TeamCity to a test environment.

We have already created the script which will do the deployment so we need only to create the TeamCity configuration.

Although we can call the script which will do the deployment directly from TeamCity I prefer to have another separate script which at its turn will call the deployment script. In this way we test it locally and if we need to add more functionality we don't have to change the TeamCity configuration. For this purpose we create run-delpoy.ps1 script which will have the same set of parameters as deploy-package.ps1. The script takes input parameters and calls the deploy-package.ps1 script.

Make sure you have created a test Azure Mobile Service instance.

Now let’s configure TeamCity. On the User Management settings page (Administration > User Management) and click Create build configuration.

I will name it Mobile Service Test Deploy and click Create button.

In the next step – Version Control Settings select User Management and click Attach.

Click on the Build Steps if it didn’t open automatically and click Add build step. Select Powershell from the Runner type drop-down. Give a name to the step and select Powershell mode and error output. Working directory will be MobileService/Scripts and Script file will be MobileService/Scripts/run-deploy.ps1. The last part is adding the Script arguments.

packageLocation parameter indicates where the package is located – it is defined by this value:

"%teamcity.build.checkoutDir%\Package"

This represent the Package folder in the checkout directory. The content of the Package folder will be generated by the Artfact dependency as you’ll see later.

The rest of the parameters value we extract from the Mobile Service publish profile as described in this post.

We need to link this build configuration to Mobile Service Team City build configuration we created in previous steps. Open the Dependencies and click on the Add new artifact dependency button. In the Depend on select the Mobile Service, select Last successful build from Get artifacts from and in Artifacts rules enter:

Package=>./Package

We’re almost done, one last step – we need to know which package was deployed to Test environment. Open the General Settings and in the Build number format enter:

Mobile Service-%dep.UserManagement_MobileService.build.number%

This will tell us which Mobiles service package version was deployed to Test environment.

Now we’re ready to run our deployment. On the Project page click on the ellipses Run button of the Deploy project and then click on the Dependencies tab. Select which build you want to deploy and click Run Build

The build run and the package was deployed successfully. As you can see the Test Deploy build indicates which Build package it used to deploy: #Mobile Service-0.0.2.37

Conclusion

With this blog post I’ve finished all the posts about building and deploying an Azure Mobile Service. I’ve started from installing and configuring TeamCity, creating PowerShell scripts to build and deploy up to configuring TeamCity to deploy on Test environment. Although it is concentrated on the Azure Mobile Service you might find some bits of it useful in other type of projects.

I hope you’ll find it useful.

Azure Mobile Service deployment with Team City part 6. Integrate SpecFlow with TeamCity

Fri, 28 Aug 2015 05:02:32 GMT

In the previous blog post I explained how to configure TeamCity to run a PowerShell script which will deploy an Azure Mobile Service.

After the Mobile Service was deployed we want to run acceptance tests. I’ve created a sample C# project using SpecFlow. It doesn’t have to be Acceptance Tests, I just wanted to give an example of how you’ll integrate SpecFlow with TeamCity. The solution contains the “Specifications” project which are a set of SpecFlow scenarios. SpecFlow has the ability to generate reports – we’ll be generating one report and integrate it with TeamCity.

We’ll create a new file – acceptance-tests.ps1 in the Scripts folder.

In order to generate a report we need to run a command which executes the NUnit tests as described in the documentation https://github.com/techtalk/SpecFlow/wiki/Reporting. For this purpose we need NUnit console app. I’ve added nuget package manually. Otherwise, it will install the package as a solution package.

<package id="NUnit.Runners" version="2.6.4" />

First step is to execute the acceptance tests with the nunit-console runner.

& $nunitRunner /nologo /labels /out=TestResult.txt /xml=TestResult.xml /framework:net-4.0 $acceptanceTests

It will generate two files: TestResult.txt and TestResult.xml. These files will be used when invoking SpecFlow report generation. TestResult name is the default name so if you don’t change it then in the next step you don’t have to provide additional parameters. You just need to provide the SpecFlow project file.

& $specFlow nunitexecutionreport "..\Source\Specifications\Specifications.csproj" /out:"..\TestResult.html"

This will generate TestResult.html report file in the root folder.

Another moment here I need to highlight – the specflow.exe is compiled for .NET 3.5 so it cannot load .NET 4.0 assemblies. You can find more details at Step Definition Report

For this reason we copy specflow.exe.config file to the packages folder.

Copy-Item -path "specflow.exe.config" -destination $specFlowFolder

Configure SpecFlow reporting in TeamCity

We can update our build so that after deployment it runs the SpecFlow Acceptance Tests and gives us the detailed report about the execution.

In the TeamCity configuration page open the Build Steps page. Add a new build step. As you might guess this will be another PowerShell configuration. The configuration is similar to the one we did before.

Working directory is MobileService/Scripts and Script file is MobileService/Scripts/acceptance-tests.ps1 with no parameters.

Next we need to configure TeamCity to display our SpecFlow report. First we add Build Feature – XML Report processing. The purpose of this is that TeamCity will take our TestsResult.xml file will parse it and report the results as the build results. In this way we can add out Acceptance Tests to be part of the CI process and they will be displayed in Test Results tab as well.

In the Build Configuration Settings page click on the Build Features and Add build feature. Select XML report processing from the drop down and select NUnit from the Report type. Add Scripts\TestResult.xml in the Monitoring rules.

Next step we’ll configure TeamCity result page to display the SpecFlow result page TestResult.html in a new tab.

Open the Administration page and click on the User Management project.

Click on the Report Tabs link.

Click on the Create new build report tab. In the new dialog enter the Tab title – that will be the title of the tab which appears in the build result page and Start page which in our case will be TestResult.html.

The Start page represents an artifact page which means that the TestResult.html page should be an artifact entity created by TeamCity. In order to do this go to the Build Configuration Settings and open the General Settings page. We have added already our package which gets deployed as an artifact. Now we need to add in the Artifact paths:

MobileService\TestResult.html=>.

Now when we run the build we have a nice SpecFlow report.

This finishes the full continuous integration and deployment of an Azure Mobile Service in TeamCitiy.

But there one last step which is outside of this deployment pipeline – in the next post we’ll configure TeamCity to deploy a package to Test environment which was deployed and tested on Dev environment.

< Previous

Azure Mobile Service deployment with Team City part 5. Configuring Mobile in TeamCity

Thu, 06 Aug 2015 09:08:03 GMT

In the previous post we finished to create all the PowerShell scripts. The build and deployment run locally. Now it’s time to create a TeamCity configuration for it.

Open the TeamCity web page and click on the arrow on the right hand side of User Management Project page and then Edit Settings from the menu.

Click on the Create build configuration.

Give it a name – I use Mobile Service and click Create.

It opens the Version Control Settings page where I will attach the VCS root previously created.

Next step is to create the build configuration. Click on the Build Steps and Add build step.

Select PowerShell Runner Type, specify the step name and select the PowerShell mode.

Click the Show advanced options link at the bottom of the page if you don’t see all the settings.

Select error value in Error Output drop down.

Enter MobileService/Scripts in Working directory

Enter the script file MobileService/Scripts/run-build.ps1

Make sure Execute .ps1 from external file is selected in Script execution mode.

Click Expand on the Script arguments and enter:

-version %build.number%

-contentPath "contentPath"

-computerName "computerName"

-userName "userName"

-password "password"

Replace all the necessary values as described in Azure Mobile Service deployment with Team City part 4. Deploying Azure Mobile Services.

Click Save.

We need to configure a few more settings.

Click on the General Settings and enter the Build number format. I use Major.Minor.Build.Revision pattern: 0.0.2.%build.counter%.

In the Artifact paths enter

MobileService\Artifacts=>Package

In our script at the build step we copy the package which we need to deploy in the Artifacts folder. Now we tell TeamCity to use that folder to create a build Artifact. You’ll see later how we use it do deploy to other environments.

Open the Failure Conditions from the left hand site and select “an error message is logged by build runner”. In some cases when the PowerShell returns an error, like failed to deploy the mobile service TeamCity will mark the build as green – success. When you select this option it will fail the build.

Now when you run this build it will execute all the PowerShell steps and will deploy the Azure Mobile Service.

In the next post we’ll configure SpecFlow to integrate with TeamCity.

< Previous

Azure Mobile Service deployment with Team City part 3. Build Azure Mobile Service with PowerShell using psake

Thu, 16 Jul 2015 05:02:40 GMT

TeamCity is a very powerful tool and you can take advantage of all its configuration options to create your CI and CD. Although TeamCity provides you with almost everything you need, like restoring packages, update version, build, running unit tests, etc. I’m going to write all these steps in a PowerShell script. It is easier to use what TeamCity offers from the start but when the complexity of building and deploying increases it will be difficult to maintain.

Having the deployment process as a set of scripts will give you some advantages, like:

Run and test the deployment process on your machine
Evolve the deployment system incrementally
Ability to test every step in isolation
Checking changes in source control and ability to revert to previous versions if needed

The scripts will be written in PowerShell and I will use psake which is a PowerShell tool to provide task-oriented dependencies.

Initially we’ll start with three scripts:

local.ps1 – we’ll use this script to run the entire set of script on local machine; it contains default parameters and it executes run-build.ps1
run-build.ps1 – the script is called by TeamCity providing all the necessary parameters. It invokes the build.ps1 script using psake module
builid.ps1 – contains all the steps necessary to build the project

Tools

First we need to get psake scripts from the git releases page and copy them to the Tools folder. We need the nuget.exe as well. Download it from Command-Line Utility URL . Copy nuget.exe in the Tools folder.

Local script

All the scripts are located in the Scripts folder.

local.ps1 script clears the screen and executes the run-build.ps1 script. It contains a few default parameters. One of the parameter is debugConfiguration. We use that for debugging purposes. For example when we work on the deployment task we might not want to run all the tasks which are time consuming, like restore packages so we’ll ignore it.

Run-build script

The run-build.ps1 script imports psake module and executes build.ps1 script in the context of the psake module. It invokes the script with parameters which don’t have default values and properties which have default values.

Build script

All the steps before running the build and the build itself are done in this build.ps1 script.

We’ll start with changing how psake prints out the tasks it runs. This will make a better separation between tasks and will be easier to read.

FormatTaskName "$([Environment]::NewLine)==================== $(Get-Date -format T) - Executing {0} ===================="

We’ll use the precondition parameter to conditionally run a task. For example, if we don’t want to restore packages we’ll use the $debugConfiguration.restorePackage parameter.

Task RestoreNuGetPackages -Depends Clean -Precondition {return $debugConfiguration -eq $null -or $debugConfiguration.restorePackage } {

The task will run when precondition returns true. I check for null value of the debugConfiguration variable because it will be null when running from TeamCity so we don’t want to skip the step.

Bear in mind that if the task execution depends on another task then that task will not run if precondition of the task in execution returns false.

We’ll start with adding the default task.

Task Default -Depends DeployPackage

Clean

First of all we need to clean everything. For that we’ll build the solution with Clean target and also delete the packages folder.

Task Clean -Precondition { return $debugConfiguration -eq $null -or $debugConfiguration.clean } {
 Exec {
        msbuild $solutionToBuild /t:Clean /verbosity:$verbosity /nologo /p:Configuration=$config /p:VisualStudioVersion=12.0
    }

  if (Test-Path "..\Source\packages") {
     Remove-Item "..\Source\packages" -Recurse -Force -ErrorAction Stop
  }
  else {
    "Didn't find the 'packages' folder."
  }
}

Restore packages

Every single build needs to restore all the packages, in this way we make sure that packages are not missing on the build machine.

Task RestoreNuGetPackages -Depends Clean -Precondition { return $debugConfiguration -eq $null -or $debugConfiguration.restorePackage } {
    if (!(Test-Path $nugetExe)){
        throw "nuget.exe could not be found on this machine. Please check: $nugetExe"
    }
    Exec {
      & $nugetExe restore $solutionToBuild
    }
}

Our mobile service project references a NuGet package hosted on the TeamCity machine. But the NuGet feed requires authentication. In order to restore that package on the TeamCity machine during the build process we need to allow the restore process to authenticate to that NuGet feed. There is a command line we need to run on the TeamCity VM.

Login on the TeamCity server and make sure that you use the same account you used when you installed the TeamCity agent. It’s important that the agent runs under the same account. We configured the agent in step 1 where I mentioned that. NuGet should add the configuration file (NuGet.config) in the same user’s folder.

For example, if you run the agent under the ‘teamcity’ user name then when you add the NuGet source as below (run the below command) it will create or update the file in this location:

C:\Users\teamcity\AppData\Roaming\NuGet\NuGet.Config

This is the command line you need to run:

NuGet.exe Sources Add –Name [GIVE_A_NAME] -Source [TEAMCITY_FEED] –UserName [USER_NAME] –Password [PASSWORD]

Sources – TeamCity NuGet feed. Check the configure NuGet server post

UserName – user name you provided when you setup TeamCity. You can create a new user name just for this purpose but in this case you’ll need to run the agent under this user

Password – user name’s password

Update assembly version

There are different methods to update the assembly version. You can keep the version in one AssemblyInfo.cs file and add that file as a link to all the projects but I don’t like this idea because you can forget to do that and some of your libraries will not have the version updated. Instead of that I iterate through all the projects and update the version for every single AssemblyInfo.cs file.

Task UpdateVersion -Precondition { return $debugConfiguration -eq $null -or $debugConfiguration.updateVersion } {
    (Get-ChildItem -Path $sourceDirectory -Filter AssemblyInfo.cs -Recurse) |
    ForEach-Object {
      (Get-Content $_.FullName) |
        ForEach-Object {
          $_ -replace 'AssemblyVersion.+$',"AssemblyVersion(`"$version`")]" `
          -replace 'AssemblyFileVersion.+$',"AssemblyFileVersion(`"$version`")]"
        } |
        Out-File $_.FullName
    }
}

Build

The build process should create a package which will be deployed to Azure. In order to do this we’ll use DeployOnBuild=true and PublishProfile=PublishProfile.xml parameters.

The PublishProfile.pubxml file doesn’t exist. We need to generate it. In order to do this we have the pubxml.template file in the Scripts folder. It contains the following xml:

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <WebPublishMethod>FileSystem</WebPublishMethod>
    <LastUsedBuildConfiguration>Release</LastUsedBuildConfiguration>
    <LastUsedPlatform>Any CPU</LastUsedPlatform>
    <SiteUrlToLaunchAfterPublish />
    <LaunchSiteAfterPublish>False</LaunchSiteAfterPublish>
    <ExcludeApp_Data>True</ExcludeApp_Data>
    <publishUrl>{0}</publishUrl>
    <DeleteExistingFiles>True</DeleteExistingFiles>
  </PropertyGroup>
</Project>

You can change it if you need to. We’re interested in the publishUrl value – we need to populate it during the build process with the package location. If you’re going to have a fixed package location then you can hard-code it but in our case the location will be driven by the TeamCity. We’ll generate the package in the “[Root]\Artifacts” folder. Root is the folder where our Scripts and Source folders are located.

The PublishProfile.pubxml file is generated in the method “GetPublishProfile” and will be saved in “[Root]\Artifacts” folder. Later it is overwritten by the build with the package. To some extend this simulates the same process you have when you deploy from Visual Studio.

function GetPublishProfile() {
    # Get the publish xml template and generate the .pubxml file
    $scriptPath = Split-Path -parent $PSCommandPath

    if (Test-Path $artifactDirectory) {
        Remove-Item $artifactDirectory -Recurse -Force -ErrorAction Stop
    }

    [String]$template = Get-Content $scriptPath\pubxml.template

    mkdir $artifactDirectory | Out-Null
    $xml = $template -f $artifactDirectory
    $outputPublishProfile = Join-Path $artifactDirectory "PublishProfile.pubxml"
    $xml | Out-File -Encoding utf8 -FilePath $outputPublishProfile

    return $outputPublishProfile
}

Task Build -Depends RestoreNuGetPackages, UpdateVersion {
    $publishProfile = GetPublishProfile 

    Exec {
        msbuild $projectToBuild /p:DeployOnBuild=true /p:PublishProfile=$publishProfile /verbosity:$verbosity /nologo /p:Configuration=$config /p:VisualStudioVersion=12.0
    }
}

Unit Tests

All the Unit Tests were implemented using xunit. First we need to build the solution which will create the Test*.dll files. After that we’ll run every Test*.dll file by xunit.exe.

xunit.exe file is added as a NuGet package. In order to do that we need to add this to our Test project, otherwise it will create a .nuget folder with packages.config file and we’ll put it under the solution folder. You can add it as I NuGet package for the solution but I don't really like it for small projects.

  <package id="xunit.runner.console" version="2.0.0" />

The full source code of the Unit Test

Task Test -Depends Build {
  if (!(Test-Path $xunitConsole))
  {
    throw "xunit.console.exe does not exist. Please check $xunitConsole file."
  }

   "************* Build solution [$solutionToBuild] for Unit Testing *************"
  # Need to run the solution to build all the tests. The Build Task run only the csproj file
  exec {
    msbuild $solutionToBuild /verbosity:m /p:Configuration=$config /p:VisualStudioVersion=12.0 /nologo
  }

  $assembliesToTest = (Get-ChildItem "$sourceDirectory" -Recurse -Include "*Test*.dll" -Name | Select-String "bin")

  $atLeastOneTestRun = $false

  "************* Running Unit Tests *************"
  foreach ($testFile in $assembliesToTest){
    "*************** Testing $testFile ***************"
    $fullNameTestFile = Join-Path $sourceDirectory $testFile
    
    & $xunitConsole $fullNameTestFile
    $atLeastOneTestRun = $true
  }

  if ($atLeastOneTestRun -eq $false){
    Write-Output "Unit Tests didn't run!"
    exit(1)
  }
}

Now we can build and test our project. In the next post I will explain how to deploy an Azure Mobile Service.

< Previous post

Create NuGet packages using AppVeyor

Fri, 22 May 2015 07:45:39 GMT

This blog explains how to create a NuGet package and use AppVeyor as a continuous integration and deployment tool.

I found out about AppVeyor some time ago from Scott's blog - "AppVeyor - A good continuous integration system is a joy to behold". Usually I use TeamCity running on a VM so I didn't have a chance to try it out until recently when I built a NuGet package to generate random users. The NuGet package is based on the https://randomuser.me API – a free API to generate random user data. You would use it in prototyping, testing or filling your database with proper user names, pictures, etc.

AppVeyor is a cloud based continuous integration and delivery service for .NET. It is free for open source projects. It has everything you need and it is really easy to set up. It has a nice Web UI where you configure your build and deployment settings but in this post I will explain the minimum configuration you need to publish a NuGet package using the appveyor.yml file. The reason I prefer to keep my configurations in a file rather than using the UI is that I can version it and when I break something I can fix it fast just by checking the differences in the file.

Every AppVeyor configuration can contain an appveyor.yml file in the root folder. If you have the file and also configure the UI then the YAML file will override the UI settings unless you explicitly disable it in Ignore appveyor.yml settings in the UI.

AppVeyor also has the option to host NuGet packages. Before pushing the NuGet package to https://www.nuget.org I use that to test my packages.

Here's the full YAML file. As you can see, it is self-descriptive and I will explain only the settings which are not clear from the first glance or might be confusing.

version: 0.9.{build}

assembly_info:
  patch: true
  file: AssemblyInfo.cs
  assembly_version: '{version}'
  assembly_file_version: '{version}'
  assembly_informational_version: '{version}'

platform: Any CPU

configuration: Release

build:
  project: RandomUser.sln
  verbosity: detailed
  publish_nuget: true

before_build:
  - nuget restore

nuget:
  account_feed: true
  project_feed: true

deploy:
  provider: NuGet
  api_key:
    secure: oersntns349lpwtsaAThuwfs//74hanwoIEN
  skip_symbols: false
  artifact: /.*\.nupkg/

Will let AppVeyor to take care of the release version number. For this purpose {build} is used. Assembly files will be patched with the version value we define in “version”.

In order to publish to NuGet the following should be added to the appveyor.yml file

build:
  publish_nuget: true

deploy:
  provider: NuGet
  api_key:
    secure: oersntns349lpwtsaAThuwfs//74hanwoIEN
  skip_symbols: false
  artifact: /.*\.nupkg/

You need to get your NuGet API key and encrypt it. AppVeyor offers a tool for encryption at this URL https://ci.appveyor.com/tools/encrypt

In artifact you provide the file name or artifact name to push.

As I said before I prefer to create NuGet packages using AppVeyor feed before pushing them for the first time to nuget.org. For this purpose you need to add the following:

nuget:
  account_feed: true
  project_feed: true

Make sure that your project contains a nuspec file in the same folder where your .csproj file is. You can find more information about nuspec here: http://docs.nuget.org/Create/Nuspec-Reference

All the tests are run automatically by the way.

Displaying AppVeyor build status badge in a repository

Wed, 29 Apr 2015 21:21:00 GMT

If you're using AppVeyor for your CI then you can display the build status in your repository readme page. You do that by using the Status Badge. There’s is good documentation on their web site http://www.appveyor.com/docs/status-badges. But if you're doing this for the first time then you might get confused as to which option to choose and where to get the data you need.

If you don't want to read an entire blog about badges then head to your AppVeyor project page, click on the settings link and then click on the Badges link. Search for Sample markdown code, copy that code and put it in your repository page. You're done.

If you're still reading then you want to know more details, so choose the option that suits you better. The examples I will provide are from my randomuser GitHub repository.

Public repositories from GitHub or Bitbucket

If your source code repository is public then you have two options:

Use the URL as described above from your project settings
Use the URL from your public repository. In this case you need to have only one AppVeyor project.
The URL has the following format:
https://ci.appveyor.com/api/projects/status/{github|bitbucket}/{repository} For example:
https://ci.appveyor.com/api/projects/status/github/ralbu/randomuser

I would prefer the second choice for public repositories. In the first case you need to embed your AppVeyor project id into the url. I'm not sure about the security implications in this case, if let's say you want to make the AppVeyor project private. In this case you don't want to expose that id.

Status Badge options

You have three options when displaying a badge:

A simple badge. Use the URL with no query string parameters
https://ci.appveyor.com/api/projects/status/github/ralbu/randomuser

Retina badge. Add retina=true parameter
https://ci.appveyor.com/api/projects/status/github/ralbu/randomuser?retina=true

This parameter will scale the image but the image doesn't look very sharp.
SVG badge. Add svg=true parameter
https://ci.appveyor.com/api/projects/status/github/ralbu/randomuser?svg=true

I like this badge and I use it instead of the first two.

Building state of the status badge

There is a difference in the status displayed on the badge when the project is queued or in building process on the SVG image compared with other two images.
The SVG badge says 'pending' and the other two say 'building...'

Display the status badge in the Markdown format

When using the Markdown format you display the badge status using the following format
[![Alt img description](Badge Url as described above)](The url to your AppVeyor status page.)

For example:

[![Build status](https://ci.appveyor.com/api/projects/status/github/ralbu/randomuser?svg=true)](https://ci.appveyor.com/api/projects/status/github/ralbu/

Conclusion

You have other options to choose from, like displaying the status of a branch. More information can be found on http://www.appveyor.com/docs/status-badgesing

Hosting NuGet in TeamCity and consume it in Visual Studio

Sat, 21 Sep 2013 14:35:00 GMT

Introduction

This post describes the setup of NuGet package inside TeamCity and configuration of your Visual Studio to consume the hosted packages. TeamCity version 7.1 is used.

When you work on a big or medium projects you’ll end up having at least one common library. If you keep everything in one solution then you don’t have problems with sharing the common library – you reference the common project to all other projects which need it.

How about the case when you have multiple separate solutions/projects and want to use the common library. In this cases you have two options: a) add the common library into all the projects as Add Existing Project and b) add a reference to the common dll file. With both approaches you have tackle a set of issues, like how to update the common library and not to break the projects using it; what if you need to use it for a project in a location different to the library, let’s say common library is located on c:/project but the project using it is located on D:/WebSites. These are just a few issues but enough to give you a headache.

All these issues will go away by implementing your common libraries as NuGet packages. You can host these packages on the NuGet web site but you might not want to do it. Here I explain how to host them in TeamCity.

Pre NuGet Build Configuration setup

Will start with standard build configuration steps. In TeamCity create a new Build Configuration. Set the Build number format as it will help to keep track on the versioning and make the update process easier. Set Version Control settings.

Add a Build Step which will build your package solution. If needed add /p:Configuration=Release to Command line parameters to build the release.

Add a unit test build step if it is the case. For example select the MSTest as Runner type if you do MS Unit testing. Add the following **\bin\**\*.Tests.dll in the List assembly files.

NuGet package configuration

Next is the part which is most interested for us. But before that make sure you have the NuGet set in Administration > NuGet Settings.

Add a new Build Step and in the Runner type select NuGetPack. If you set the NuGet settings you should have NuGet.exe dropdown with the NuGet version.

In the Specification files select the project you want to create a package from.

Update Version to %build.number% if you want to keep the same version you set in General Settings of your build configuration.

Set the Output Directory. For instance, Build\packages

Make sure you check the Publish created packages to build artifacts.

Also you might want to check Include sources and symbols but not mandatory.

NOTE:

In the Build Steps screen add AssemblyInfo patched in Additional Build Features so it will update the dll version in order to keep your files versioned.

That's all you need to set for TeamCity to create NuGet packages.

Visual Studio configuration

Next we need to configure VS to get the package from TeamCity.

In VS open Tools > Library Package Manager > Package Manager Settings. Select the Packages Sources and click the "+" to add a new sources. Give it a name and set the Source. If you haven't figured it out go into TeamCity > Administrator > NuGetSettings > NuGet Server and get the URL, either Autenticated Feed URL or Public Feed URL, depending how you configured it.

In order to add the common library to your project follow the same steps you do when you add a standard NuGet package to your project except you'll see now an additional repository - the one you’ve just created. That’s it – you now have your own NuGet package repository and you can add it to all your projects.

Using NuGet without committing packages to source control

When you add the NuGet package to your solution it will be added to your source control. So all the dll files will be committed to the source control. Starting with NuGet version 2 you have the option to download the library when you compile so the missing libraries will be downloaded on demand instead of keeping them on the source control. In order to enable this in VS open Tools > Library Package Manager > Package Manager Settings and select General. Check the Allow NuGet to download missing packages during build. This should be done on every machine. Next right click on the solution which uses the NuGet packages and select Enable NuGet Package Restore.

When you enable NuGet Package Restore a new .nuget folder will be created. It contains NuGet.exe file. It is executed during the build process to install the missing packages. This file should be added to source control. So if you have all your *.exe files ignored make sure NuGet.exe is not excluded, otherwise the build will fail.

Conclusion

One of the best way of sharing your libraries is using NuGet packages. You need to setup a TeamCity configuration build and configure the Visual Studio to access it. This post describes the steps you need to follow.

Git versioning for .NET projects with TeamCity

Thu, 28 Mar 2013 05:26:00 GMT

TeamCity has a nice feature which allows to create a build number automatically with every build. For example, MyLib.dll has version 1.2.3.0. When configuring TeamCity in the “Build number format” the value specified like {0} will increase with every build. So if you set “Build number format” 1.2.3.{0} then the last number (revision number) will increase with every build.

For a .NET project if you provide the AssemblyInfo patcher feature for your build configuration then the AssemblyVersion and AssemblyFileVersion will be updated automatically with the build number.

This works well for the cases when only one number should be changed. But you might want to have two numbers updated with your build, build and revision values. With Subversion you can include the repository Revision number as part of the building number. Git doesn’t provide this number because each commit is represented by a SHA1 hash.

The solution will be to take advantage of the number of commits since the most recent tag. This is made available through the git describe command.

This will work only if you have at least one tag in your repository and every time you need to change you version you need to create a new tag. Also you need to push your tag to the remote repository as it is not pushed automatically.

Let’s add a new tag to your commit

git tag v1.2

And use describe command

git describe --tags --long

Will display

v1.2-0-gb2d5397

The --tags flag allows to use lightweight tag and --long takes care to display the long format – the tag, the number of commits and the abbreviated commit name.

The 0 number represent the number of commits.

The describe command works fine but what happens if a new tag is created and its purpose is not for versioning. To fix this will add the --match flag so your command will become:

git describe --tags –long --match v?.?

This will display only the tags which are in format v?.?, v1.2 for instance. If you want to keep your versioning tags differently, for example version1.2 then you need to change v?.? to version?.?

That is all good but how can we use it with TeamCity? We will create a Powershell script which parses the output and creates the build number.

In TeamCity “Runner type” is set as Powershell and in the “Script arguments” %build.number% is provided.

Will use the following script

Param ([string]$build_num)

$git_version = (git describe --tags --long --match v?.? | Select-String -pattern '(?<major>[0-9]+)\.(?<minor>[0-9]+)-(?<seq>[0-9]+)-(?<hash>[a-z0-9]+)').Matches[0].Groups

$git_describe = $git_version[0].Value

$version = [string]::Join('.', @(
  $git_version['major'],
  $git_version['minor'],
  $git_version['seq'],
  $build_num 
))

Write-Host "##teamcity[buildNumber '$version']"

Line 1: reads the provided %build.number% from TeamCity
Line 3: uses the git describe command and creates an object with all version parts
Lines 7-12: create a version string based on the git tag and TeamCity
Line 14: uses TeamCity service messages to pass the information to TeamCity

This step should be added before the step where you compile your project.