ConnectPackage.Create Method (Microsoft.Health.Package)

Asks HealthVault to create a pending package for the application specified by the connection with the specified user specific parameters.

Declaration Syntax

Public Shared Function Create( _
	ByVal connection As OfflineWebApplicationConnection, _
	ByVal friendlyName As String, _
	ByVal securityQuestion As String, _
	ByVal securityAnswer As String, _
	ByVal applicationPatientId As String, _
	ByVal packageContents As System.Collections.Generic.IList`1 _
) As String
public static string Create(
	OfflineWebApplicationConnection connection, 
	string friendlyName, 
	string securityQuestion, 
	string securityAnswer, 
	string applicationPatientId, 
	System.Collections.Generic.IList`1<HealthRecordItem> packageContents
public: static System.String Create(
	OfflineWebApplicationConnection connection, 
	System.String friendlyName, 
	System.String securityQuestion, 
	System.String securityAnswer, 
	System.String applicationPatientId, 
	System.Collections.Generic.IList`1 packageContents
public static function Create(
	connection : OfflineWebApplicationConnection, 
	friendlyName : System.String, 
	securityQuestion : System.String, 
	securityAnswer : System.String, 
	applicationPatientId : System.String, 
	packageContents : System.Collections.Generic.IList`1
) : System.String;


The application connection to HealthVault. The application ID in the connection is used when making the patient connection.  
A friendly name for the patient connection which will be shown to the user when they go to HealthVault Shell to validate the connection.  
A question (usually provided by the patient) to which the patient must provide the securityAnswer when they go to validate the connection in the HealthVault Shell.  
The answer to the securityQuestion which the patient must use when adding the package to their record via HealthVault Shell. The answer is case-insensitive but otherwise must match exactly. Additionally, it must be at least 6 characters long.  
The application specific identifier for the user. This identifier is used to uniquely identify the user in the application data storage, whereas the HealthVault person ID is used to identify the person in HealthVault.  
The list of HealthRecordItems that will be encrypted and added to the package that the user will claim via HealthVault Shell.  

Return Value

A token that the application must give to the patient to use when validating the connection request.


Exception TypeCondition
System.ArgumentNullException If connection is null.
System.ArgumentException If friendlyName, securityQuestion, securityAnswer, applicationPatientId or any element in packageContents are null or empty.
System.ArgumentOutOfRangeException If securityAnswer is less than 6 characters.
HealthServiceException If an error occurs when contacting HealthVault.


The encryption is delegated to the .NET Crypto classes. The encryption algorithm supported by default is AES256. If TripleDES is required, the caller should create the custom Password Protected Package and call Create.

The answer key provided is not the actual key to the decryption. A key is derived using the answer, the salt, and the number of hash iterations (via the System.Security.Cryptography.Rfc2898DeriveBytes class). To ensure case-insensitivity, the answer is lower cased using System.String.ToLowerInvariant (culturally-agnostic) prior to generating the derived key.

The algorithm used has the following parameters:
  • Mode = CipherMode.CBC
  • Padding = PaddingMode.ISO10126

The salt supplied is used as the salt to the derived key as well as the key to the supplied HMAC. The data must be appended to the hash, then encrypted and then Base64 encoded.


Namespace: Microsoft.Health.Package
Assembly: Microsoft.Health (