Alexander Vanwynsberghe

"There is nothing impossible to him who will try"

How to setup DirSync with Project Online

Last week, the Active Directory team released a new version of a tool called “DirSync”. This is a tool who makes it possible to synchronize Active Directory accounts from your on-prem environment with Office 365. The version they release was a special one. Let me quote:

I’m happy to let you know that we’ve made it dead simple to connect AD to Azure AD, enabling users to log into Office 365, Windows Azure and any other cloud app integrated with Windows Azure AD using their on-premise username and password.  We’ve done this by updating Windows Azure Active Directory Sync Agent (a.k.a. DirSync) adding the ability to sync hashes of users’ on-premise AD passwords into Windows Azure AD.

How cool is that? Well, curious as I am, I decided to give this tool a go and synced my (playground) Active Directory to my Project Online tenant (which is nothing more than a Office 365 subscription). In this post, I’ll explain how you can achieve this.

First things first, you need an Active Directory. If you have an on-prem AD, just skip this step, at it’s just for demo purposes. As I don’t have the required hardware, but I do have an MSDN subscription, I used some Windows Azure VM’s for that part. What I did was first creating a DNS server (Networks -> Virtual Network -> Register a DNS Server). Next, a new virtual network using my DNS Server. Now  you can create your 2 Azure VM’s. I will not explain this in detail, but be sure that you use your Virtual Network when you go trough the Wizard.

03

You need 2 VM’s, one for the Active Directory role and one responsible for the DirSync. I’ll not go into detail about how to setup an AD role and how to join the other machine to this domain. You can find all info here: http://technet.microsoft.com/en-us/library/jj574166.aspx. Once completed, you should have this:

04

Next up, we will ‘enable’ DirSync at our Office 365 subscription. Browse to https://portal.microsoftonline.com/DirSync/DirectorySynchronization.aspx and enable step 3:

11

Next up, we will install the “DirSync” tool. You can download the latest version here (or use the “Download” link on the page you’re currently looking at). Once the file has been downloaded (180 MB), run the installer, and follow the wizard. The installation takes about 10 minutes.

05

Once the installation has been completed, the configuration Wizard will start. Provide your Windows Azure Active Directory Administrator (WAAD) Credentials. This is the account that you used to create your Office 365 subscription. (if you don’t know the credentials, or you want to try, browse to: https://activedirectory.windowsazure.com and test it)

07

At the next step of the wizard, enter your Active Directory Enterprise Administrator Credentials.

08

At the next step, be sure to enable “Enable Password Sync“. That’s this cool new feature!

09

Once the last step has been completed, a first “full sync” will be started:

10

That’s it! Nothing special. Now you have to check the “Users” in your Project Online (office 365) subscription. Browse to “Admin -> Office 365 -> Users“. There you will see the AD users! Great! Now, just “syncing” this users does not mean that they have access to your subscription. They are not assigned to a license. To manage this, click on the user, and select “Activate Synced Users

12

Assign the correct license to this user, and click “Next” to finish. Note that this user will get a temporary password, but you don’t need this as you have DirSync with password sync (joy!).

13

Still one small thing to do. “Share” my site (in this case the Project Web Access) with that new user. Just click on the “Share” button.

14

Now open a new (inprivate) browser window, and login using the username and password from your Active Directory. There you go:

15

There you have it! A sync between your AD and Project Online (Office 365). But it doesn’t stop there for this post. I just wanted to be sure that the password sync does actually work. So I changed the password and the first name of my user in my AD. But then … How can I force a sync? By default, it takes about 3 hours (password changes-only will be instantly, but changing a name for example will take some time).

So, PowerShell to the rescue! Browse  to “C:\Program Files\Windows Azure Active Directory Sync” and double-click on DirSyncConfigShell.psc1. Enter the command “Start-OnlineCoexistenceSync“:

16

If you open the “Event viewer” on your machine, you will see some entries from the AD sync:

17

Enjoy your syncing!

Using Project Online OData with Excel Web App

Project online has some great reporting features. One of the features that I really like is the OData service. This OData service is not only available for Project online, but also for on-premise deployments. To access this feed, all you have to do is browse to the following url: “/pwa/_api/ProjectData”.

One of the tools to “explore” this Odata feed is Excel. You can open one of the existing Project Online reports with Excel. Go to “Reports – English – Project Overview Dashboard” and click on the 3 dots, select “Edit“.

01

The report will open in Excel, and you can now select the ‘DATA‘ tab, and press ‘Refresh All‘. This should load all your data and show you a list of all projects with some additional information. This is pretty cool, but can we also use this within the Excel Web App? Well, let’s try it straight. Go back to the “Reports” folder, and instead of clicking on the 3 dots, just click on the name of the file. Excel Web App should open, and you will see an empty list of projects. Now click on the Data tab and select “Refresh All Connections“.

02

So, that’s not what we were expecting. It looks like Excel Web App cannot access the Odata feed. The explanation is quite simple:

When Excel workbooks are refreshed in Office 365, the BI Azure Service retrieves updated data from Project Online and recalculates the internal workbook model. If the workbook has data connections pointing to Project Online OData feeds, the BI Azure Service must have permission to the SharePoint Online tenant to retrieve that data.

What we have to do is giving the BI Azure service the required permissions to access our Project Online tenant. Browse to your PWA instance, and add “/_layouts/15/appinv.aspx” to the URL. For example “http://yourtenant.sharepoint.com/sites/pwa/_layouts/15/appinv.aspx“. You will now see the application permission screen. In the App ID field, add 00000009-0000-0000-c000-000000000000 and click Lookup. The title and App domain should tell you we’re working with the Azure AnalyisisServices. Copy and paste the following in the Permission Request XML Field

03

Click create and Trust the App.

04

To be sure that the App has been granted with the correct permissions, go to “Admin (on top) – SharePoint – Apps – Permissions“. There you should see the App “Microsoft.Azure.AnalysisServices

05

That’s it. Now we can open the report using Excel Web App, and click on “Data – Refresh All Connections“. Have fun!

06

Note: Be sure that you first refresh and save your report using the Excel (desktop) application. This will update the internal model of the workbook so it is supported by Excel Web App.

Debugging SharePoint 2013 remote events using the Windows Azure Service Bus

In this post, I will talk about how you can debug remote events within a SharePoint 2013 App. Especially with the Autohosted App Model (I made a post about that a while ago). Let me first start with a small and really easy to understand app that I will use to highlight the topic of this post.

The App

It’s quite an easy app where you can:

  • Add a contact
  • Get a contact

The App has some logic in the Web project (to manage the button “Add Contact” and “Get Contacts“), and a “List” in the SharePoint project. You will find the sources at the bottom of this post. When running this App, you will see something like:

03

As you can see, the “FullName” contains the text “Not set!“. That’s correct, I only provided my first and last name. But I want my full name to be “managed” by a remote service. And that’s where this post is all about. Finally! What I want is a remote event receiver that will be triggered when a new contact has been added. Add one to the SharePoint project. Right-Click and select “Add – New – Remote Event Receiver”. Call it “Contact List“. You need to select the type of event on which the event receiver needs to do something. Select “An item was added“.

02

You will now see a new folder in the Web Project called “Services“‘ and a new service called “ContactList.svc“. When you open it, you should see 2 methods. The one we need is called “ProcessOneWayEvent“. You can add the following code:

What it actually will do is get the ClientContext and get my first and last name that I submitted. It will than perform a string merge and add it to the “FullName” of the ListItem. Nothing fancy. So, why don’t we just hit F5 and check it out? You will soon find out that it will not work, the service is not being called. You can try to add a breakpoint, and you will see that it will be ignored. But why?

Problem

The problem is quite easy to understand. What will happen when you press F5 is a “Publish” of your App to SharePoint online, and once you “Trust” the App will eventually loop back to your “Local IIS”  (as you can see in the URL of the screenshot at the beginning of this post). It looks like:

problem1

So our Web project is running locally, meaning that our web service is also running locally. So in our case, when we hit the button “Add Contact“, it will try to call our Remote Event Receiver. So from a  SPAppWeb (which is SharePoint Online) context, it will not be able to contact “Localhost“. It looks like:

problem2

Solution: Windows Azure Service Bus

In the final “RTM” version of Office Developer Tools for Visual Studio 2012 there is cool feature called “Enable Remote Event Debugging“, making use of the Windows Azure Service Bus. Now first of all, what’s that Azure Service bus? Let me take the description from MSDN:

The Windows Azure Service Bus provides a hosted, secure, and widely available infrastructure for widespread communication, large-scale event distribution, naming, and service publishing. The Service Bus provides connectivity options for Windows Communication Foundation (WCF) and other service endpoints – including REST endpoints — that would otherwise be difficult or impossible to reach. Endpoints can be located behind network address translation (NAT) boundaries, or bound to frequently-changing, dynamically-assigned IP addresses, or both.

In other words, the Windows Azure Service Bus allows you to expose our local WCF service to the “outside world”. And that’s exactly what we need! All you have to do is get yourself a Service Bus instance and enable this feature in the SharePoint App project properties. You can get a Windows Azure Service Bus  instance using the Windows Azure Management Portal. On the left side, click on “Service Bus” and click on the “Add” sign on the bottom of the page. Add a name, and finish the wizard.

06When your service has been created, all you have to do is click on the “Access Key” button and copy the connection string. Next, right-click on your SharePoint App project in Visual Studio and select “SharePoint“. There you can “Enable Remote Event Debugging“:

08

Now you can add a breakpoint in your service code and press F5. There you go:

09And if you look at the App itself, you will see that the “FullName” has a value:

10

Mission accomplished! You can download the sources here. Have fun! Oh, and just a small note, did you know that you can actually see which services are available/active on you Windows Azure Service Bus? Just browse to the URL of your service bus, and you should see:

04

How to use Project Server Online data in a SharePoint 2013 App using CSOM

This week I was attending the 3 day Project Ignite training. This is a technical training offered directly from Microsoft and was presented by Christophe Fiessinger and Jan Kalis at Warsaw (but I followed the training on Lync, which was really cool using the 360-video). I learned lots of new and interesting things about Project Server 2013 and Project Online. Thanks Christophe and Jan!

Of Course, that’s not the topic of this blog post. During the last day of the training, we got some information about the extensibility options for Project Server 2013. One of the topics was about CSOM, which is an abbreviation for Client-Side Object Model, and also about JSOM, which stands for Javascript Object Model. Let me use the slide from Project Ignite explaining what it is all about:

As you can see, an interesting topic to do some deep diving and (as Christophe told us to) doing our homework. I’ll guide you through the process of creating:

  1. A console application, connecting to my local Project Server 2013 lab machine and create a project.
  2. A SharePoint Autohosted app (based on my previous blogpost: Windows Azure auto-provisioned apps for SharePoint 2013), connecting my Project Online PWA instance using OAuth 2.0 and retrieving a list of projects.

1. Local Console Application

To start, I will create a small piece of code to create a project on my local Project Server 2013 lab machine. So no SharePoint app, no authentication, just creating a project using CSOM. To start, open your Visual Studio 2012 and create a new Console Application. The first thing you have to do with this empty console project is referencing 3 DLL’s. If you’re developing on a machine with Project Server 2013 installed, you can add a reference directly, otherwise you need to copy the 3 DLL’s to your development machine (create an ‘Assemblies’ folder in your project) and reference them this way. The 3 DLL’s you need can be found in the folder “%ProgramFiles%\Common Files\Microsoft Shared\Web Server Extensions\15\ISAPI\ “. Copy those items:
  1. Microsoft.ProjectServer.Client.dll
  2. Microsoft.SharePoint.Client.dll
  3. Microsoft.SharePoint.Client.Runtime.dll

Reference them in your project and open ‘Program.cs’. Add the code, listed here, to your application. I’m not going to repeat every piece of code, as it’s explained very well on that link. But what I want to mention is ‘security’. If you run your SharePoint/Project Server 2013 dev environment, and you develop your application on another machine, you need to provide credentials to connect to SharePoint/Project Server, in fact, you need to initialize the ProjectContext with those credentials. The ProjectContext contains the client-side context for development with a Project Web App instance, and contains the enterprise-wide collections of Project Server objects that exist in Project Web App. You can get the ProjectContext using your credentials with the following quick and dirty solution:

If you run the application (after you added the following command to the start-options of your project: -n “Test Project using CSOM 01” -t 20) , you should see:
In general, it’s all about the ProjectContext. Using this context, you can do/get whatever information you want. In this case, a new Project is created using the object ‘ProjectCreationInformation’, this object is added to the ‘projContext.Projects‘ and finally you tell the context to update with this new project. This will create a queue job and will perform the required action. That was easy to do!

 

2. SharePoint Autohosted App

In this part, I will create a SharePoint Autohosted App where I will use the CSOM to retrieve a list of all projects. You can find a step-by-step guide in one of my previous posts. What you will need  is a subscription of Project Online Preview  (of course). If you haven’t got a  subscription yet, you should really try it out (more info can be found in this post). The first step is to create a new “App for SharePoint 2013” project using Visual Studio:
On the next screen, you should enter the URL of development site (note: when you want to debug Apps on SharePoint Online, you need to have a site collection created as ‘Development site’ type. Otherwise, you will receive an error while publishing in debug mode). This option does have an impact when you want to try debug apps for Project Server (using PWA), but more about that later.
No you have an empty SharePoint App. In our case, we want to use this app to get a list of projects stored on our online PWA. If you look at the files in your project, you will see a file called ‘TokenHelper.cs‘. This is a file responsible for the OAuth 2.0 authentication of your application with SharePoint. It includes the code to handle OAuth 2.0 authentication and how to perform callbacks to SharePoint using CSOM. More information about SharePoint 2013 authentication can be found here.
This TokenHelper class is used to get a SharePoint ClientContext, like you can see in the code below. The TokenHelper returns an authenticated instance of the ClientContext, which is the CSOM you can use to create some cool things.
This is great for SharePoint, but we need something different, we need a ProjectContext. This ProjectContext object inherits from ClientContext in SharePoint,  so you can also access the SharePoint CSOM through this ProjectContext object. To get this context, we need to change some small things to the TokenHelper class. Create the following 2 new functions in TokenHelper.cs
Now we have can get our ProjectContext using the “GetProjectContextWithContextToken” function. We can use the following code just to output the list of Projects:
What it basically does is loading the Projects into the ProjectContext and execute the query to get the results. Ok, now that you have the code, you should manage the permissions of the App. Because will we ‘read’ data from Project Server, we will need this permission to be able to actually read the data. The permission configuration settings can be found in the AppManifest.XML. You can find this file in your Solution Explorer. When you open this file, Visual Studio will show you an editor where one of the option is about permissions. Add the permission ‘Projects Read’ to this list and save the file:
Allright, we have the code and the permissions for our App are set. The next thing is, how can we debug this app? Well, remember when you created the project. We’ve added the URL to our Development site on SharePoint online environment. This development site is a seperate Site Collection. The first problem with that is the fact that this Site Collection does not contain a PWA instance. So if we debug our current application, we will never get data. The second problem is about the permissions. When you try to debug the application, it will check the permission settings. Because we created a permission ‘Projects Read’, we will always get an access denied error, simply because there is no PWA there. So, debugging the application on a Development Site Collection will give you:
You could also try to debug it directly on the PWA site (by changing the debug URL), but then you get this error when debugging:
I passed the question about this to Christophe, and he forwared my question to Eli Sheldon (Program Manager at Microsoft). He gave me this explanation (Thanks!):

SharePoint added a site collection level feature near RTM that, once enabled, will allow you to F5 deploy from VisualStudio, no matter what type of site collection you are targeting. Until the new bits roll online and this is documented, your best option here is to F5 debug on-prem and publish an app package and use the corporate catalog to test online.

So as you can see, currently no F5 debug with this release. But the RTM is coming really soon! (Should be there around mid November for MSDN subscribers). So for now, just publish the App and install it on our Project Server Online environment.  Right-click on your project containing the AppManifest file and select ‘Publish‘. You will get this dialog:
Click finish, and the output folder of your .APP file should open. Now we should ‘upload‘ it to our SharePoint Online environment, and make it available for the users. The place where App’s are managed is called the “App Catalog“. This app catalog is a separate Site Collection, and can be created using the SharePoint Administration Center. There you can click on ‘Apps – App Catalog‘. If you haven’t created one yet, it will create one for your, and otherwise, you will be redirected to the App Catalog itself. On your App Catalog site, click on ‘Apps for SharePoint‘ (on the left side). You will see an overview of all installed apps, including an indication of the licenses you still have available. To add your App, click ‘New Item‘ or drag and drop your .app file to the top area of this page.

Now you have your new Application available in the App Catalog. To use it, just go to Project Server Online PWA. Go to ‘Site Contents‘ on the left side, and click on ‘Add an App‘. There you should see the application we’ve just uploaded. Click the App, and you should get a question to confirm the required permissions. In our case, reading Project data. Trust this and continue. When the process is ready, your application is installed on your site, and you’re ready to use it. Click on the App, and you should see:

That’s a list of your projects, retrieved by the ProjectContext (CSOM). Nothing fancy, no HTML, just plain text. Cool! Now it’s up to you to use the CSOM and create some great apps! I’m really excited about this way creating apps, the way CSOM works, the flexibility, the (future) debugging.

 

3. The things we learned 

  1. You can do lots of things with the ProjectContext
  2. Don’t forget to setup your Permissions in the AppManifest file
  3. You can’t debug until RTM

Thanks to my colleague Koen Callens for the fun experience of creating our first App together! Thanks for reading, and enjoy creating your Project Server apps!

Windows Azure auto-provisioned apps for SharePoint 2013

I suppose you all heard about the “App” concept in SharePoint 2013? If not, you have a nice overview about this new concept on msdn. An app for SharePoint is a great way to surface a remote web application in SharePoint. In this post, I want to tell you a little bit more about Windows Azure auto-provisioned apps for SharePoint 2013.

Imagine this: Wouldn’t it be cool if you can deploy whatever custom web application with whatever server-code behind it, directly to your Office 365 instance? Well, using the Windows Azure auto-provisioned apps you can. First question you can ask yourself, what’s Windows Azure doing in this story and how does it link to your Office 365? Well, to get this working internally each Office 365 gets automatically an Azure account associated. That’s nice, and really powerful. Because you now have both Azure and Office 365 together, you don’t have any reasons or whatever to stick with your on-premise installation.

An auto-provisioned app contains at least one Windows Azure Web Site that can be launched from a SharePoint 2013 Preview host web, and may also include SharePoint components on an app web and a SQL Server database (based on SSDT and .dacpac packages).

Let’s take a look what the development and deployment process looks like:

  1. The developer builds a SharePoint application into in .APP file
  2. Deploy to SharePoint
  3. SharePoint installs the application for you
  4. SharePoint provisions all Azure components
  5. SharePoint provisions the SQL Azure database and initializes everything included in the .dacpac (Data-tier Application Component Package)

So in general, you create an application, publish it to SharePoint, and SharePoint will do everything for you. So creating an Azure Website, manage your database on SQL Azure and initialize everything.

Let’s try it out. First you have to create a new SharePoint project in Visual Studio 2012. Open Visual Studio and click ‘File –  New Project‘. In the ‘new project‘ window, select ‘Visual C# – Office/SharePoint – Apps‘ and select the ‘App for SharePoint 2013‘ template. Give your project a name and click ‘Ok

Note: If you have never created a SharePoint/Office 2013 app before, you will not find the Project Template in Visual Studio 2012. You need to install the Microsoft Office Developer Tools for Visual Studio 2012. You can download this here. It will start WebMatrix and download all the required components you need.

On the next screen, enter the name of the application, and the URL of your development site. I used my SharePoint Online subscription for this. Be sure to use a ‘Development Site‘, otherwise you will get an error when you try to test your application. (been there, done that!). If you don’t have a development site, create a new one and use the ‘Development’ template when creating. That will do the trick. Ok, in the current window, also be sure to select  and choose “Autohosted”.

When you click ‘Finish’, your project will be created. Basically, it will create a solution with 2 projects. The first project contains an AppManifest file, and the second project is a simple ASP.NET application.

The AppManiFest file is the definition of your SharePoint application. It contains a title, a name, which (tile) icon it uses, what the start page is, which permission requests it need to run (for example accessing  User Profile information),… The ASP.NET application itself is really basic, but one thing to notice is the file ‘TokenHelper.cs‘. This is a file who is responsible for the OAuth 2.0 authentication of your application with SharePoint. This helper class is used in Default.aspx. It includes sample code about how to handle OAuth 2.0 authentication and how to perform callbacks to SharePoint using CSOM.

In this example, we won’t change anything and just continue and get our application up and running. All you have to do is click on ‘Debug‘, or just press ‘F5‘.

In the output console of Visual Studio, you will see that the SharePoint application will be uploaded to SharePoint, and that SharePoint will do the necessary things to install it. Note that your App is NOT provisioned on Azure yet. If the installation was successful, your browser will be opened and will ask you to do a login and it will now ask you: “Do you trust your application”? Click ‘Trust it

You will now have your application listed as an item in the ‘Site Contents‘.  Click on your application and you will get a certificate error. If you look good to the URL of your application you will see ‘http://localhost:xxxx’. What SharePoint did was an installation, and during the installation, the application URL was set to your localhost environment. Indeed, if you look on that taskbar of your machine, Visual Studio started an IISExpress with the same port as the one SharePoint redirects you to. Just ignore the certification error and continue.

What you see now is not quite much. What this example basically does is using the ‘SPHostUrl‘ parameter that is added to the URL when SharePoint opens your application. Using this parameter, the application will get an access token (using OAuth 2.0) and use this token to get a client context object. This object can load the title of the SharePoint site you’re using. Because your app is hosted locally using IISExpress, you can easily debug it.

Ok, let’s assume that our application is ready to be deployed. We can use Visual Studio to deploy our application. Right-click on your project containing the AppManifest file and select ‘Deploy‘. It will now execute the same process as before (as you can see in the Visual Studio Output window). When your application is installed, trust it, and click on the Application icon to open it.

As you can see now, the URL is not on localhost anymore, but it got a unique o365apps.net URL. So our application has been deployed to Windows Azure, awesome!

Of course, we’re still in development. But let’s say that everything is good, tests are written and the application is ready to go live, how can you do this? Well, we first need to create an ‘APP’ package of our application. In Visual Studio, right-click on your project containing the AppManifest file and select ‘Publish‘. You will get this dialog:

Click finish, and the output folder of your .APP file should open. In fact, an APP file is nothing more that a zip file (you can open it with 7Zip for example), containing all your artifacts. A bit like the WSP files.

Ok, so we have our APP file. Now we should ‘upload‘ it to our SharePoint farm, and make it possible for users to select this application on their site. The place where App’s can be managed is called the “App Catalog“. This app catalog is a separate Site Collection, and can be created using the SharePoint Administration Center. There you can click on ‘Apps – App Catalog‘. If you haven’t created one yet, it will create one for your, and otherwise, you will be redirected to the App Catalog itself.

Adding an App to the catalog is really simple. On your App Catalog site, click on ‘Apps for SharePoint‘ (on the left side). You will see an overview of all installed apps, including an indication of the licenses you still have available. To add your App, click ‘New Item

It will open a new dialog where you can select your .App file and give it a version comment. Click ‘OK‘ to continue. The next dialog gives you an overview of everything related to your application. Complete this as you want, and click ‘Save

Now you have your new Application available in the App Catalog. To use it, just go to a site where you want to use the application. On this site, go to ‘Site Contents‘ on the left side, and click on ‘Add an App‘. Look what you see there, the application we’ve just uploaded:

Click the App, trust it, and your application will be provisioned by SharePoint. When this process is ready, your application is installed on your site, and you’re ready to use it. Click on the App, and you should see:

The text displayed is the name of my site, which is ‘Ideation’, and you also see a unique ID in the URL = a unique Windows Azure website. (Note the ‘Website’ part of the name).

So that’s it. We have our SharePoint app up and running on Windows Azure. Great! One thing that’s really important to know: each ‘installation’ of our App will provision a new Windows Azure Website. So this will be a part of your billing/account, don’t forget that.

To finish this post, I’ll give you 2 reasons to use this approach:

  1. When you deploy an autohosted app for SharePoint, all Windows Azure and SQL Azure components are provisioned for you when the app for SharePoint is installed.
  2. The Windows Azure Web Sites infrastructure handles load balancing, multi-tenancy, and other important maintenance tasks for you.

Thanks for reading!

TFS 11 Beta Build Service on Windows Azure

front

With the new upcoming version of TFS, you will have to possibility to have your own TFS instance running on Windows Azure, called “TFS Preview”. One of the cool things about this is the fact that you’re not responsible anymore for the TFS infrastructure. You don’t have to invest in some decent hardware, everything you want is there for your, on Windows Azure.

The one thing you need to have ‘on premise’ is a build server, as TFS Preview does not give you any options to use a cloud-based build server. Which is in fact understandable, because a build server can generate lots of load and needs to be monitored precisely. But, shouldn’t it be cool to have ‘everything’ in the cloud? Well, actually you can: TFS Build Service on Windows Azure using the VM Role

In this post, I’ll take you trough the steps to setup your own build service and host it on Windows Azure.

1. Azure account

Because you will be hosting your build service on Azure, I suppose you already have your an Azure account. If not, you might already have access using your MSDN subscription (there is some good information on this blog post). The next thing you have to do is signup for the VM role beta program. You can do this on windows.azure.com and then select “Beta Programs”.

2. Base VM Role Image setup

The next thing you have to do is create your VM Role Image, which you will use to upload on Windows Azure. In fact, this virtual image will be configured like an on-premise build service. This image contain an operation system (off course) and a TFS 11 build controller with one (or more) build agents.

  • To get started, open Hyper-V manager on a Windows 2008 (R2) machine, and select the option to create a new Virtual Machine.
  • Follow the wizard, and set the amount of memory to 2048 MB. Also be sure to select the ‘Virtual Network’ connection.
  • Create a new virtual disk called “baseimage.vhd” and set the size to 30GB (when you select this size, you can deploy the VM in a “small” role, take a look at the pricing for more info)
  • Finish the wizard, boot your new virtual machine and install your operation system (windows 2008R2 for example).
  • There is a special requirement for a valid VM Role image. You have to allocate the entire virtual hard disk file to a single partition where you install the operating system. To avoid creating a recovery partition during the installation, follow these steps:
    1. Choose the Custom (advanced) installation type to select the partition where you will install Windows.
    2. Press Shift + F10 to open a command prompt during GUI-mode setup.
    3. At the command prompt, enter the following commands:
      1. diskpart
      2. select disk 0
      3. create partition primary
      4. exit
    4. Close the command prompt window.
    5. Install Windows in the newly created partition.

3. TFS 11 Build Controller

  • Next step is to install the TFS build controller on the VM, but do NOT configure it yet. We will configure it when the VM role is online on Windows Azure.
  • To do this, run the TFS 11 beta installation (you can download the beta using MSDN or this link.)

  • When the installation is finished, close the Configuration screen.
Tip: When you are planning to build more than some ‘basic’ applications, be sure to also install Visual Studio!

 

4. Windows Azure VM Role Integration Components

The next part is the installation of the VM Role Integration Components. The integration components must be installed on the machine before base image is uploaded to the Azure. The integration components start each time the OS starts. It handles the integration between the role instance and Azure environment. Follow these steps:

  1. In the Virtual Machine Connection window, in the Media menu, point to DVD Drive and then select Insert Disk. In the Open dialog, browse to the location of the ISO file for the VM Role Integration Components, wavmroleic.iso, and then click Open. The wavmroleic.iso is located at ‘C:\Program Files\Windows Azure SDK\v1.6\iso\’
  2. In the Operating System Configuration step, enter an Administrator Password, confirm it, and then click Next.
  3. Follow the wizard and once the installation of the components has finished, you will be prompted to restart the system. Click Yes to continue.
  4. Wait for the system to restart and log in to the guest machine once again. Now, inside the VM, open the Start menu, type %windir%\system32\sysprep\sysprep.exe and then press Enter to launch the System Preparation Tool. Set the System Cleanup Action to“Enter System Out-of-Box Experience (OOBE)”, check the option labeled Generalize, set the Shutdown Options to Shutdown, and then press OK. This tool will prepare the image by cleaning up various user and machine settings and log files, as well as removing any hardware-dependent information.
  5. Wait for the system to completely shutdown. Your image is now ready for deployment.

 

5. Uploading the VM to Windows Azure

Now we have a VM image ready for deployment.  Next step is to upload this image. To do this, we will use the ‘csupload‘ command from the Windows Azure Command Prompt. Follow this steps:

  1. Open the Windows Azure SDK Command Prompt as administrator
  2. Type the following command to link the context to your current subscription:
    • csupload Add-VMImage -Connection “SubscriptionId=[SubscriptionId]; CertificateThumbprint=[ThumbPrint]” -Description “TFS Build Service” -LiteralPath “C:\baseimage.vhd” -Name baseimage.vhd -Location “West-Europe”
      • The subscription id can be found on the management portal in the property grid, when you select your subscription.
      • The certificate thumbprint is a private certificate that is installed on the local machine and that is linked to the management certificates on the Azure portal.  Uou can easily copy the thumbprint from the property grid in the Azure Portal
      • Be sure to change the LiteralPath to the location of where your VHD is located.
      • The location (data center) needs to be defined where the storage will be created. You can use friendly names like “West-Europe”
  3. Now the upload will start. The first step in the process is the preparation
  4. After preparation, it will start uploading. When the upload starts, you can see your new vhd on the Windows Azure portal as ‘Pending’
  5. Wait for the upload to complete. This can take several hours, depending on the upload speed of your Internet Connection. When finished, you should see:

6. Creating the Service Model

After completing the previous step, you now have a VM image deployed to your Windows Azure account. In this task, we will create a service model and configure it to reference this image.

  1. In Visual Studio, create a new Windows Azure Project. In the New Windows Azure Project dialog, click OK without adding any roles. You will create a Virtual Machine role in the following steps.
  2. When the solution is created, right-click the Solution folder and select New Virtual Machine Role. This option is ONLY available when you are in the VM Role beta program. When your request was accepted, you should have received an email with a link to enable the VM Role option in Visual Studio. If you lost this mail, you can use this link (32bit or 64bit), it’s a small change to the Windows Register.
  3. You should see a the properties of the new VM Role. In the ‘Virtual Hard Disk‘ section, select your Azure subscription and select the the image we have just uploaded
  4. In the ‘Endpoints’ section of the wizard, add a port for the build-controller. A TFS Build Controller uses 9191
  5. Save your settings and close the window. Next step is to publish your VMRole and meanwhile enable Remote Desktop. You can do this by right-click on the solution, and select ‘Publish’.  In this window, follow the Wizard and enable ‘Remote Desktop’.
  6. Now you can Publish this solution. You can follow the status of your deployment using the Windows Azure Activity Log screen.

  7.  The roles take the following statuses
    • Initializing
    • Waiting for host
    • Setting up Windows for first use
    • Starting Windows
    • Starting Traffic
    • Ready
  8. When finished you can see your Hosted Service using the Azure Portal. Now you can also connect to the VM using Remote Desktop. Click on the Remote Desktop icon and log in using your account (defined in the Remote Desktop Setup process).

7. Configure your Build Service

Last step is to configure your brand new Build Service. When you are logged-in on the VM using Remote Desktop, launch the TFS Build Controller configuration.

  1. Click on “Configure Team Foundation Build Service” and then click the Start Wizard button at the bottom.
  2. On the Project Collection screen, identify your team project collection/account on the hosted service.  You can’t type here so just click the Browse button and add your TFS preview/Hosted TFS account. In my case, I already have a build controller running, but I’ll add another one
  3.  Next step is to configure the Build Service. In my case, I already have a build controller, but I will replace it with a new one (the original one is offline). You can also decide to use this machine as a ‘Scale out’ system for an existing Build Service. This existing one will use this new machine as extra agent capacity.
  4. In the next step, you can configure which account will run the Build Service. This can be network service, or a specific account within your Active Directory (if you use Azure Connect with AD integration). This depends on the installation type. In my case, I’ll just use the network service.
  5. In the ‘Advanced‘ section, you can define your hosted TFS  Service Service Account. Leave this by default. You can also change/manage this using the Administration section of your Hosted TFS account, in my case:
  6. Verify and confirm the Configuration Settings
  7. Configuration completed
  8. That’s it, now your Build Service is up and running, on Windows Azure. Now you can tweak this by adding some agents,… You can manage the Build Controller using Visual Studio 11 (or 2010) by going to the ‘Builds‘ section of your Team Explorer, and click on ‘Actions‘.

8. Conclusion

Now we have our TFS11 Build Service up and running on Windows Azure. Now you can create Build Definitions and queue builds (a failing build in my case)

Good luck with your Build Service and enjoy it!
Thanks for reading.