This post covers the installation of the Visual Studio Team Services Build and Release Agent on Windows. This is the new cross platform agent and is currently in a Preview state. This is written in C# using the .Net Core CLR and runs on Windows, OSX, Ubuntu and Red Hat.
The existing VSO Agent is marked as Deprecated, care should be taken when using documentation on the internet to check if it refers to the new or old version of the agents.
This post uses the Visual Studio Team Services site created in the other blog posts in this series. For this post I have paid for additional agent slots in VSTS so my existing agents can be used. We cover adding a new Agent Pool for the local windows build agent.
This post covers installation and setup of the VSTS Build Agent on Windows on your own hardware to enable building of Xamarin Android projects only. Note iOS projects cannot be built using this setup, installing the build agent on OSX is required for this. The article Xamarin DevOps with VSTS - Setup a Cross Platform Build Agent on OSX shows how to setup a VSTS build agent on OSX.
I updated this post on 9th July 2016 to add the section on creating a new Agent Pool which I had previously omitted. I also edited the resources link to Start Windows rather than Start OSX.
Resources
The Cross Platform VSTS Build Agents are hosted on GitHub:- Visual Studio Team Services Build and Release Agent and Start Windows Agent
Donovan Brown's post How to Add a User to Team Foundation Administrators Group in Visual Studio Team Services
To add additional private build agents to VSTS follow the instructions in Pay for more services in Visual Studio Team Services
Key Points
The Agents used in this post are the new cross platform agents and are currently in a Preview state.
The free Visual Studio Team Services account supports one private agent in addition to the Hosted Agent.
If you need more VSTS Agent slots then follow the instructions Pay for more services in Visual Studio Team Services
Configure a Personal Access Token
The ReadMe.md for the Cross Platform VSTS Build Agent contains links to the releases for the various platforms and instructions for getting started.
The first step is to follow the Configure Account and Roles instructions.
Note if you created the VSTS site then you should have the correct permissions for the next steps, however if you encounter problems due to insufficent permissions then follow the instructions in Donovan Brown's post How to Add a User to Team Foundation Administrators Group in Visual Studio Team Services.
Navigate to the VSTS Home page:-
Click on settings cog in the top right and the Control Panel will be displayed:-
Select the ‘Agent pools’ tab and then select the ‘All Pools’ entry:-
Now we can create the Personal Access Token. Go back to the previous tab and click on the user name ‘blogaboutxamarin’ in the top right and select the ‘My Profile’ entry:-
Click on the ‘Security’ tab and the ‘Personal access tokens’ list will be displayed:-
Click the ‘Add’ button and the ‘Create a personal access token’ page is displayed:-
Next enter a description and set the ‘Expires in to the ‘1 year’ option. The ‘All scopes’ option should be checked.
Click the ‘Create Token’ button. The token will now be displayed with a message warning that it’s only available this one time so copy it.
Next we are going to create a new Agent Pool as we want to end up with the following Agents:-
- Default - Local (your hardware) OSX agent for Xamarin.iOS
- Hosted - VSTS Cloud Agent for Xamarin.Android
- LocalAndroid - Local (your hardware) Windows agent for Xamarin.Android
Click on the Agent pools tab and the Agent Pools are displayed. Click on the New Pool... button and the Create Agent Pool dialog is displayed:-
Enter a name for the Agent Pool, in this example I use LocalAndroid and click the OK button. The new Agent Pool will be listed:-
Installation of the Windows Build Agent
Next we can move onto the installation of the Cross Platform VSTS Build Agent itself. We need to follow the Start Windows instructions.
The first step of the Windows install involves ensuring the System Requirements are installed. This is essentially ensuring that Visual Studio is installed.
Download the windows agent from the GitHub Releases page.
Next follow the third step of the instructions to Create the agent. We will install the agent to a directory off of the C: drive named myagent. This location and naming can be altered as required. Open PowerShell, navigate to the C: drive and execute the following commands:-
mkdir myagent
cd myagent
Add-Type -AssemblyName System.IO.Compression.FileSystem ; [System.IO.Compression.ZipFile]::ExtractToDirectory("$HOME\Downloads\vsts-agent-win7-x64-2.101.1.zip", "$PWD")
ls
The screenshot below shows that the agent has now been extracted from the zip file into the myagent directory:-
Configure the Build Agent
We are now ready to configure the agent by executing the command:-
.\config.cmd
This will run the build agent configuration script, the first prompt is to enter the Server URL:-
In this example we enter:-
https://blogaboutxamarin.visualstudio.com
Next we are prompted to enter the authentication type:-
So press enter to use the Personal Access Token (PAT) authentication. We are now prompted to enter the PAT so paste in the PAT and press enter and the agent will connect to the server:-
We are now promted to enter the Agent Pool, so type in LocalAndroid and press enter. We are now prompted to enter the AgentName. In this case I will press Enter to accept the default suggestion of the Windows Computer Name DESKTOP-7J4VHTR:-
The agent should now have been added successfully. We are now prompted to enter a work folder. Press enter to accept the default work folder (or enter another name):-
The agent settings have been saved and we are prompted to run the agent as a service or interactively.
In this example we will choose to run the agent interactively, this will require we manually start the agent in a PowerShell or Command Prompt window in order to use it. Choosing the services option we would not have to do this and the build agent service will always be running and available. We press enter and the configuration is complete:-
Running the Build Agent
Now we can run the agent by executing the command:-
./run.cmd
Returning to the VSTS Agent Pools tab we can now see the the Default Agent Pool has an Agent DESKTOP-7J4VHTR listed:-
Queueing a Build
Now we can return to the VSTS Build page, select the HelloDevOps Android CI build:-
The build tasks to activate and de-activate the Xamarin License are not required for on premise builds. The Build your Xamarin app documentation covers this. To do this de-select the Enabled option on these build tasks:-
Now we can start a build by clicking the Queue build... button. The Queue build dialog is displayed. Ensure that the LocalAndroid agent pool is selected in the Queue drop down:-
Press the OK button and the build will start. We can see from the Build Summary Page that the build ran on the local agent DESKTOP-7J4VHTR we have just installed and configured:-
We can also see the build request listed in the Agent Pools tab:-
Returning to the Terminal window we can see that it shows the output of the Agent:-
This completes the setup of a local VSTS Build Agent on Windows.