Now that we have HelloWorld set up and running, we want to move on to developing the real application. Well start with a shell application and add to it as we go.
Download the WeightTracker shell, and open the project in Visual Studio. Register the certificate using the same process you used in the previous tutorial. Add a reference to the following HealthVault assembiles in c:\program files\microsoft healthvault\sdk\dotnet\assemblies:
- Microsoft.Health.dll
- Microsoft.Health.ItemTypes.dll
- Microsoft.Health.Web.dll
Run it, and you will be taken to the HealthVault authorization page for the application. Note that its specific to this application it has its own name, logo, description, and set of requested types.
It is possible to continue in the tutorial using the configuration that comes with WeightTracker, but since configuration is an important part of HealthVault applications, I recommend that you create your own configuration. Thats what well be doing in this part of the tutorial.
Creating a new certificate
When we were working with Hello World, we had to register the application certificate on our system, and we did that through the MMC utility.
This time, we need to create a certificate, register it on our system, then register it with the HealthVault platform. Its possible to do the work by hand, but were going to use a utility that ships with the SDK to do this.
Go to Start-> All Programs > Microsoft HealthVault > SDK > HealthVault Application Manager. If you are running Vista, youll need to run as administrator.
You should see the initial application manager screen, and it should list the HelloWorld Sample certificate that you registered in the last part of the tutorial, and it may list other sample applications you have used.
The Application Name isnt stored as part of the certificate it is only stored by the ApplicationManager application. The application knows the names of some of the sample applications, which is why they show up.
If you check the Show Unnamed applications checkbox, you will see the WeightTracker certificate pop up. You can verify which one it is by matching the application ID (defined in web.config) with the certificate name.
We will create a new certificate by clicking the appropriately-named button. This will bring up a dialog that asks you to enter a name for the application.
I chose to call mine Weight Tracker Tutorial, since thats the name of the application well be writing. You can use the same name or something else, like Pizza Joes spicy vegetarian.
The main list should refresh and you should see the new certificate listed. When we generated a certificate, it was created with both a private and a public key, and theyre both in the certificate store. The public key is something that well send off to the HealthVault platform so it can use to verify items signed with the private key. Public keys are typically passed around as .cer files.
The private key isnt something that we should be emailing around, because anybody who has it can pretend to be us. Application manager does allow you to export both the private and public keys in a .pfx file, in case you want to run the application on another server.
The wikipedia articles on public key cryptography and digital signatures are good introductions to this area if you would like to know more. There is also the cryptography overview on MSDN.
Registering a certificate with the HealthVault platform
To register a certificate, right-click on it and choose Upload certificate.
This will package the certificates public key and the application name (if present) into a request, and send it off to the HealthVault application configuration center. It will then launch your browser to the app config center.
The app config center is a HealthVault application, and access to the configuration of a specific application is limited to a single HealthVault account. When you authenticate, you should use an appropriate account that works for what you are doing using a shared account when multiple people need to be able to access and modify an applications configuration.
Once you have authenticated, you will see a list that contains your new application, with the name that you chose, and the generated application id. Click on your application.
You will see the Information page for your application. Here, you set the name, description, and other items that show up on the authorization page, including the logo.
Configuring an applications data access
Well start by configuring the data access that well need to get started.
There are two kinds of access that an application can request. Online access provides access when the user is running your web application, and is what well use in the tutorial. Offline access provides access whenever the application wants access, and is typically used to synchronize information between HealthVault and the application.
Offline access is something users are more careful about granting, especially to groups that they dont trust, so your application should try to use online access whenever possible.
Click on the OnlineAccess tab. To make organization easier, data access is grouped into rules. Choose add rule, to bring up the rule editor.
Here you need to give a name for the rule (which isnt user-visible, so you can name it whatever you want), and a why string, which is the justification that is given to the user on the page where they decide whether to grant access to your application. Good why strings are required before you can go live, and if you put some thought into it at this point, things are much easier later on.
Ill call this rule Weight, because thats what were going to ask for. For the why string, I thought of a few possibilities that we could use:
- Because we need to access your data.
- Because the application needs access to work correctly.
- WeightTracker uses access to your Weight measurements to help you effectively manage your weight.
- All your weight are belong to us.
Which one is best? Please write 500 words explaining why, and have it for me on Monday.
The key here is that the why string is displayed to the user, and it needs to be something that a) the user understands and b) explains the benefit of granting access.
(do we have a good link on writing why strings?)
For permissions, I choose All, because I want to be able to perform all operations on Weight measurements (create/read/update/delete) , and then I choose the Weight Measurement data type from the list, and pick Save. That gives me my first rule.
I add a second rule:
| Rule name: | Height |
| Why string: | Weight Tracker uses your height to help determine whether your weight is appropriate. |
| Permissions: | Read |
| Data types: | Height Measurement |
Note that I only specified Read access, rather than asking for access that I dont need. Your applications access should always be as minimal as possible dont ask for access that you dont need.
You will also need to delete the rule for Personal Image.
Now that weve done that, the platform configuration is complete. All that is left is to configure the application to use the new application ID.
Configuring the application to use a new certificate
To modify the application, we need to update the application id in web.config file.
In application manager, right-click on your new certificate, and choose copy certificate name to clipboard. Switch over to Visual studio, open the web.config file, and look for the ApplicationId entry. You will find:
<add key="ApplicationId" value="f36debe2-c2a3-434a-b822-f8c294fdecf9" />
Thats the one that the application is currently using. On startup, the application finds this string, prepends WildcatApp- to it, and then uses that string to search for a certificate to use.
Duplicate the app id entry, and comment one of them out. Paste in your new application ID for the value in the one that isnt commented out, remove the WildcatApp- part, and save the file.
Heres what I typically do:
<add key="ApplicationId" value="1b8cbb19-a9ed-4ebc-b498-6ae3d0ed44d7" />
<!applications ids
my key
<add key="ApplicationId" value="1b8cbb19-a9ed-4ebc-b498-6ae3d0ed44d7" /> |
original key
<add key="ApplicationId" value="f36debe2-c2a3-434a-b822-f8c294fdecf9" />
-->
At this point, you should be able to run your application, and get the authorization screen that matches the information that you entered in application configuration center.
I like to keep another application ID around (usually the HelloWorld one) so that I can easily switch to it to see if Im running into problems due to my application configuration.
Next Time
Next time, well be writing some code.
