.NET SDK

Getting Started

The Delivery .NET SDK lets you interact with Healthwise content using .NET. It supports .NET Core 2.0+.

Before You Begin

This guide assumes you have a working knowledge of the Compass data model. If you are new, we recommend you review the data model reference before continuing. See the Data Model section for more information.

Installation

Install the library through nuget or the .NET CLI.

dotnet add package healthwise-delivery-sdk-net

Create a Delivery Client

To use the Delivery API, instantiate a DeliveryClient object and initialize it with an access token.

See Authentication to learn how to get a token or embed code.

var deliveryClient = new DeliveryClient.Builder()
    .AccessToken(accessToken)
    .Build();

NOTE

Make sure to store your credentials securely. Do not hardcode your token or token creation credentials. Our sample application uses a configuration file to store credentials

Core Functionality

Content Search

This retrieves a paginated list of content resources. You can narrow the search by supplying content filters. To paginate through the response, supply top and skip parameters to the content search parameter.

Examples

Retrieve the title for all content records associated with the Asthma concept:

var results = await deliveryClient.Search(new ContentSearch
{
    AttributesToRetrieve = new List<ContentAttribute> { ContentAttribute.Title },
    Filter = new ContentFilter { Concept = new List<string> { "hwcv_20425" } }
});

Retrieve the data for all content records associated with Abscessed Tooth core content set:

var results = await deliveryClient.Search(new ContentSearch
{
    AttributesToRetrieve = new List<ContentAttribute> { ContentAttribute.CoreSets },
    Filter = new ContentFilter { CoreSet = new List<string> { "cc_00004" } }
});

Retrieve the title and codes for the What Is aspect of the Abscessed Tooth core set:

var results = await deliveryClient.Search(new ContentSearch
{
    AttributesToRetrieve = new List<ContentAttribute> { ContentAttribute.Title, ContentAttribute.AssociatedCodes },
    Filter = new ContentFilter
    {
        CoreSet = new List<string> { "cc_00004" },
        Aspect = new List<AspectLabel> { AspectLabel.WhatIs },
    }
});

Retrieve the title for the topic abo2094:

var results = await deliveryClient.Search(new ContentSearch
{
    AttributesToRetrieve = new List<ContentAttribute> { ContentAttribute.Title },
    Filter = new ContentFilter
    {
        Id = new List<string> { "abo2094" }
    }
});

Content Render

This is a single piece of content rendered as JSON or HTML. You can request the content in the following ways:

• By its ID, localization, and format.
• Semantically by its core set, aspect, localization, and format.

Supply RenditionOptions if you would like to modify the rendered output.

Examples

Request the HTML-formatted, American-English rendition of the topic abo2094:

var rendition = await deliveryClient.Render("abo2094", "en-us", RenditionFormat.Html, new RenditionOptions());

Request the longest available JSON-formatted, American-English rendition of the What Is aspect of the Abscessed Tooth core set:

var rendition = await deliveryClient.Render(new ContentKey
{
    CoreSetId = "cc_00004",
    AspectLabel = AspectLabel.WhatIs,
    Localization = "en-us"
}, RenditionFormat.Json, new RenditionOptions());

Core Content Set Search

This is a paginated list of core set resources. You can narrow the search by supplying core set filters. To paginate through the response, supply top and skip parameters to the core set search parameter.

Examples

Request the aspect and title for all core sets associated with the SNOMED CT code 309081009-Abnormal Cervical Smear:

var results = await deliveryClient.Search(new CoreSetSearch
{
    AttributesToRetrieve = new List<CoreSetAttribute> { CoreSetAttribute.Title, CoreSetAttribute.Aspects },
    Filter = new CoreSetFilter { Snomed = new List<string> { "309081009" } }
});

Request the title and codes for the Grief core set CC_00290:

{
    AttributesToRetrieve = new List<CoreSetAttribute> { CoreSetAttribute.Title, CoreSetAttribute.AssociatedCodes },
    Filter = new CoreSetFilter { Id = new List<string> { "CC_00290" } }
});

Retries and Timeout

You can configure the number of retries, the timeout, and the exponential backoff factor for HTTP requests in the Delivery Service .NET SDK. The following C# code specifies a HttpClientConfiguration parameter when creating the Delivery Client. The configuration sets the number of retries to two, a timeout of 60 seconds, and a back-off factor of two.

var deliveryClient = new DeliveryClient.Builder()
    .AccessToken(accessToken)
    .HttpClientConfiguration(config => config
        .NumberOfRetries(2)
        .Timeout(TimeSpan.FromSeconds(60))
        .BackOffFactor(2)
    ).Build();

Versioning

The Delivery Service .NET SDK follows Semantic Versioning (SemVer) for version numbers. SemVer consists of three parts: MAJOR.MINOR.PATCH.

• MAJOR version: Increments for incompatible API changes. Update cautiously, as it might require code adjustments.
• MINOR version: Adds new features in a backward-compatible manner. Update for added functionalities.
• PATCH version: Includes backward-compatible bug fixes. Update for bug resolutions.

For example, upgrading from 1.2.3 to 1.3.0 introduces new features, while 1.2.3 to 1.2.4 includes only bug fixes.

Usage Tracking

When making API calls, you can include a brief description about why you are making the API call. Filling out this information is optional; however, it helps us understand your use cases and assists in troubleshooting any issues that might come up.

To specify usage tracking for the .NET SDK, configure your Delivery Client with an ApplicationUseCase value:

var deliveryClient = new DeliveryClient.Builder()
    .AccessToken(accessToken)
    .ApplicationUseCase("Topic Inventory")
    .Build();

Errors

The Delivery .NET SDK throws exceptions on invalid actions or requests for nonexistent content. If there is an error with Healthwise, a client exception will be thrown (these are rare).

Make sure to surround your calls to Delivery Service functions with a try-catch block to appropriately respond to these errors.

Error	Description
InvalidRequestException	The requested was invalid, often due to incorrect query parameters.
UnauthorizedAccessException	No valid API key was provided.
ForbiddenAccessException	The API key does not have permissions to perform the request or does not have permissions to access the requested content.
NotFoundException	The requested resource does not exist.
IntentionalGapException	The requested resource is an intentional gap.
RestClientException	Something went wrong on the Healthwise server.