Export (0) Print
Expand All

Getting started with the HealthVault .NET SDK

HealthVault

Microsoft HealthVault is a cloud-based platform designed to put people in control of their health data.

Last updated: July 2012

This topic contains the following sections.

HealthVault helps people collect, store, and share health information with family members and participating healthcare providers. HealthVault connects with a variety of third-party applications and devices to help people manage their fitness, diet, and health data.

HealthVault offers a privacy- and security-enhanced foundation on which a broad ecosystem of solution providers, device manufacturers, and developers build innovative new health and wellness management solutions.

This getting started guide will show you how to create a HealthVault application and connect it to the Microsoft HealthVault Pre-Production Environment (see HealthVault development basics for a link to the environment). More specifically, this guide discusses:

  • The materials included in the HealthVault .NET SDK.

  • The procedure for installing the SDK.

  • The requirements for developing a HealthVault application.

  • The process of creating your application and testing it in the HealthVault PPE.

  • Where you can go to learn more about HealthVault.

For information on connecting your application to the HealthVault production environment and making your application available to HealthVault users, see the Go-live guide.

After you install the SDK, the following items are available:

  • The SDK Reference (Microsoft.Health.chm) containing code interfaces to the HealthVault platform, methods, and types. This information is also available on MSDN for viewing online at http://msdn.microsoft.com/library/hh672196.aspx.

  • The Getting Started guide

  • HealthVault Application Manager

The following items are created in the SDK folder at Program Files\Microsoft HealthVault\SDK:

  • Docs

  • DotNet

  • Source

  • Tools

HealthVault SDK Docs folder

The following items are available in the Docs folder:

  • This Getting Started guide

  • The Microsoft.Health.chm file containing the managed code interfaces to the HealthVault platform, methods, and types

  • The HealthVault SDK End User License Agreement (EULA)

  • The Release Notes for this version of the HealthVault SDK

HealthVault SDK DotNet folder

The DotNet folder contains several sample applications. Each sample application includes:

  • Visual Studio project file and solution file

  • Some sample applications

HealthVault SDK Source folder

The Source folder contains the source code for the following HealthVault .NET assemblies:

  • Microsoft.Health.dll

  • Microsoft.Health.Web.dll

  • Microsoft.Health.ItemTypes.dll

  • Microsoft.Health.ItemTypes.Old.dll

HealthVault SDK Tools folder

In the Tools folder, you can find:

  • ApplicationManager.exe: a utility for creating and managing HealthVault application certificates and creating new HealthVault web applications

  • UserGuide.htm: documentation for the Application Manager

  • ComputerCertificates.msc: a Microsoft Management Console script that helps you import and export certificates to/from the correct certificate store

  • WinHttpCertCfg.exe: a utility that can be used to allow the NetworkService account to access your application's private key

Required software

The instructions in this getting started guide assume that you have the following software:

  • The HealthVault .NET SDK

  • An appropriate development environment

  • A compatible Web browser

HealthVault .NET SDK

This guide uses the following material from the SDK:

  • The HelloWorld sample application source code.

  • The HelloWorld sample application certificate.

Development environment

  • Visual Studio 2008 or 2010

  • .NET Framework 2.0

  • Windows 7 or Windows Vista

  • IIS Web Server for developing web applications: The HealthVault application environment is fully compatible with the Development Web Server that is included with Visual Studio. However, the Development Web Server does not support more than one Web user connection at a time. To test your application with multiple users, you will need to host your application with Internet Information Server (IIS).

  • A supported internet browser: HealthVault works with all standard browsers: Internet Explorer, Firefox, Safari, Opera, and Chrome. We recommend that you use the latest version of your preferred browser. HealthVault requires that you enable JavaScript and cookies.

You can download the Microsoft HealthVault .NET SDK installer from the Downloads page of the MSDN HealthVault Developer Center.

The SDK provides two ways to create a new HealthVault web application: automatically with the HealthVault Application Manager, or manually.

This section describes the steps for creating a HealthVault web application using the Application Manager.

  1. Navigate to SDK\Tools.

  2. Run ApplicationManager.

    JJ582794.alert_note(en-us,MSDN.10).gif Note

    In Windows Vista, ApplicationManager.exe requires elevated permissions.

    To run with elevated permissions, right-click the application and select Run As Administrator.

    To permanently set the application to run with elevated permissions, right-click the application, select Properties, select the Compatibility tab, and select Run this program as an administrator, and then click OK.

  3. Click Create New.

  4. Enter the name of the application.

  5. [Optional] Enter the name of the Visual Studio project. If no project name is specified, the application name is used by default.

  6. Leave Automatically create Visual Studio website for this Application checked. If this box is not checked, the Application Manager will create a new certificate and register the certificate with the HealthVault web service, but will not create a Visual Studio project.

  7. Select a project type. The default project type is C#. To create a Visual Basic .NET project, select the VB radio button.

  8. Select a location for the application certificate file. If Use local cert file for website is selected, the Application Manager exports the new certificate to a local folder and modifies the Web.Config file to refer to the local certificate. If the box is not selected, Application Manager uploads the certificate to the HealthVault certificate store but does not save it locally. The default setting uses a local certificate.

  9. Enter a location for the project files. The template creates three folders.

    • ProjectLocation\ProjectName

    • ProjectLocation\ProjectName\cert (for the exported certificate files, if any)

    • ProjectLocation\ProjectName\website (for everything else)

    JJ582794.alert_note(en-us,MSDN.10).gif Note

    Before the next step, ensure that your computer is connected to the Internet.

  10. Click Create and Register Application.

    The project files are created, saved, and then opened in Visual Studio. (If you have more than one version of Visual Studio installed, the project files are opened using the most recent version.)

    The HealthVault Application Configuration Center (ACC) is opened in a Web browser. You will be prompted for LiveID or OpenID credentials if you are not already logged in.

  11. In ACC, enter your credentials, read and accept the HealthVault Developer Site terms, and then click Create application.

  12. In Visual Studio, press F5 to build and open the Web application.

    Your application will open in a Web browser and immediately redirect to the HealthVault user shell, and you will be prompted for credentials again.

  13. In the HealthVault user shell, enter your credentials, then allow your application access to a record in your HealthVault account.

    Shell will redirect you to your application.

Welcome to HealthVault!

This section describes the steps for manually creating a HealthVault Web application.

Install a sample application certificate

Your HealthVault application won't run without an application certificate. The HealthVault .NET SDK includes a certificate management utility, HealthVault Application Manager, that is specifically intended to manage application certificates on a development machine.

To install a sample application certificate using the HealthVault Application Manager

  1. Browse to the tools directory in your HealthVault SDK installation path, for example, C:\Program Files\Microsoft HealthVault\SDK\tools, and then start ApplicationManager.exe.

  2. Click Import pfx, and browse to the cert folder of the sample Web application, such as C:\Program Files\Microsoft HealthVault\SDK\DotNet\WebSamples\HelloWorldCertStore\cert.

  3. Select the certificate (pfx) file for the sample application, such as HelloWorld-SDK_ID-05a059c9-c309-46af-9b86-b06d42510550.pfx.

To manually install a sample application certificate on your computer

  1. Browse to the tools directory in your HealthVault SDK installation path, for example, C:\Program Files\Microsoft HealthVault\SDK\tools, and then double-click ComputerCertificates.msc.

    OR

    In Application Manager, click Computer Certificates.

  2. In the Computer Certificates control, expand the Personal folder and select Certificates.

  3. From the Actions menu, hover over All Tasks, and click Import.

  4. On the welcome page of the Certificate Import Wizard, click Next.

  5. On the File to Import page, click Browse and browse to the certificate folder of the sample Web application, for example, C:\Program Files\Microsoft HealthVault\SDK\DotNet\WebSamples\HelloWorldCertStore\cert, and then select the certificate (.pfx file) for the sample application, such as HelloWorld-SDK_ID-05a059c9-c309-46af-9b86-b06d42510550.pfx.

    JJ582794.alert_note(en-us,MSDN.10).gif Note

    The file browser does not show *.pfx files by default. To display the certificate, select Personal Information Exchange (*.pfx, *.p12) in the file type list.

  6. With the .pfx file selected, click Open.

  7. Click Next.

  8. On the Password page, click Next. (A passwordis not required.)

  9. On the Certificate Store page, leave Place all certificates in the following store selected, use the default value of Personal in the Certificate Store field, and click Next.

  10. On the Completing the Certificate Import page, click Finish.

  11. In the Certificate Import Wizard dialog, click OK.

JJ582794.alert_note(en-us,MSDN.10).gif Note

The certificate should now appear in the list in the Computer Certificates window.

Grant access to nework service accounts (IIS only)

This step is required if your Web application is hosted by IIS. It is not usually required if your application is hosted by the Development Web Server that is included with Visual Studio, because the Development Web Server does not use isolated machine accounts.

To grant access using the HealthVault Application Manager

  1. Browse to HealthVault install path\SDK\Tools, and then double-click ApplicationManager.exe.

  2. Right-click the certificate file.

  3. On the context menu, click Grant access to IIS process.

To grant access manually

Before you can run the commands in this section, you need to install winhttpcertcfg.exe on your computer. Winhttpcertcfg.exe is included in the cert subdirectory of each sample in the SDK. You can also install it from the Microsoft Download Center.

The procedure to grant access to a network service account depends on the operating system of your Web server:

Windows Vista or Windows 7

JJ582794.alert_note(en-us,MSDN.10).gif Note

In Windows Vista or Windows 7, you must run the batch file in Administrator mode (which is not the same as being logged in to an Administrator account) in order to grant the necessary Windows accounts access to the application certificate.

To grant the necessary Windows accounts access to the application certificate on Windows Vista using the batch file:

  1. In the sample application's certificate folder (SDK\DotNet\WebSamples\SampleName\cert), right-click GrantCertificateRights_Win2003.bat.

  2. From the context menu, select Run as administrator.

  3. Review the output of the batch file to confirm that the operation succeeded.

On Windows Vista or Windows 7, you can also grant certificate access to the computer (IIS) account manually.

To manually grant the necessary Windows accounts access to the application certificate on Windows Vista using the Microsoft Management Console (MMC):

  1. Right-click the certificate you just loaded into the MMC in the Install a sample application certificate procedure.

  2. From the context menu, hover over All tasks, and click Manage private keys.

  3. In the Permissions dialog, click Add.

  4. In the Select Users, Computers dialog, click Locations.

  5. Select the computer's name, and then in the Object Name field, enter NETWORK SERVICE.

  6. Click OK in all dialog boxes.

Windows XP

To grant the necessary Windows accounts access to the application certificate on Windows XP SP2:

  1. In the sample application's cert folder, run GrantCertificateRightsXP.bat to configure the needed Windows accounts with access to the certificate.

  2. Review the output of the batch file to see whether the operation succeeded or failed.

Windows 2003 Server

To grant the necessary Windows accounts access to the application certificate on Windows 2003 Server:

  1. In the sample application's cert folder (SDK\DotNet\WebSamples\SampleName\cert), run GrantCertificateRights_Win2003.bat to configure the needed Windows accounts with access to the certificate.

  2. Review the output of the batch file to confirm that the operation succeeded.

Open the sample solution file in Visual Studio

The solution file for each sample is located in the sample application's root folder (SDK\DotNet\WebSamples\SampleName\SampleName.sln). Double-click the solution file to open it in Visual Studio.

Start the sample application

To run the sample application:

  1. In Visual Studio, make sure the sample project is selected, and press F5.

    The sample application will start and connect to the HealthVault PPE login server.

  2. Log in to the HealthVault PPE.

  3. Once you have logged in, allow the Hello World application access to one of the records in your test account.

You have created a HealthVault application! The sample applications in the SDK provide good starting points for adding functionality to your application.

Make the application your own

The SDK provides several ways to customize your application beyond the examples provided by the sample code.

Application ID

As you continue to develop your application, you will eventually notice some limits on its behavior. For instance, you cannot change its online description, or modify its data access rights. (It always has full access to all data in your test account in the PPE environment.) That is because, as far as the PPE server is concerned, it is still the sample application whose application certificate you originally used to install it.

To give your application an identity of its own, you will need to create a new Application ID. With a new Application ID, you can:

  • See your own logo and description during sign-in, instead of those belonging to a sample application.

  • Explore Offline Access, Open Query, and Send E-mail functionality.

  • Configure the data access rights of your application.

For more information about creating an Application ID, see Generating an Application ID (http://msdn.microsoft.com/healthvault/bb898878.aspx).

Data types

For information about data types, including how to extend an existing data type or create a new one, see Data Types.

The HealthVault Developer Center on MSDN (http://msdn.microsoft.com/healthvault) provides links to a variety of useful resources.

Show:
© 2014 Microsoft