Introduction to HealthVault Development #2: Hello World
In this post, we’ll create an account on the HealthVault system, open up the HelloWorld sample application, and verify that it works on our system.
There are two live HealthVault platforms.
- A developer platform at https://www.healthvault-ppe.com. This platform is intended to store test data rather than real consumer data, and is the one that should be used to develop an application. When an application is all done, there is a process to deploy (aka “go live”) with the application, and it will then be able to run against…
- The consumer platform (which we sometimes confusingly refer to as the “live” platform) lives at https://www.healthvault.com.
All of our tutorial examples will be talking to the developer platform.
Examine the source code
Start Visual Studio, then open the HelloWorld application at C:\Program Files\Microsoft HealthVault\SDK\DotNet\WebSamples\HelloWorld\website.
In the solution explorer, expand Default.aspx and double-click on default.aspx.cs. This shows the code for the main page. Notice that the page class is derived from HealthServicePage – that class handles the initial communication handshake between your application and HealthVault, sending the user to the right page to log into the system, etc. That all happens behind the scenes before the Page_Load handler is called.
Open web.config, and browse through it. If you find the following line:
<sessionState mode="InProc" cookieless="true"/>
change it to:
<sessionState mode="InProc"/>
ApplicationId specifies a GUID that uniquely identifies a specific application to the platform. ShellUrl and HealthServiceUrl define which instance of the platform to talk to.
There’s also a proxy setting at the end of the file – if you are running on a network with a proxy server, you will need to change this so that the application can get outside the firewall.
Run the application
Hit <F5> to start the program in the debugger.
That will build the solution, start up the asp.net development web server, and start debugging default.aspx. A browser session will open up, and you’ll find yourself on the login page for the HelloWorld application.
All authentication and authorization in HealthVault applications is performed by a set of web pages that live on the HealthVault server. These web pages are collectively known as the “HealthVault Shell”.
When you ran the application, the startup code in HelloWorld realized that it didn’t know who the current user was, and redirected off to the appropriate HealthVault shell page.
At this point, you will need to create a test HealthVault account. For authentication, you can either use Windows live or Live ID. If you need to create an authentication account – and for test purposes it’s probably a good idea not to use an account you use for something else – go do that now.
Once you’ve created that account, enter the credentials on the login screen. You will be prompted to create a HealthVault account, and then (when you click continue), will be prompted to authorize the Hello World application to access the information in your record.
Before an application can run against the HealthVault platform, it must be configured on that platform. That configuration stores some descriptive information about the application (name, etc.), and also the precise data type access that the application is required. For example, an application that tracks a person’s weight might need to be able to store and retrieve weight measurements, but only read height measurements.
The authorization page that you are currently looking at details this information for the user, who can then make a decision about whether to grant the application that access. This page is atypical because the Hello World application asks for access to all types to make things more convenient, but real applications will only specify the subset of access required.
Choose “approve and continue”, and you will be redirected back to a page on your system.
This will be a page that says “Server error in ‘/website’ application. If you dig a little more, in the exception text you will find:
SecurityException: The specified certificate, CN=WildcatApp-05a059c9-c309-46af-9b86-b06d42510550, could not be found in the LocalMachine certificate store,or the certificate does not have a private key.]
Every time an application runs, it needs to prove its identity to the platform through a cryptographic signature. To do this, it needs a private key on the machine where the application is running. It will use that key to sign the data, and the platform will then verify the signature using the public key that was registered as part of the application configuration process.
The Hello World application is already configured on developer platform, so we just need to register it on the client.
Register the certificate
To do this, we’ll need to get the certificate into the local machine’s certificate store. Go to the location on disk where HelloWorld lives, go to the cert directory, and you’ll find a .pfx file, which contains both the public and private keys.
Start up the certificate manager using the following shortcut:
C:\Program Files\Microsoft HealthVault\SDK\Tools\ComputerCertificates.msc
Right click on certificates, choose “All tasks”, then “Import”. Specify the .pfx file at:
C:\Program Files\Microsoft HealthVault\SDK\DotNet\WebSamples\HelloWorld\cert\HelloWorld-SDK_ID-05a059c9-c309-46af-9b86-b06d42510550.pfx
And then hit next repeatedly and finish. That will finish the import of the certificate.
If you use a proxy to get to the internet and there is a password associated with it, you may need to modify the config file for it. In the sdk/tools directory, find ApplicationManager.exe.config, and add the following:
<
system.net>
<defaultProxy enabled="true" useDefaultCredentials="true">
<proxy usesystemdefault="True"/>
</defaultProxy>
</system.net>
At this point, you should be able to re-run the application (or just hit F5 in the browser), and the HelloWorld application should then work. Note that the certificate is only accessible for the user who imported the certificate – access for other accounts (such as IIS) can be granted through the winhttpcertcfg utility (also in the tools directory), or through a utility that we’ll discuss in the future.
Next time, we’ll start on our application itself.
Introduction to HealthVault Development #3: Configuring our Application