In this article, I will discuss a basic functionality of Team Foundation Server 2013 Build Service which is the use of Arguments and Variables.
In Using Environment Variables in Visual Studio 2013 and TFS 2013 I discussed how environmental variables can be used and accessed with Team Foundation Server 2013 Build Service. Let us first find out the difference between arguments and variables. According to this msdn post, the differences are as follows:
To differentiate this further, an argument is used to communicate between the Workflow Engine and the activities. Variable can have scope for complete workflow or any sequence. In order to send any value to an activity or get from activity, we can use arguments.
An argument can also be used as a parameter in order to communicate to the outside world. This is done using Metadata.
Build Service has a workflow and there are activities in a particular sequence in it. Activity does not decide which will be the next activity or sequence to be called, but the workflow decides this. That is why we do not have to specify the flow of activities/sequences in XAML for workflow for the activities. When we are designing a flowchart, the rule we follow is no diagram should remain hanging. In XAML for workflow, we do not have to worry about it.
An activity is a base unit of creating a workflow. Even a simple WriteLine can be an activity. An activity can be simple or composite. It may receive run time values and also may return them at run time.
The normal Build Workflow process looks as follows.
Let us take a small example to make our understanding of the difference between arguments and variables, even better. In this example I am going to download the default template and do some modifications to it. Following are the steps for doing it.
- Create a blank solution and add it to Source Control. As we will be creating a Build later, it is required to add the solution to the Source Control so that the code will be built. Add a Console Application to it.
- Start the wizard from New Build Definition, select Process tab and click on Download for Default Template.
- Download it at the same location as that of the solution and provide some meaningful name to it. (It is not advisable to keep the same name as we will be doing some changes to it). Open the xaml file in Visual Studio 2013.
- Click on the Arguments tab
- You will see a list of all the arguments.
Let us explore one of the arguments which is shown in the list. BuildNumberFormat is used as an argument which specifies the build number when a build is triggered. This build number will be used to create the name for the drop folder once the build is successfully completed. The argument BuildNumberFormat is also used as parameter which is available for modification during editing build definition.
- Now we will add a new argument. To add an argument go to the end of list, click on the area where you see Create Argument. The default name for the argument is ‘argument1”, change it to TestArgumentMessage. Keep the other values as they appear. You can see the direction is In (which means the value will be given from the workflow to the activity), argument type string and the name I have set. If the direction is Out it will be to the workflow from the activity. You can also use InOut for both ways. There is one more direction property which will be more useful when you are working with Code Activity (activity using C# code)
- I will add a sequence activity at the end of the existing workflow activities and add a WriteBuildMessage activity in it
The Information icon will specify that there needs to be some configuration done for either the parent or the child activity. Once this is done the icon will be removed.
- WriteBuildMessage will be configured as follows
I am going to check-in the xaml and queue the build. The diagnostics will be shown as below
Every time you do any change to the xaml, you need to check-in so as to reflect the changes.
- Now we will create a variable with the complete scope. Select Overall Build Process and create a variable for it. Set its value as below. You can see the scope, if you select some other activity, the scope of the variable will be limited to it. (You can observe that variable1 is having scope for Run on agent. I have added this only to show the difference in scope. There is no need to add this variable)
This variable will be used to get value from the Out argument.
- In order to see how Out argument works, I am going to use activity called “GetEnvironmenVariable<T>” and drop it before the existing WriteBuildMessage. While dropping, change the type to string. I have set the display name to “Build Number” and done the configuration as follows
Observe that the result will be automatically set to TestVarMessage. The Name will fetch the BuildNumber as shown and will set it to the variable.
- The information symbol shows that the mandatory configuration is not set
Now the sequence activity looks as below
- Let us save the xaml and check-in to the source control.
- Create a Build Definition with this modified template and queue the build
- The build diagnostics shows the value of the variable along with the previous argument
- Let us now add a parameter which first will be visible during build editing, as well as while queuing the build. In order to add a parameter, we need to click on the ellipse (…) button in Metadata argument. We will get the following list as shown below. Go to end of the list. Provide the following values.
The parameter added can be viewed while editing, while queuing a build or always. As you can see I have selected always.
- Let us check-in the template and now see the parameter in edit as well as queuing of build
Now the queued build shows new value in diagnostics
In this article we discussed how arguments and variables can be used during Build Process and the difference between them.