Now that you have a Team Foundation Service account, some of you are going to be interested in setting up a build machine to work with it.  Richard Hundhausen did a very nice video to walk you through this process but I’m going to recap it because there’s a few additional things I want to explain.  If you watch his video, it’s higher fidelity than this post but you might get some additional understanding here.

First let’s talk about options.  You can install and configure a build machine to run against your Team Foundation Service account.  You will have to use a TFS 11 build agent.  The TFS build agent is part of the TFS install and is available to MSDN subscribers on the download site and will be available to everyone tomorrow (Friday 9/16) at this url: http://go.microsoft.com/fwlink/?LinkId=225714

You can install the build server on any machine you use – a workgroup machine at home, a domain machine at work, an Azure VM Role, an Amazon VM, whatever you like.  TFS doesn’t really care.  The machine just has to have connectivity to the internet to get to tfspreview.com.

Run the TFS installer on the machine you want to install the build controller/agent on and you’ll accept the license, copy the bits on to the machine, etc and then get an install screen like this.  Since you are just installing a build server, you don’t want to choose any of the Team Foundation Application Server wizard.  You just want the Configure Team Foundation Build Service.  Click on “Configure Team Foundation Build Service” and then click the Start Wizard button at the bottom.

You’ll see a welcome page, click Next and see this.  If this isn’t what you see, try canceling and make sure you had the right wizard selected.  This wants you to identify your team project collection/account on the hosted service.  You can’t type here so just click the Browse button.

And you’ll see this.  I’ve not connected to a server from this machine before so there’s no server for me to pick from.  I click the Servers… button.

And get the list of available servers – see there aren’t any.  I told you   So click the Add button.

You can type the full url in the top line if you want but here, I’m using the dialog controls.  “minka” (that’s actually the name of my farm ) is the name of the account so I give a name of minka.tfspreview.com.  Then I click the https button (you have to use https to connect to the server for this).  The url in the preview field is what I could have put in the top edit field if I had wanted to.

Now I click OK and I go back to the previous window and close that and I see this.  For our TFS Service, the team project collection is always called DefaultCollection and you can only have one.  In the on premises product you can have more than one and name them whatever you want.  Select DefaultCollection and click Connect.

At this point you are connected and the url will be filled in the wizard page above.  Click next on that wizard page and you’ll go to the Build Services page.  This allows you to configure how many agent you want running.  The default is 1 per core but I don’t really need to build 8 things in parallel on my little machine at home so I changed it to 2 and clicked Next.

That takes me to the Settings page which controls how the build service runs on my local machine.  Remember the build service itself runs on the machine I’m installing it on and it needs some identity to run as.  It’s going to connect to my hosted account with a different identity but more about that in a minute.  I created an account on my local machine called “Build”.  I could have called it anything I want or used the account I was logged in as.  If I had been on a domain, I could have used Network Service but I’m at home so I’m just using a local machine account.  BTW, while I was playing with this, I discovered that we don’t support accounts with no password right now.  That’s a bug and we’ll fix it.  I’m logged in to my 11 year old’s account at home and he doesn’t have a password   That’s the only reason I went and created a new account just for the build service.

The last thing you do is specify what port on your local machine you want the build service to use.  This isn’t the port on the hosted service but rather the one on your local machine.  The default works for most people.

Then there’s that bit in the middle about authenticating with the hosted service and the Windows Credential Manager.  Let’s finish the wizard and then I’ll talk about that.

Click Next and you can review your choices and click Verify.  Everything should Verify fine and you can click Configure.

When configuration is done you’ll get a completion screen that looks like this.  You can now finish out the wizard and it will launch you into the TFS admin console.

Click on the Build Configuration node on the left and see that you controller and agents are up and running and all is happy.  You can close the admin console, go into VS, start creating build definitions and running builds.

Now what about those funny credentials.  There’s up to 4 sets of credentials at play here:

1. What you are logged into the local machine you are installing as.  As long as you have sufficient permissions to install that’s all that really matters.
2. The account you configure the local build service to run as.  That’s what you entered into the wizard.  I used a local account called “Build”.  Many people just use the account they are logged in as or, if they are on a domain – Network Service.
3. The Live ID that you log into your Team Foundation Service account with.  It only plays a part here in that you have to authenticate with the service using that Live ID when you in the connect dialog sequence above.  If the system hasn’t saved those credentials you’ll get a Live ID web page to log in.  This makes sure that you have permission to configure a build machine against your account.  You wouldn’t want random people creating build machines against your account would you?
4. The service identity that the build agent uses to connect to your Team Foundation Service account – we sometimes refer to this as the “Project Collection Identity”.  This is the bit of magic that the text in the above dialog is about.

Let me expound on #4…  The build service, running on your local machine, needs to talk to your hosted account.  To do that it needs to authenticate (login).  Unfortunately, it can’t use your Live ID because Live ID doesn’t support automated services authenticating.  Fortunately, we use Windows Azure Access Control Services (aka ACS) to handle authentication and ACS supports something called service identities that are explicitly designed for this kind of scenario.  The build setup wizard you’ve just run uses the Live ID authentication you did when you connected to create a service identity for you and generates a random password.  It then puts that password in the Windows Credential Manager for your local build service account.

When I look in my Windows Credential Manager for my local “Build” account, I see:

Note it’s got my url https://minka.tfspreview.com/defaultcollection and an auto generated user name (the name of your ACS service account on the hosted service) – “Account Service (minka)”.  And it’s got my auto-generated password.  Please, please, please don’t change it.  That will only change your local copy (not the one on hosted TFS) and your build service won’t work.  Since you don’t know what the auto-generated password is, you can’t set it back.  That means you are hosed.  the only thing you can do is unconfigure the build service and reconfigure it from scratch.

Let’s look at this in the admin console:  If I click the “Properties” link on the build configuration page, I get a dialog like this.  I need to click the “stop to make changes” link which stops the local build service while you make configuration changes.

OK, now my local build service is stopped.  Notice the two tabs at the bottom.  The visible tab, “Servi ce Identity” is actually the account that your local build service runs as on your local machine.  My computer is KIDS-PC and the account is Build.  I can change that and save the changes and all will be well.

The other tab, “Project Collection Identity” is what account the build service uses to talk with the server (in this case my hosted TFS account).  For our hosted TFS service, I have to use an ACS Service Identity and I can’t change it or the password (at least right now).  We have not built any feature of the service to change either the ACS service account or its password.

OK, that’s some long gory details about exactly how it works.  Most people need never know or care.  Run through the wizard and it just “does the right thing” for you.  But just in case you ever need to understand what is going on, now you do.

Have fun!

Brian