Download this article as a PDF document.

Download corresponding Visual Studio 2012 project files.

Basic Configuration

The figure below illustrates the HealthVault Proxy Service using an Offline application deployment configuration. Notice that the HealthVault Proxy Service is a client of the HealthVault platform whilst Client Apps, interface directly only with the proxy.

This web-service does not need its own database and does not keep any state. It can easily run on an Azure WebSite or within an Azure WebRole. The proxy may also be deployed using an on-premises web-server for an enterprise scenario. Our Proxy Service exposes WCF (i.e. SOAP) service-interfaces. But, the sample could be modified to expose a REST interface instead.  We will defer that exercise for now in favor of some pending experimentation with Windows Azure Mobile Services (coming soon).

Figure 1. Basic Solution Architecture

The HealthVault Proxy Service exposes three primary service-interfaces for client apps. These interfaces correspond to HealthVault feature areas. Specifically, Patient Connect, Get/Put Things, DOPU.

Note: Learn more about HealthVault solution architectures and platform features at (http://blogs.msdn.com/b/healthvault/archive/2013/05/18/revisiting-connectivity-models-and-solutions-architectures.aspx).

Establish your Development and Test Environment

The Pre-Production Environment

From a platform perspective, HealthVault supports an ecosystem of applications and devices.   The HealthVault platform is well-documented with open support for practically any web-based client solution.  However, for integrity and security purposes, programmatic access to real user accounts is controlled.  In order to access the production HealthVault service, client applications must be authorized to access not only the production service itself but also individual consumer accounts hosted therein.  

This authorization process first involves development of your application utilizing a freely accessible Pre-Production Environment (PPE).   Once you have completed development and testing of your application using the PPE, then you may apply for authorized access to the production environment; a process termed “Go Live”.  

The Pre-Production Environment enables you to develop and test a complete end-to-end solution and thus gain a high-degree of confidence prior to final deployment.   Note that all PPE uniform resource identifiers (URIs) correspond to production environment URIs but with the “-ppe” suffix appended to the domain name (e.g. account.healthvault-ppe.com).  

Spend a few moments up-front establishing a HealthVault PPE “existing” user-account for your development purposes.  User logon and authentication to PPE corresponds exactly to the production HealthVault platform in that you may select from Windows Live, Facebook, or OpenID authentication.   We recommend creating a new test account using Outlook.com as illustrated.   You should first create the test account using Outlook.com, Facebook, or OpenID, and then proceed to the PPE environment in order to associate your new user-account with a corresponding HealthVault PPE account.

When you now logon to the HealthVault PPE Shell as a new user, the Shell creates an authorization workflow that associates your user-account with your corresponding authentication service.  

Consider end-user usage scenarios.  A common HealthVault end-user usage scenario involves a family.  A family healthcare manager (e.g. “Mom”) may configure, access, and manage HealthVault accounts for each family member (e.g. “Dad”, “Son”, “Daughter”).   Spend a few moments exploring the HealthVault PPE Shell.   Note that the “Health Information” section corresponds to collections of data-types that you may access from your solutions.

Register your HealthVault Proxy Service Application

The proxy service will need to be registered as a HealthVault application with a corresponding Application ID. Additionally, an X.509 Certificate will need to be generated and the public key provided to the HealthVault platform. The corresponding private key will be hosted within the proxy service itself and utilized for mutual authentication and encryption between the proxy service and HealthVault. You’ll want to first install the HealthVault .NET SDK on your development workstation along with Visual Studio.

After installation of the HealthVault .NET SDK, you will need to register your proxy application using the HealthVault Application Configuration Center (ACC).  The ACC enables a solution developer to associate an Application ID as well as a Public Key Certificate with a new HealthVault application.   A view of the ACC portal appears below.  Although you may accomplish the necessary registration steps using just the portal, don’t do so now.   We will instead utilize a tool included with the HealthVault SDK, the Application Manager, which automates this task.

From the Tools folder within the HealthVault .NET SDK installation path (e.g. C:\Program Files (x86)\Microsoft HealthVault\SDK\Tools) start the HealthVault Application Manager (i.e. ApplicationManager.exe).   Within the illustration below, note that I’ve already used Application Manager to create a new “HealthVaultProxy” sample.   Also note the link to the HealthVault Application Configuration Center (ACC) along with a short-cut to the local machine Computer Certificates store.   For our HealthVault proxy-service application, we will instead utilize the “Create New Application” feature.

Press the Create New Application button now.   This action opens the following dialog window.  For this scenario, we will not ask the Application Manager to also create a Visual Studio project directly but rather only utilize Application Manager to configure our application meta-data including Application ID and Certificate.

Within the Create New Application dialog window, type your solution name and uncheck the field labeled “Automatically create Visual Studio website for this Appliction”.   Press Create and Register Application.

Notice that this action launches the HealthVault Application Configuration Center (ACC) within a browser window.   You will first be prompted to logon.   Use an account that will be considered your Development Manager or Release Manager Account.  At the Terms and Conditions page, read and accept the agreement then select Create Application.  This registers your application with the HealthVault Pre-Production Environment and redirects your browser to the Application Configuration Center default page.   Your application name and assigned Application ID appear listed therein. The image below will differ based upon your specific application name and Application ID.

Also notice that the HealthVault Application Manager displays a new entry with a corresponding new self-signed certificate.  By convention, the Certificate Name corresponds to the assigned Application ID. 

Click the Computer Certificates link.   Notice the corresponding new certificate stored within the Local Computer certificate store.   Be sure to save and protect this certificate as it contains both your public and private RSA keys.   Plan to distribute only an exported certificate file containing your public key (typically saved as a file with the .cer extension).   A certificate containing only your public key has been automatically added to the Application Configuration Center during the Create Application step above.  Before moving your application to production, you may wish to assign a new production-only public-private key pair (i.e. a new certificate).

Let’s export the certificate file.  This may be done either from the ComputerCertificates console immediately above or via the HealthVault Application Manager.   Using the HealthVault Application Manager, right-click the Certificate Name and select Export public and private keys (.pfx).   Choose a destination folder that will be associated with the proxy-service solution files included with the Solutions Accelerator. The Visual Studio project’s “App_Data” folder is a good choice for prototype development purposes.

We are now ready to return to the HealthVault Application Configuration Center and complete the application registration process.  Within your browser, click on the Application ID link for the HealthVault Proxy Service application.

The resultant tab’ed web page represents your opportunity to tell the HealthVault platform about your application including why it needs access to HealthVault user-information, what fields will be accessed, whom to contact for management purposes, and additional rules and properties that you can explore later.   For now, navigate to the Offline Rules tab and select Edit.

Each HealthVault application will have a unique set of data-access requirements depending upon your solution requirements.  Hence, we’ll need access to a specific and custom set of information data-types within consumer HealthVault records.   Select that field group as illustrated below.   Be careful to also scroll the window further down and press the Save button.

Note: It’s common to configure both an Online rule and an Offline rule with the same configuration. This provides flexibility in solution architecture in that you may then provide both a User Portal as well as a Web Service usage experience.

Next, switch to the Methods tab within the HealthVault Application Configuration Center web-page. Configure your application as indicated within the following image. These "method" settings enable our application to utilize HealthVault platform features including "Patient Connect", "Drop-Off and Pick-Up", and to send insecure email messages.

Browse the additional tabs to familiarize yourself with additional configuration options. The Admins tab enables you to invite additional configuration managers to access this application configuration. At this point, you have everything you need to now configure and build the proxy-service sample application.

Configure, Build, and Deploy Your HealthVault Proxy Service

Modify your Project Settings

Now that you’ve utilized the HealthVault Application Configuration Center to register a new Application ID and a have corresponding X.509 certificate file, you may proceed to configure the sample proxy service project. Download the project files using the link provided at the start of this article.  Open the solution using Visual Studio. From within Solution Explorer, select and edit the HealthVaultAppSetting.cs file as illustrated.

Replace the dummy ApplicationID with your own as illustrated. Also set the .pfx certificate file name to match your new certificate file.

Note: Copy your certificate file (.pfx) into the solution’s App_Data folder. Be sure to set the certificate file property as “copy if newer” within the Visual Studio solution.

Also, note the myValidTokens Guid array within the AppSettings class. The corresponding list of tokens represents the list of client systems authorized (by you) to utilize this proxy service for access to HealthVault records. You must utilize and manage these tokens according to your business and solution deployment requirements. A typical scenario is to assign individual tokens to either separate departmental clinical systems or to individual client applications (e.g. enterprise tablets).  

Note:  Each of your client applications will share the same consumer record-set associated with your Application ID.   You will need to understand this scenario and ensure that your organizational access to HealthVault lands within the purview of terms of service and privacy constraints.  In effect you are responsible for authenticated and secure access to consumer records accessible via your web-service.   The sample code provided is for illustration and concept discovery purposes only and does not represent implementation of a web-service with complete authentication nor secure-access features.

In effect, our "token list" represents a shared-secret model of client-application support. Before moving this sample to production, you would want to implement a more sophisticated token-management facility than the simple Guid array provided. One possible approach is to implement a management interface that enables both application authentication as well as timeout-period token-generation. This article does not address security considerations beyond configuration of SSL for transport-level encryption between registered clients and the service.

Build and Test your Project

Use Visual Studio to build your web-service project. A console application project is also included within the sample solution. You may utilize this console application in debug-mode directly from Visual Studio in order to test connectivity and functionality of the web-service project prior to deployment to a hosted environment.

First, update the Service References section of the test client application. Initially, configure these service references to utilize the in-solution HealthVaultProxy library project.

Before running the test-client, look at the command-line usage options in file HVProxyTest.cs. Initially, just choose the "-createconnection" command-line option.

Open the project properties windows and configure the Command line arguments section as illustrated.

The -createconnection option will walk you through a sequence of questions and subsequently invoke the following TestCreateConnection method. Each of the remaining command-line options have a similar test-method illustrating the use of each web-service interface methods. Review file HVProxyTest.cs.

Deploy your HealthVault Proxy Service

Deploy the WCF web-service project to any IIS web-server reachable via HTTP or HTTPS. Windows Azure offers several web-site hosting environment options. We’ve utilized Azure WebSites for hosting our service during development and testing. This approach is very convenient, but not acceptable for production hosting because Azure WebSites doesn’t currently support HTTPS endpoints.  For production deployment, you’ll want to use the Azure Web Role option instead.  Proceeding with development/prototype deployment, configure your Windows Azure WebSite using the instructions provided here.

Once you have an Azure WebSite endpoint available, download the publish profile as illustrated. You will import this profile into your HealthVaultProxy project from the Publish menu.

You can easily deploy to an Azure website from within Visual Studio simply by right-clicking your HealthVaultProxy project within Solution Explorer and selecting Publish. Select Import and open the publish profile previously obtained from your Windows Azure dashboard.

Once you have your proxy web-service published to a hosted environment, note the service URL from the Windows Azure WebSite Dashboard. Copy this URL and use it to reconfigure your client-application Service Reference endpoints. Note they should point to your new hosted service URL (e.g. "MyProxy.AzureWebSites.net/HVConnect.svc").

Enable Transport Security for your HealthVault Proxy Service

Windows Azure WebSites are great for lots of scenarios including hosted web-services. However, this convenient hosting environment currently doesn’t support HTTPS (i.e. SSL).  [Correction 6/03 : Azure WebSites has just introduced SSL support.]  Hence, you’ll need to instead utilize the Windows Azure Web Role (i.e. dedicated virtual machine) deployment model in order to support SSL certificates.

You will need to modify your solution to add an Azure Web Role project as indicated.  Your HealthVaultProxy service will be hosted on a dedicated (but not state persistent) virtual machine.   Learn more about developing solutions with Azure Virtual Machines via the links provided at the end of this article.

See the following references section for information on using HTTPS with Windows Azure Web Role hosted services.

• Configuring SSL for an application in Windows Azure (http://www.windowsazure.com/en-us/develop/net/common-tasks/enable-ssl)
• Configure an SSL Certificate on an HTTPS Endpoint (http://msdn.microsoft.com/en-us/library/windowsazure/ff795779.aspx)

Corresponding modifications to the HealthVaultProxy project are limited to the web.config file and the system.servicemodel section as illustrated.

Next-Steps

Please note the following key-points.

1. This project intentionally does not depend upon any HealthVault SDK components on the client-side. All SDK constructs are hidden within the server-side proxy service. This approach is optional. Advantages include removing client-side dependencies and extending the range of possible client types. You may decide to import the Microsoft.Health.ItemTypes.dll assembly into your .NET client application project in order to work with "Thing Types" via C# classes instead of raw XML. Other options include writing simple wrapper classes (as I've done) or perhaps utilizing XSD.exe to generate C# classes from HealthVault Thing Type schema (see the schema type browser at http://developer.healthvault.com).
2. The HealthVault Proxy Service serializes Thing Type data into XML. JSON serialization API's are also available using the HealthVault SDK.
3. Our project utilizes WCF to expose SOAP based services. This approach is nice for many client application types (especially if you can use tools to generate the client-side proxies). However, it's not so nice for browser-based or JavaScript clients. For that scenario, a REST or HTTP Handler approach would be more ideal. We'll work on that demonstration soon.
4. There are lots of HealthVault features that we're leaving on the table. One of those is the ability to use built-in Thing Type transforms. A client could use these transforms to render data to HTML, for example, and thus achieve an easily coded HealthVault data-type viewer.
5. We recommend setting break-points within HealthVaultProxyTest and simply walk-thru the service interface methods to explore how Patient Connect, Get/Put Things, and DOPU work.
6. Integrate additional Windows Azure platform features.   http://www.windowsazure.com/en-us/develop/net/app-services/  and http://www.windowsazure.com/en-us/develop/net/fundamentals/intro-to-windows-azure/
7. Windows Azure virtual machines come in two flavors (persistent and not persistent).   Web-role hosted virtual machines are not persistent (also referred to as Platform as a Service, or PAAS).   You may wish to use the persistent variety instead (also referred to as Infrastructure as a Service, or IAAS).   Advantages of IAAS hosting include easy integration with on-premises services including your Virtual Networks and Active Directory.

A Quick Visual to Set Expectations

The following image is a screen-capture of the sample application as it opens from within the Visual Studio 2012 Windows Runtime simulator.   Please ignore the fact that our sample isn’t likely to pass the Windows Store “look-and-feel” quality-bar.   For now, we’re only interested in a simple UI experience that maps directly onto the primary HealthVault Library for Windows 8 API’s.   Notice that you can create a fully functional HealthVault application using only six or seven library functions.

When a user presses the Connect button, the application initiates an interactive session with the HealthVault platform.   If this is a first-time connection, a redirection to the HealthVault Shell with a logon experience occurs.   Subsequent connections use cached credentials.   Next, the user may press the QueryThings button.   This action results in a HealthVault query for a number of data-elements within the user’s HealthVault record.   Any items returned are display in a scrolling List View wherein the query results are serialized to XML strings and displayed as illustrated.

That’s it, nothing more than a simple demonstration of connecting-to, reading-from, and writing-to HealthVault platform services.   But, hopefully, that’s a good place to start and without introducing any unnecessary complexity.

A Look at our Visual Studio Projects

The following image illustrates the contents of the Visual Studio 2012 Solution.   Four projects are contained therein.   The HealthVault.Foundation project builds into an assembly providing lower-level functionality for connecting-to, authenticating-with, and exchanging-data with the HealthVault platform service.   The HealthVault.Runtime project builds into an assembly providing classes that encapsulate HealthVault data-types as well as classes that assist with storing HealthVault data within the Windows Runtime application cache facility.  You must add these two assemblies as references within your Windows Store HealthVault projects.   There is no need to use the published HealthVault .NET SDK as that SDK includes assemblies useful for Windows Desktop applications and not for Windows Runtime applications.

The hvJS project is the sample project provided previously demonstrating use of the aforementioned library but using HTML and JavaScript for the application user-interface.   The hvXamlCS project is the subject of this blog.   All of the code-snippets discussed herein are copied from either the MainPage.xaml file or the MainPage.xaml.cs file.   No other files need be modified beyond these two as generated via the New Project + Windows Store + Blank App (XAML) Visual Studio template.

Constructing our Main Page

The following XAML listing is copied from our MainPage.xaml file.   Refer to the application UI screen-shots above.   The elements herein serve to implement each element of the UI.   We’re using a parent Grid (line #1) defining three primary rows.   Grid-Row 0, line #10, defines our application title-bar.   Grid-Row 1, lines #13 thru #21, specify our user-action buttons.   Grid-Row 2, lines #22 thru #48, specify the functionality of our scrolling ListView control (aka: our “ResultsGrid”).

Note the use of DataContext binding at line #3.   Since we need to display a list of strings (i.e. a Collection of Strings), we’ll specify this in XAML as a CollectionViewSource element.   Additional data-binding statement occur further down at line #29 wherein we name the “ResultsListView” and bind it to the previously named CollectionViewSource “CVS”.  A final binding statement occurs at line #39 in which individual strings within our collection are bound as “Result” items.

 1: <Grid Background="{StaticResource ApplicationPageBackgroundThemeBrush}">

 2:     <Grid.Resources>

 3:         <CollectionViewSource x:Name="CVS" IsSourceGrouped="False"/>

 4:     </Grid.Resources>

 5:     <Grid.RowDefinitions>

 6:         <RowDefinition Height="Auto"/>

 7:         <RowDefinition Height="Auto"/>

 8:         <RowDefinition Height="*"/>

 9:     </Grid.RowDefinitions>

 10:     <TextBlock Text="My HealthVault App" 

 11:                Margin="12"

 12:                Style="{StaticResource HeaderTextStyle}"/>

 13:     <StackPanel Grid.Row="1" Margin="10" Orientation="Horizontal">

 14:         <Button Content="Connect"  Click="OnConnect" />

 15:         <Button Content="RevokeConnections"  Click="OnRevokeConnections" />

 16:         <Button Content="ReConnect"  Click="OnReconnect" />

 17:         <Button Content="AuthorizeOthers"  Click="OnAuthorizeOthers" />

 18:         <Button Content="GetThing"  Click="OnGetThing" />

 19:         <Button Content="QueryThings"  Click="OnQueryThings" />

 20:         <Button Content="PutThing"  Click="OnPutThing" />

 21:     </StackPanel>

 22:     <Grid x:Name="ResultsGrid" Grid.Row="2" Margin="10" >

 23:         <Grid.Resources>

 24:         </Grid.Resources>

 25:         <Grid.RowDefinitions>

 26:             <RowDefinition />

 27:             <RowDefinition Height="10" />

 28:         </Grid.RowDefinitions>

 29:         <ListView x:Name="ResultsListView" ItemsSource="{Binding Source={StaticResource CVS}}" 

 30:                 Width="Auto" Margin="0,0,0,0" Height="Auto" 

 31:                 VerticalAlignment="Top" Background="DarkGray"  

 32:                 ScrollViewer.HorizontalScrollBarVisibility="Auto" 

 33:                 ScrollViewer.VerticalScrollBarVisibility="Auto" 

 34:                 ScrollViewer.VerticalScrollMode="Enabled" 

 35:                 ScrollViewer.HorizontalScrollMode="Enabled">

 36:             <ListView.ItemTemplate>

 37:                 <DataTemplate>

 38:                     <StackPanel Orientation="Horizontal">

 39:                         <TextBlock x:Name="RowText" Text="{Binding Result, Mode=OneWay}" 

 40:                         Margin="0,0,0,0" Height="Auto" Width="Auto"  

 41:                         ScrollViewer.VerticalScrollMode="Auto" 

 42:                         ScrollViewer.HorizontalScrollMode="Auto" 

 43:                         ScrollViewer.BringIntoViewOnFocusChange="True" />

 44:                     </StackPanel>

 45:                 </DataTemplate>

 46:             </ListView.ItemTemplate>

 47:         </ListView>

 48:     </Grid>

 49: </Grid>

Now, let’s consider how this XAML specification maps onto our collection of results-strings within the code-behind file, MainPage.xaml.cs.   The class “ResultItem” is used to house a single string item.   The class derives from Windows.UI.Xaml.Data.IValueConverter in order to reuse the base functionality of data-exchange between individual ResultItem instances and corresponding individual TextBlock elements within the XAML show above (line #39).

 1:     public class ResultItem : IValueConverter

 2:     {

 3:         public string Result { get; set; }

 4:         

 5:         public ResultItem()

 6:         {

 7:         }

 8:  

 9:         public ResultItem(string result)

 10:         {

 11:             Result = result;

 12:         }

 13:  

 14:         // Convert and ConvertBack derive from IValueConverter and provide data-exchange with UI elements.

 15:         public object Convert(object value, Type targetType, object parameter, string language)

 16:         {

 17:             var item = value as string;

 18:             object retVal = Result;

 19:             return retVal;

 20:         }

 21:  

 22:         public object ConvertBack(object value, Type targetType, object parameter, string language)

 23:         {

 24:             throw new NotImplementedException();   // we're only using it for one-way visual output.

 25:         }

 26:     }

We establish our ObservableCollection (i.e. list of ResultItems) further below within MainPage class as illustrated via the following code-snippet (line #8).   The instructions at lines #15 and #16 programmatically bind the collection to our parent Grid as the CVS.Source.

 1: public sealed partial class MainPage : Page

 2: {

 3:     HealthVault.Foundation.HealthVaultAppSettings myAppSettings;

 4:     HealthVault.Foundation.HealthVaultApp myApp;

 5:  

 6:     // Use the ObservableCollection for DataContext Binding

 7:     private ResultItem resultItem;

 8:     public ObservableCollection<ResultItem> ResultItems { get; set; }    

 9:  

 10:     public MainPage()

 11:     {

 12:         this.InitializeComponent();

 13:  

 14:         // Bind our results string collection to the ListView UI element.

 15:         this.ResultItems = new ObservableCollection<ResultItem>();

 16:         CVS.Source = this.ResultItems;                                  

 17:  

 18:         // Create HealthVault Application Instance.

 19:         this.CreateHealthVaultApplication();   

 20:     }

While here, notice the call to CreateHealthVaultApplication(…) at line #19.  This method appears immediately below.  This demonstrates how to associate your application with the HealthVault platform.   The GUID listed within line #4 is the Application ID associated with this HealthVault application as registered using the HealthVault Application Configuration Center portal.   Learn more about how to register and configure a HealthVault application here.

 1: private void CreateHealthVaultApplication()

 2: {

 3:     // **** My AppID from config.healthvault-ppe.com ****

 4:     myAppSettings = new HealthVault.Foundation.HealthVaultAppSettings("8b48e454-f36f-4246-a6b7-b365af4754c4");   

 5:     myApp = new HealthVault.Foundation.HealthVaultApp(myAppSettings);

 6:     myApp.AppInfo.InstanceName = "hvXamlCS TestApp";

 7:     myApp.DebugMode = true;

 8: }

What remains to be illustrated is how the ResultItems collection is filled with individual Result objects.  Lines #14 and #15 from the TestGetThing method demonstrate this step.   The call to ScrollToBottom at line #17 is not strictly needed, it simply auto-scrolls the ListView so that the last ResultItems entry is visible.  

 1: async private void TestGetThing()

 2: {

 3:     // Get a simple Weight measurement

 4:  

 5:     ItemQuery query = HealthVault.ItemTypes.Weight.QueryFor();

 6:  

 7:     var record = myApp.UserInfo.AuthorizedRecords[0];

 8:  

 9:     ItemDataTypedList result = await record.GetAsync(query);

 10:  

 11:     foreach (var item in result)

 12:     {

 13:         Debug.WriteLine(item.Serialize());

 14:         this.resultItem = new ResultItem(item.Serialize());   // Update our collection

 15:         this.ResultItems.Add(this.resultItem); 

 16:     }

 17:     ScrollToBottom();

 18: }

The subsequent rendering of information is accomplished entirely via the automated DataContext binding of XAML and the Windows Runtime.   Note that we’re only putting new information into the display and not setting any class member data in our code-behind classes so there’s no need for two-way data-exchange.

Getting Things from HealthVault

A basic “Get Things” example function was presented immediately above.   The “TestGetThing” method is invoked when an application user presses the GetThing button.  Note that this test function uses the HealthVault.ItemTypes.Weight.QueryFor(…) library function to obtain a list of Weight measurements from the currently selected HealthVault user record.

The Weight class, like other data-type classes within the HealthVault.ItemTypes namespace, implements an QueryFor method derived from the HealthVault.Types.ItemQuery base class.   A simple and thankfully shallow class hierarchy exists in which individual HealthVault data-types, such as Weight, are defined.   You may easily extend this pattern to define your own data-types.   A key benefit of doing so enables participation not only in the QueryFor construct but also in IItemDataType derived serialization capability as illustrated in line #14 above.

Continuing with a more sophisticated query, the following source illustrates the use of an ItemFilter to specify a request for multiple ItemTypes (e.g. Weight, Condition, Medication) created after a specific date, and ordered by an effective date (lines #11 thru #19).   As indicated, the asynchronous request operation may be invoked with either a GetAsync(query) or a GetAllItemsAsync(query) library method call.   The later option returns when all pending HealthVault transactions occur.

 1: async private void TestQuery()

 2: {

 3:     // The following code queries for a maximum of 10 Weight, Condition, 

 4:     // and Medication items that were created after November 1st 2010 

 5:     // and returns the results ordered by the effective date of each item 

 6:     // (HealthVault’s default sort order). 

 7:  

 8:     ItemQuery query = new HealthVault.Types.ItemQuery();

 9:     query.Name = "GetThingsWithFilter";  

 10:  

 11:     ItemFilter filter = new HealthVault.Types.ItemFilter();

 12:  

 13:     filter.TypeIDs.Add(HealthVault.ItemTypes.Weight.TypeID); 

 14:     filter.TypeIDs.Add(HealthVault.ItemTypes.Condition.TypeID);

 15:     filter.TypeIDs.Add(HealthVault.ItemTypes.Medication.TypeID);

 16:     filter.CreatedDateMin = new HealthVault.Types.DateTime("11/1/2010");

 17:  

 18:     query.Filters.Add(filter);

 19:     query.MaxResults = new HealthVault.Types.NonNegativeInt(10);

 20:  

 21:     var record = myApp.UserInfo.AuthorizedRecords[0];

 22:  

 23:     // GetAsync is one approach...

 24:     //

 25:     // ItemDataTypedList result = await record.GetAsync(query); 

 26:     // foreach (var item in result)

 27:     // {

 28:     // Debug.WriteLine(item.Serialize());

 29:     // }

 30:  

 31:     // GetAllItemsAsync returns only when all recordItems AND 

 32:     // pending items have been retrieved from HealthVault

 33:     var result2 = await record.GetAllItemsAsync(query);   

 34:  

 35:     foreach (RecordItem item in result2)

 36:     {

 37:         Debug.WriteLine(item.Serialize());

 38:         this.resultItem = new ResultItem(item.Serialize());   

 39:         this.ResultItems.Add(this.resultItem);

 40:     }

 41:     ScrollToBottom();

 42: }

Putting Things into HealthVault

Adding information to a HealthVault user record is also very intuitive as illustrated in the following code-snippet.  Simply utilize the HealthVault.ItemTypes class library to set your chosen data-type properties.   Then, invoke the PutAsync API on the selected HealthVault Record.

 1: async private void TestPutThing()

 2: {

 3:     // Store a Blood Pressure item in a HealthVault record. 

 4:  

 5:     HealthVault.ItemTypes.BloodPressure bp = new HealthVault.ItemTypes.BloodPressure();

 6:  

 7:     bp.When = HealthVault.Types.StructuredDateTime.Now();

 8:     bp.SystolicValue = 120;

 9:     bp.DiastolicValue = 80;

 10:     bp.PulseValue = 58;

 11:     bp.IrregularHeartbeat = new HealthVault.Types.BooleanValue(false);

 12:  

 13:     var record = myApp.UserInfo.AuthorizedRecords[0];

 14:  

 15:     await record.PutAsync(bp);

 16: }  

Account and Connection Management

The following set of methods correspond to the Connect, RevokeConnections, ReConnect, and AuthorizeOthers buttons available via the application UI.   The use of these should be self-explanatory.  The primary objective is to add flexibility to your Windows Store application for the management of HealthVault account connectivity.

 1: async private void ConnectWithHealthVault()

 2: {

 3:     await myApp.StartAsync();   // Redirect to HealthVault for account access authorization.

 4: }

 5:  

 6: async private void ReconnectWithHealthVault()

 7: {

 8:     await myApp.ResetAsync();

 9:     ConnectWithHealthVault();

 10: }

 11:  

 12: async private void RevokeConnectionsWithHealthVault()

 13: {

 14:     foreach (var record in myApp.UserInfo.AuthorizedRecords)

 15:     {

 16:         await record.RemoveApplicationRecordAuthorizationAsync();

 17:     }

 18: }

 19:  

 20: async private void AuthorizeAdditionalRecords()

 21: {

 22:     await myApp.AuthorizeAdditionalRecordsAsync();

 23: }

 24:  

 25: async private Task<bool> IsAuthorizedOnServer()

 26: {

 27:      return await Task.Run(() => IsAuthorizedOnServerImpl());

 28: }

 29:  

 30: private bool IsAuthorizedOnServerImpl()

 31: {

 32:     IAsyncOperation<bool> b = myApp.IsAuthorizedOnServerAsync();

 33:     return b.GetResults();

 34: }

 35:  

 36: private Record GetCurrentRecord()

 37: {

 38:     return (myApp.UserInfo.AuthorizedRecords[0] as HealthVault.Foundation.Types.Record);

 39: }

 40:  

 41: LocalRecordStore GetCurrentRecordStore()

 42: {

 43:     return myApp.LocalVault.RecordStores.GetStoreForRecord(GetCurrentRecord() as HealthVault.Foundation.IRecord);

 44: }

Summary

The HealthVault Library for Windows 8 is a great new way to build Windows Runtime healthcare applications and take advantage of Windows Store marketing and distribution benefits.   The library leverages the Software on Device Authentication (SODA) model for HealthVault connectivity.   We’ve provided “getting-started” samples using both WinJS and XAML/C#.   The library includes source files that are both instructive and extensible.  Enjoy!

HealthVault + Your Client Applications

The following image illustrates that HealthVault Platform Services are exposed via a number of feature-areas.   Some of these features are unique for a web-service in that they encapsulate workflow involving interaction with real people.  If our web-service involved only content browsing, selection, and consumption, then it would be much more recognizable relative to common web-service abstractions.   Consequently, a first-step conceptually is recognition that you may be dealing with uncommon terminology and unfamiliar extensibility models.   Let’s explore this illustration further.

Choose Your Data-Types

Refer to the lighter-blue graphic in the middle of the illustration directly above.   Though not comprehensive, this feature-list is key to understanding solution integration options.   For example, it’s readily apparent that the platform exposes a data-access API and that most operations utilize a PersonID and a RecordID parameter to uniquely target a HealthVault record.  Also, note the top-most green text-block to the right under the heading “Your Client App(s)”.   As a solution designer, a first decision is simply to identify what operations (e.g. create, read, update, delete) are required upon which data-types hosted within a HealthVault record.  Do you need to know what data-types are available?   Browse over to developer.healthvault.com.   Notice the link therein to the Health Types Schema Browser.  

Special considerations for data-types:

• If you are using one of our SDK’s to build your solution, then you can use predefined library classes encapsulating our data-types.   With the .NET SDK, data-type classes are referenced from the Microsoft.Health.ItemTypes.dll assembly file.   Using these classes trivializes creating data-type object instances, object serialization, and transferring data to/from HealthVault.  Our new Win8 library includes a modernization of these class abstraction specify useful within the Windows Runtime execution environment.
• If you are not able to use an SDK within your solution, then you’ll need to deal with data-types formatted as XML or JSON.   This is often the case if your solution runs in an execution sand-box such as Silver Light, as client-side script running within a browser, or on an embedded device.   You may need to “roll-your-own” data-handling classes, copy them from SDK source files, or perhaps auto-generate classes from schema using a tool like XSD.exe.   The amount of development involved depends upon the number and complexity of data-types you’ll be using.
• Each HealthVault integrated application is custom-configured to access specific data-types.  You utilize the HealthVault Application Configuration Center to define data-access rules for your application along with corresponding specified data-types.   HealthVault uses this configuration information to limit your application to as-specified and user-authorized fields within HealthVault records.
• Spend some time thinking thru data-centric scenarios.   For example, typical clinical-trial scenarios require that data-measurements can’t be changed.  In that case, use the HealthVault “immutable” data-type attribute.  
• Consider using the Care Plan data-type or the Continuity of Care document type if your solution will be providing summary information to patients and especially if that information is important for sharing with other providers.
• Will you be rendering the data to a UI, perhaps a browser?   Consider utilizing the transforms provided with HealthVault platform services to ease your development burden.

Choose Your Connectivity Model

HealthVault exposes a rich set of client application connectivity options.   Why do we need many options?   Recall that your application will be participating in one or more workflow activities involving real people who may or may not be using your application interactively when HealthVault platform interaction occurs.   This is an important design-to point best described by scenario example.  Note that many HealthVault solutions utilize more than one connectivity model depending upon aspects of the overall solution architecture.   Again, developers utilize the HealthVault Application Configuration Center to define their application connectivity requirements that correspond directly to connectivity model decisions.

The Software on Device Authentication (SODA) connectivity model applies when you are writing an application that will most likely run with user-interactivity on a personal computer.   A SODA application typically accesses only a single HealthVault record at once.   This connectivity model was conceived in order to simplify management of secure access to the HealthVault platform from widely distributed client-application installations.   Platform interactivity occurs securely within a shared-key encrypted session.   This avoids the complexity of managing a Public Key Infrastructure as certificate exchanges are not required.   Of course, the various HealthVault SDK’s encapsulate the SODA model functionality and most client applications thus inherently benefit without further development beyond invoking the connection methods.

Online connectivity applies to web-page applications (e.g. Patient Portals) wherein HealthVault data-access occurs within a user-interactive browser session.   Typically, user authentication initiates secure site access along with corresponding HealthVault application access.   As most Online applications are deployed within data-centers, certificate based security is much more viable.   Hence, Online applications are configured to use a private-key certificate in which the corresponding public-key has been previously shared with the HealthVault platform using the HealthVault Application Configuration Center.  When using the HealthVault SDK, developers may derive their web-pages from HealthVault base classes that encapsulate Online application functionality.

Offline connectivity is appropriate when your solution requires access to HealthVault records anytime and without user interactivity.   A one-time Patient Connect workflow process (described further below) is required of Offline applications.   Thereafter, your Offline application may simply invoke record access as needed.   This access occurs indefinitely or until the access authorization is explicitly removed; either by the account owner or by the Offline application itself.  Offline application authentication is also certificate based with corresponding Offline data-access rules defined using the HealthVault Application Configuration Center.  When using the HealthVault SDK, developers may leverage the OfflineWebApplicationConnection class to initiate an Offline connection.

Direct connectivity refers to a secure messaging (i.e. secure email) HealthVault platform facility.  The Direct Project served as the genesis of loosely-connected consortium providing secure data-transfer for healthcare providers and their patients.   Each HealthVault consumer receives a free secure email inbox (e.g. myname@direct.healthvault.com).   Solution providers may simply integrate with a secure email server gateway in order to exchange information with HealthVault account owners.   What if you don’t know whether or not a patient has a HealthVault account?   No worries, just send your message to a special HealthVault Direct address (i.e. newuser@direct.healthvault.com) and specify the patients insecure email address in the subject line (e.g. myname@outlook.com) and HealthVault will enable that patient to both create an account and receive your message.   You may also attach standard healthcare documents (e.g. Continuity of Care Documents) and HealthVault will import the information into the appropriate Health Information fields of the patient’s HealthVault record.

Special considerations for connectivity models include:

• If you anticipate both a web-portal usage scenario as well as a back-end clinical system usage scenario, then you’ll need a combination of both Online and Offline connectivity.  
• It’s possible to have aspects of all connectivity models within a sophisticated distributed solution scenario.   You may consider utilizing a Master-Child ID HealthVault Application configuration in that case.   Otherwise, you’ll either have a single Application ID with multiple access-rule definitions or a number of Application ID’s with individual access-rule definitions.
• Direct connectivity requires nothing more than an exchange of Trust between your organization and HealthVault operations.   You may wish to join the Automated Blue Button Initiative and participate in Trust Bundles wherein multiple business entities exchange Trust collaboratively as groups.
• Direct connectivity is a great way to accomplish Meaningful Use certification criteria.   Leverage HealthVault to achieve patient View, Download, and Transmit (VDT) objectives and subsequently request a report of completed VDT activities.

Choose Your HealthVault Features

It’s somewhat easy to confuse connectivity models with other platform features because there are close relationships between them.   As mentioned, an Offline application will typically utilize a workflow named Patient Connect to gain authorized access to a HealthVault record.   Hence, it’s common to refer to Offline connectivity and Patient Connect synonymously.   However, it’s preferable to separate these as Patient Connect is more a type of workflow than a connectivity model.   We won’t explore many HealthVault platform features in this section, but rather discuss a few that become important for HealthVault solution designers.

A Patient Connect workflow is typically used within a solution that requires access to HealthVault records without a user-interactive session.   Patient Connect is often combined with Offline connectivity (discussed above).   The classic use-case is one of new patient registration.  In a clinical setting, you want to both establish a patient record within your back-end clinical systems as well as establish access to the new patient’s HealthVault record.  Your application initiates Patient Connect by sending a request to HealthVault including a local patient ID and a secret question/answer known by the patient.  HealthVault responds with an access token along with a welcome URL.   You provide this information to your new patient (e.g. either via email or via a kiosk).   When the patient browses to the URL, HealthVault validates the access token and guides the patient through account access/creation and authorization of your Offline application.   Once this workflow is completed, your application may query HealthVault for a list of authorized accounts and associate those with entries within your patient database.   You subsequently interact with HealthVault programmatically using the patient HealthVault PersonID and RecordID.

DOPU, meaning Drop-Off and Pick-Up, is a workflow in which your application sends information to HealthVault but with no direct HealthVault record access.   Like Patient Connect, you initiate DOPU by sending a request to HealthVault including attached healthcare information.  You also provide your email address, the patient’s email address, text representing an email to the patient, and a secret question/answer know by the patient.   HealthVault stores this information, returns a package ID, and subsequently sends your email message to the specified recipient.    The patient will receive instructions via email for on how to retrieve the information securely.   Any attached information recognized as HealthVault data-types are optionally imported into the recipient's HealthVault record.   This feature enables a very loosely-coupled patient-provider information exchange.

I’ll mention support for Devices as a platform feature as well.   Many healthcare devices are listed within the HealthVault Device Directory.   Some of these devices are very capable providing directly integrated HealthVault connectivity via Wi-Fi or mobile networks.   Others leverage companion personal computer applications, importing data via USB for example.  Alternatively, devices vendors may leverage the HealthVault Connection Center application and USB connectivity to transfer data to HealthVault records.  Interestingly, the HealthVault Connection Center application also provides image file uploading functionality (e.g. DICOM images).

Direct Messaging is also a workflow-oriented platform feature (in addition to a connectivity model).  What could be more intuitive than sending an email with attachments from your clinical solution?   Currently, HealthVault users will need to enable the integrated HealthVault Message Center in order to utilize their inbox and subsequently transmit information to providers.  

Special considerations for HealthVault features include:

• Your solution’s patient and patient-record interactions will determine your choice of platform feature-area integration.   Consider the workflows involved and design accordingly.
• Perhaps you want to utilize more than one workflow feature area from within the same solution.   Consider implementing a central service from which multiple subsystems may share a common HealthVault connection.
• A usage scenario options matrix is published here.

Choose Your Solution Platform

We probably already have an SDK or code-library for your target solution platform.   Again, an SDK is not strictly required for HealthVault solution integration.   But, if you use one, you won’t have to write a lot of protocol handling, security constructs, and data-type parsing and serialization code.    Our SDK list is here along with a number of corresponding samples.  

Special considerations for solution platforms include:

• Market reach.   Are you developing for mobile?  You will likely need to consider designing for code-portability which may drive your solution design to a web-service model with as much “common-code” on the client device as is possible.  
• Enterprise or Consumer?  Consumer applications typically correspond in a one-to-one manner.   That is, one application user to one HealthVault record.   Enterprise applications, however, may exhibit a many-user to many-record usage model.   This becomes very important as you imagine who your target users may be.   A physician or nurse using a tablet device may wish to scroll a list of patient records, select one or more, and exchange information with the selected person or group.   Hence, SODA connectivity running on a tablet platform may be appropriate for Consumer while the Enterprise scenario requires more design decisions and corresponding system integration considerations.
• An interesting new platform option is the Windows Runtime introduced with Windows 8.   Windows Runtime applications are distributed via the Windows Store (an Enterprise-scoped distribution option exists as well).  A first-party HealthVault Windows Store application is available to consumers for free.  In fact, you may leverage the same code library as our Windows Store app to build your Windows Store application.

HealthVault + Your Web Service + Your Client Apps

You may require a solution architecture in which multiple client applications utilize the same HealthVault subscription.   The following image illustrates this model.  This design would be ideal for an enterprise clinical system servicing multiple departments with a variety of client-app types.  Let’s walk-thru the illustration in more detail.

In the middle of the image is a “cloud provider” hosted “HealthVault Proxy Service”.   This service encapsulates all connectivity with the HealthVault Platform and is configured as an Offline application from a HealthVault perspective.  It serves primarily as a stateless router of HealthVault access requests from any number of Mobile, Enterprise, or Device applications (illustrated on the lower-right of the image).   Ideally, this Proxy Service would accomplish several functional requirements for the client-app community including:

• Serve as a HealthVault interface for an Enterprise domain enabling both a departmental system deployment model as well as an Enterprise tablet device deployment model.
• Centralize a write-once, deploy-once, HealthVault connectivity and feature integration solution.   The proxy service is the only subsystem component with the need to understand HealthVault connectivity and HealthVault feature API’s.   All client-app types need only understand how to integrate with the proxy-service itself (more on this momentarily).
• Expose a subset of HealthVault features including Data-Access, Patient Connect, DOPU, and as a Direct Gateway.   The SODA connectivity model wouldn’t make sense within the proxy-service as it is intended instead as a direct-to-HealthVault connectivity model.  The Online connectivity model might be combined with the Proxy Service if an interactive Patient-Portal experience is required.   In that case, the proxy service would effectively host both a web-app as well as a web-service with corresponding Online and Offline configuration rules.
• HealthVault currently doesn’t expose services directly as REST, SOAP, or OData.   Hence, the proxy-service provides an opportunity to implement these standards on behalf of HealthVault.   Thereby, increasing the richness of client usage scenarios.
• HealthVault is a very XML friendly platform.   A proxy service may provide a translation function wherein XML content is transformed to whatever client data-model desired; JSON, for example.
• Serve as a central-point for organizational analytics, profiling, or security management.

In fact, this is the solution architecture that our Dynamics CRM partner’s are utilizing to implement Population Care Management solutions.   The use of a proxy service is actually necessitated by the Dynamics CRM solution extensibility sand-box.   The HealthVault SDK assemblies are restricted from use in the solution sand-box for a number of reasons including the use of system cryptographic methods.   However, code running within the sand-box is completely capable of call-outs to web-services.  It’s important to note that the proxy service need not be hosted in the cloud at all.   In fact, it could reside on the same server or within the same domain data-center as the Enterprise client systems.

As you may have guessed, this article is a segway to subsequent articles focused on exactly how to implement a HealthVault “bridge” solution architecture.   A number of motivations culminate in this exercise.   One is that modern application design is largely focused on cloud-services composition instead of on isolated application design.  Imagine a clinical office utilizing Office365, Dynamics Online, Windows Azure, Lync or Skype, and HealthVault as platform technologies for their healthcare informatics needs.   With a bit of customization, these subscription-based services would fulfill a significant amount of business process technology requirements.  

I’ve recently joined the Microsoft HealthVault team in a Solutions Architect role with a focus on assisting our partners and customers as they build great HealthVault integrated solutions.              I’ve always enjoyed this type of role and look forward to the learning experiences that HealthVault will bring into my life.   One of the first such experiences is collaboration with the “Hacking Health” initiative underway now in Canada.   The Cajun Code-Fest is a similar event happening in the USA.

In this post, I’ll seek to share a few tips for developers in the “Getting Started with HealthVault” phase of their solution development.   I’m using my personal blog for this information (instead of the team blog) as I’m also ramping-up on the platform technology and corresponding use-case scenarios.   Perhaps my perspective will be valuable to others.

The HealthVault platform provides several application connectivity models supporting a variety of workflow experiences.   For example, a typical on-premises healthcare clinical system may require a semi-automated HealthVault workflow involving direct patient interactions.   Alternatively, an analytical application may require minimal user-interactions and rather a fully-automated offline HealthVault interaction workflow.   In practice, most full-featured HealthVault solutions implement a combination of workflow scenarios depending upon a number of functional requirements including consumer-interaction, security model, deployment environment, data-management, and device integration. 

From a platform perspective, HealthVault supports an ecosystem of applications and devices.   The HealthVault platform is well-documented with open support for practically any web-based client solution.  However, for integrity and security purposes, programmatic access to real user accounts is controlled.  In order to access the production HealthVault service, client applications must be authorized to access not only the production service itself but also individual consumer accounts hosted therein.   The Consumer is truly the owner of their Health information.

In the USA, initiatives such as Meaningful Use and the Automated Blue Button Initiative are driving innovation in healthcare information systems technology.   A key objective is the simple and secure exchange of healthcare information between providers and patients.   The Direct Project has produced a reference implementation for trust-based encrypted message exchange that is quickly becoming the standard.   HealthVault users receive a free Direct Address and may utilize the HealthVault Message Center to participate in secure Direct communications.

Online services are also generating a great deal of innovative thinking.   The ability to compose a solution utilizing a number of online services not only increases the speed of implementation but also the richness of end-user experiences.  For example, clinical systems are really just customized Customer Relationship Management (CRM) systems.  Why not compose these systems utilizing Dynamics CRM Online and HealthVault?   Throw in Office365, Skype, Lync, and Windows Azure hosted services and you have a very powerful platform for quickly automating healthcare businesses.

Getting Started

• A HealthVault Application Development Primer using ASP.NET MVC – The first few paragraphs of this article apply to development of any HealthVault Application.   
• Determine How Your Application and Users Will Connect to HealthVault – This article (and links therein) will enable you to more quickly decide upon a solution architecture and corresponding development tasks.
• Get Your Development Tools and Find Documentation – The MSDN HealthVault Developer Center is the central hub for HealthVault Application Developers.   Use the Forums tab to participate in community Q&A.   See the various SDK’s and sample-code links.

Noteworthy Samples

• Sean’s HealthVault Toys – Sean Nolan leads the HealthVault team and regularly contributes invaluable insights via the Family Health Guy blog.  He has recently posted a few interactive samples using an Azure WebSite.   Experiment with these to gain familiarity with various HealthVault Application models.
• The HealthVault SDK Samples – When you download and install the HealthVault .NET SDK, you will find several samples hidden within the installation folder.  
• Codeplex Projects, Java, MVC, and Win8 SDKs – Several “sample” projects hosted on Codeplex.com also include class libraries that are sneaking-out the door as SDKs in their own right.   You can re-use these class libraries as reference assemblies (you get the source too) within your applications.   The Java library provides a thin abstraction layer over the raw XML over HTTP HealthVault Platform API and is a good way to build system-independent solutions.   The Win8 library enables development of new Windows Store style HealthVault Applications.
• Oldies but Goodies – Eric wrote a number of how-to type topical articles several years ago.   They remain very relevant resources.

And, of course, contact us if you have a great idea for a HealthVault Application and need a bit of technical assistance getting it going!

“To solve a problem, create abstractions.   To attain efficiency, remove abstractions.”

Such is the case with I/O in the Cloud (i.e. all Clouds).   Efficiency requires designing for the underlying platform with specific considerations for storage account quotas, network constraints, and partitioning strategies across available resources.   Regarding storage, the article published here is a good place to start with understanding capabilities and constraints.  

Regardless of final solution design, it is often advantageous to initially simply get a prototype solution deployed with minimal configuration and code changes.   Such is the promise of Infrastructure as a Service (IaaS).   Especially with Windows HPC Server solutions, addition of an SMB File Server to your Windows Azure service enables an easy Cloud integration experience.   If your objective is to create an evaluation prototype, the scenario described herein may either completely serve your file I/O requirements or just provide an operational envelope for testing purposes.   For illustration purposes, I’ll keep the solution scenario as simple as possible.   However, there are several deployment configuration options that would dramatically enhance your storage I/O performance and still not require modifications to your existing solution.   I hope to document these advanced configuration options within subsequent posts.

First, a look at what we are to achieve herein…

1. Configure a file server (SMB protocol, port 445) with a persistent name (e.g. “myfileserver.cloudapp.net”).
2. Create a file share (e.g. “\\myfileserver\myshare”) accessible from other Windows Azure worker-role VMs (e.g. compute-nodes) with user authentication (we will use workstation-mode, NTLM, and not domain authentication).  
3. Ensure that the file share is backed by blob storage.
4. Execute a compute job wherein the working directory path resolves to a UNC path (e.g. “\\myfileserver\myshare”).

Note the following non-objectives (perhaps to be documented in subsequent posts or even superseded by future platform features).

1. Load-balance across multiple SMB file servers.
2. Optimize I/O (via partitioning) across multiple blob storage accounts.
3. Distribute the file structure namespace across multiple file shares (e.g. using mklink from the client perspective).
4. Leverage mountable read-only VHD files in order to gain wider distribution and staging of read-only data.
5. Utilize alternative file distribution utilities (e.g. ClusterCopyConsole) to stage job input data.
6. Address on-premises to file server VM connectivity (e.g. using Windows Azure Connect or Virtual Network).
7. Securely configure the service and file server VM instance.

Effectively, for illustration purposes, our Virtual Machine hosted file server instance will be a single point of I/O for any number of compute-node server instances. 

Configure the Virtual Machine File Server

Utilize the following procedure to configure a Windows Azure Virtual Machine (VM) instance for use as a File Server.

1. Create the File Server VM instance (e.g. “MyFileServer.cloudapp.net”) using the Windows Azure portal.   See reference instructions here.  
2. Attach and format a blob-storage hosted data-disk to the VM.  
3. Once the File Server instance is running, configure a limited privilege user-account (e.g. “MyUser”).   Note that this service account is a primary security mechanism for the server instance.  Any other VM within the data-center could access your server or cause denial of service.   More advanced server security configuration is beyond the scope of this article.
4. Using the Server Manager Console, enable the File Server Role.
5. Create a File Share folder (e.g. “MyShare”) on the attached data-disk and enable read/write access for the MyUser account.
6. Add two endpoints to the VM for both TCP port 445 and UDP port 445.   This enables the server (at the service deployment level) to communicate SMB protocol with worker-roles hosted in the same Windows Azure data-center.   The SMB protocol is not currently routed externally from the data-center.

Your File Server configuration should appear as follows from the management portal.

With corresponding service end-points configured as illustrated.

And the file share configuration similar to the following image.

Configure the Compute Node Templates

You may wish to familiarize yourself with the “burst to azure” capability of Windows HPC Server 2008 R2.   Also, a previous article discusses how to utilize start-up scripts in connection with “Windows Azure Node Templates”.   You can utilize a start-up script to configure your worker-role compute-nodes so that they can “see” \\MyFileServer\MyShare.   Let’s illustrate how that’s accomplished…

The following image illustrates a list of Compute Node Templates within the HPC Server Cluster Manager console.

Node Templates enable partitioning of node-groups across multiple Windows Azure service deployments.   Each service may contain a large number of compute nodes all managed from a single cluster head-node.   Refer to the links immediately above for detailed information on how to configure a cluster to utilize Windows Azure worker role VMs as compute nodes.   For our immediate purpose, we only need to modify the startup script (i.e. nodeprep.cmd) associated with each node template.

Add the following command line to the nodeprep.cmd file.   Obtain your myfileserver.cloudapp.net VIP address from the Windows Azure management portal (e.g.  nslookup myfileserver.cloudapp.net).   The echo command appends an entry to the etc\hosts file on each local compute node and thus enables subsequent UNC host name resolutions (e.g. \\myfileserver).  

Configure Your Job to Use the File Server and Share

When you submit jobs using the HPC Server Scheduler those jobs are run within a user-logon context.   With on-premises compute-nodes, the scheduler utilizes domain account credentials.   When the target compute-node group for your job is the AzureNodes group, then a temporary local user logon is created for your job.   You can verify this by submitting a job using the “whoami” command and viewing the resultant output.

Consequently, your job runs within a context in which any secure external resources (e.g. file shares) requires authenticated user access.   You can achieve this by adding a Node Preparation Task to your job as illustrated.   This task runs once on each node and precedes execution of any other task within your job.  

Subsequent tasks, within your job context, will have access to the file server resources.   For example, you can configure the Working Directory to utilize the file share for task input or output.

References

Learn about Windows Azure Virtual Machines.

See the course information with schedules here.   Learn more about C++ AMP via the MSDN Parallel Programming in Native Code blog.

Download the script files associated with this topic from here.  Refer to the authoritative documentation for this topic here.

This feature functionality applies when utilizing Windows HPC Server to deploy compute nodes onto Windows Azure using the Cluster Configuration Manager from the head-node.

With Service Pack 3 (SP3) of Windows HPC Server 2008 R2 (November 2011 and later), Microsoft added the ability to specify integration with Windows Azure via Node Templates.   When adding a new Node Template, you may optionally specify a node Startup Script as illustrated.

The startup script (e.g. nodeprep.cmd), is called during the Virtual Machine (VM) startup sequence upon deployment activation within a Windows Azure service.   The script is executed only once and within system context on each VM instance within your deployment configuration as new nodes are added to the compute cluster.

Proper configuration of the startup script sequence involves not only specification of the script name within the template editor, but also addition of the nodeprep “package” to the blob storage account also associated with the Node Template.   This package upload activity must be accomplished prior to adding any new nodes to the cluster.   Hence, the cluster admin must execute an “InstallNodePrep.bat” type script from the head-node prior to adding new nodes within the context of the new Node Template.

Setup your scripts and package files on the head-node as illustrated below.  

• Create a two-level folder structure containing your scripts and startup package files.  
• File “c:\MyHeadNode\InstallNodePrep.bat” is executed from cmd.exe on your head-node.   This script creates two .zip file “packages” that will be uploaded to the Blob storage account associated with your Node Template.   Note the command line syntax within the cmd.exe window below wherein the corresponding node template is specified using the “-t” argument.
• The first package is a zip of the file “c:\MyHeadNode\nodeprep\nodeprep.cmd”.   Note that this file corresponds to the “nodeprep.cmd” script that you’ve specified within your Node Template configuration illustrated above. 
• The second package is a zip of the folder “c:\MyHeadNode\nodeprep”.   

Now, when new Azure Node instances are added to your cluster, the “hpc sync” node configuration sequence will download these two packages automatically to the node-local “%CCP_PACKAGE_ROOT%” path.

Your “nodeprep.cmd” startup script will be unzip’ed and executed.   Note, a good practice is to ensure that any .msi installer executions occur synchronously using the “start /wait” command syntax (see the sample files from the download link above).   Concurrent installations are problematic and could create a difficult to diagnose race condition.  

A very useful startup script output log is produced at “e:\approot\HpcStartupCommand.log” on each VM instance.   You will want to ensure that your startup script contributes stdout and stderr results to the log file as illustrated within the example files (refer to the download link above).

A new optional extension of the Windows Azure SDK, the Windows Azure HPC Scheduler SDK enables developers to create a new class of Windows Azure solutions.   The SDK includes a job scheduling service along with support for popular distributed parallel computing runtimes traditionally associated with High Performance Computing workloads.  

Get started developing solutions…

•    Update to the latest Windows Azure SDK for Visual Studio 2010.
•    Download the Windows Azure HPC Scheduler SDK installer.
•    Get the Code Samples project files from MSDN Code Gallery.
•    Review the Getting Started Guide for installation and sample walk-through information.
•    Watch the introductory video posted at Microsoft Showcase.
•    View the BUILD Conference session on HPC for Windows Azure.

Obtain the LINQ to HPC beta2 bits at Microsoft Connect (search for the downloads section).   A prerequisite installation is the now released Service Pack 2 for Windows HPC Server.