This tutorial carries continues on from the previous tutorials Part 1: Create your First Project, Part 2: Create your First Configuration and Part 3: Create your First Repository and it is recommended that these are completed before reading this tutorial.
So far we have created a project, attached a configuration and created a repository, however we still cannot run a build! Fear not, by the end of this tutorial you will have be ready to run your first build up and running.
In this tutorial we will be creating an a MSBuild action that will build our Fluent NHibernate source repository using Visual Studio. This tutorial assumes you have Visual Studio the .NET 4.0 Framework installed on your server.
...
Go ahead and try running a build. The easiest way to run a build is by using the Quick Build button (Fast forward icon) on the configuration tile. The quick build action will run a build with the default actions parameters passed into the build process.
Once the build has been run, it will turn red, as seen shown below. The reason the build failed is that there are no actions for the build to complete. Well this is easily fixed by adding some actions to the Configuration Workflow in the Configuration Wizard. Click the Edit Configuration button (Edit pencil icon) on the configuration tile to enter the Configuration Wizard then click 4 Stagesnavigate to the Stages section of the Configuration Wizard.
Stages & Workflow Editor
Welcome to the Stage & Workflow Editor. This is where you define the individual actions that will be executed run when a build is runexecuted. For more detailed information on working with workflows, check out the Managing Stages section.
Stages
Continua CI creates a default 'Build' Stage when a new configuration is created and this stage can be seen is displayed near the top of the page in the Stage Editor. Each stage is represented as a blue chevron and is accompanied by a stage gate, which is represented as a box with a triangle missingcut out. Stages can be used as a way to break a complex build process into smaller, logical pieces. For example, your build may consist of a build stage, a test stage and a deployment stage. For this tutorial however the default 'Build' stage will be all we need.
...
Actions are the individual build steps that are executed when a build is run. These actions range from running a batch file to running a build runner and executing unit tests. All actions are defined and controlled through the bottom section of the stages page. On the left you can find all the available actions and to the right is the Workflow Editor where the action execution order is defined.
So lets create our first action by navigating to the Build Runners category as seen below. Selecting the Build Runners category will display all available build runner actions that can be executed within Continua. For this tutorial we want to build our Fluent NHibernate source code using Visual StudioMSBuild, so lets add a Visual Studio .NET MSBuild Action by double clicking Visual Studio MSBuild.
Selecting an action will bring up the action dialog where you can set all the properties for your Visual Studio MSBuild action. In this tutorial we will need to point this action to the Fluent NHibernate Visual Studio Example .sln csproj file, so lets set the Project File property to $Source.Fluent_Nhibernate$/src/FluentNHibernate.slnExamples.FirstProject/Examples.FirstProject.csproj. Continua CI supports Variables, Objects & Expressions which we are using in this field to point to our repository. You can see that we are using $Source.Fluent_Nhibernate$ to point to our repository rather then providing a concrete file path. This is done so that you do not need to worry about where repositories are located as Continua CI looks after all repository management for you. So lets breakdown what is happening when we define our project file to point to $Sourceas $Source.Fluent_Nhibernate$/src/FluentNHibernate.slnExamples.FirstProject/Examples.FirstProject.csproj.
Continua allows you to specify dynamic objects and variables that are then given values when a build is executed. Dynamic objects and expressions are registered with surrounding $ symbols. In the image below you can see that specifying $Source.$ displays a dropdown that lists all the repositories that can be accessed from this configuration. At the moment we only have our Fluent NHibernate repository, however any other repositories that may have been created will also display in this list. So by setting the project file to $Source.Fluent_Nhibernate$, we are pointing Continua to our Fluent_NHibernate repository. If you called your repository a different name then this property will need to reflect the new name. ie. $Source.<repo_name>$
Anything that follows $Source.Fluent_Nhibernate$ refers to the file structure of the repository itself. So by specifying specifying /src/FluentNHibernate.sln we Examples.FirstProject/Examples.FirstProject.csproj we are telling Continua to get the FluentNHibernate.sln file Examples.FirstProject.csproj file from the src/Examples.FirstProject folder of the repository. On the GitHub Fluent NHibernate page you can see the project's repository structure. In the two images below, you can see how we point to the .sln csproj file in Continua CI and how the project's file structure looks over at GitHub.
For this tutorial we only need to set the project file, make sure Project File, set the action is enabled to enabled, set Configuration to Release, set Output Path to $Workspace$/Output and set the Using property to whichever Visual Studio version that is installed on the server..NET Framework version that is installed on the server.
You should notice that we also used a dynamic expression when setting the output path. In this case we used the expression $Workspace$. This expression is extremely important in Continua as it references the workspace folder on the agent where all your build actions will be executed. As each build is executed it dynamically creates new temporary directories on the agent while the build is executing. These directories will always be created in the ContinuaAgent folder which you specified when you installed the agent. The reason you should always refer to your build files using $Workspace$ is that you do not know the directory name or structure at runtime. By using $Workspace$, you will always be referencing the root folder for a specific build on the agent.
You may also notice that we are specifying that this project should be built in the subfolder 'Output'. By default, every stage will copy all the files from the output folder back to the Continua server once the stage has completed. This copying of data between the agent and server is defined on the stage itself using Workspace Rules. For this tutorial however, the default workspace rule is all we need, as long as our project is built in $Workspace$/Output.
The Using property is used to tell Continua which version of Visual Studio the .NET Framework it should use when executing the Visual Studio MSBuild action. This Using property uses property collectors to point Continua to the correct application it should use when performing a task. Unless your Visual Studio .NET framework was installed in a non-standard directory, the default Property Collector should find Visual StudioMSBuild. If Continua cannot find Visual Studio MSBuild then a new property collector will need to be specified in the administration section.
Once your Visual Studio MSBuild action has been configured, click Save which will add your action to the Workflow editor, as shown below.
If you were to create additional actions then these would also be added to the Workflow editor underneath your Visual Studio MSBuild action. In Continua, actions toward the top of the list are executed before actions that are towards the bottom. For now though, the Visual Studio MSBuild action is all we need to build our project so lets save our workflow by clicking Save & Complete Wizard.
Congratulations, you have created your first action workflow! Continue on to Part 5: Using Builds where we demonstrate how to run your build and access all the build information.
Continue to Part 5: Using Builds