Working with Contentful environments and .NET

To make development easier for our users, we publish client libraries for various languages which make the task easier. This article details how to use the .NET CDA client library with environments.

Pre-requisites

This tutorial assumes you understand the basic Contentful data model as described in the developer center and that you have already read and understand the getting started tutorial for the .NET client library and the using the management API with Contentful and .NET client library article.

Contentful.net is built on .NET Core and targets .NET Standard 2.0. The client library is cross-platform and runs on Linux, macOS, and Windows.

Configuring your environment

The ContentfulOptions class has an Environment property that you can set to configure which environment you want to fetch content from. If omitted it will default to the master environment.

var httpClient = new HttpClient();
var options = new ContentfulOptions {
    DeliveryApiKey = "<content_delivery_api_key>",
    SpaceId = "<space_id>",
    Environment = "<environment_id>"
};
var client = new ContentfulClient(httpClient, options);

If you're using ASP.NET Core you can set the environment in your appsettings.json.

"ContentfulOptions": {
    "DeliveryApiKey": "<access_token>",
    "ManagementApiKey": "<cma_access_token>",
    "PreviewApiKey": "<preview_access_token>",
    "SpaceId": "<space_id>",
    "UsePreviewApi": false,
    "MaxNumberOfRateLimitRetries": 0,
    "Environment": "<environment_id>"
  }

Fetching content from an environment

Once an environment is configured, subsequent requests to all environment aware endpoints will use that environment. For example calling GetEntries with an environment configured will result in fetching entries from that environment.

var httpClient = new HttpClient();
var options = new ContentfulOptions {
    DeliveryApiKey = "<content_delivery_api_key>",
    SpaceId = "<space_id>",
    Environment = "staging"
};
var client = new ContentfulClient(httpClient, options);

var entries = await client.GetEntries<Product>();
// entries would be a collection of entries from the "staging" environment

The same is true for calling GetAssets, GetContentTypes. In fact all the methods of the CDA (Content Delivery API) client, except the sync methods, are environment aware.

However, when using the ContentfulManagementClient, only a subset of the methods available on the ContentfulManagementClient are environment aware. The other methods will call your master environment, regardless of wether you have an environment configured or not. The following methods are not environment aware:

• CreateSpace
• UpdateSpaceName
• GetSpace
• GetSpaces
• DeleteSpace
• GetWebhooksCollection
• CreateWebhook
• CreateOrUpdateWebhook
• GetWebhook
• DeleteWebhook
• GetWebhookCallDetailsCollection
• GetWebhookCallDetails
• GetWebhookHealth
• GetRole
• GetAllRoles
• CreateRole
• UpdateRole
• DeleteRole
• GetSpaceMemberships
• CreateSpaceMembership
• GetSpaceMembership
• UpdateSpaceMembership
• DeleteSpaceMembership
• GetAllApiKeys
• CreateApiKey
• GetAllUsers
• GetUser
• GetCurrentUser
• GetUpload
• UploadFile
• DeleteUpload
• CreateManagementToken
• GetAllManagementTokens
• GetManagementToken
• RevokeManagementToken
• GetOrganizations
• GetEnvironments
• CreateEnvironment
• CreateOrUpdateEnvironment
• GetEnvironment
• DeleteEnvironment

This means that a call to any of the above methods will always use your master environment.

var httpClient = new HttpClient();
var options = new ContentfulOptions {
    ManagementApiKey = "<content_management_api_key>",
    SpaceId = "<space_id>",
    Environment = "staging"
};
var client = new ContentfulManagementClient(httpClient, options);

var contentTypes = await client.GetContentTypes();
// would get all the content types from the "staging" environment

await client.DeleteWebhook("<webhook_id>");
// Will delete the webhook from the master environment!

The above example shows how you can fetch content types from a specific environment, but the call to DeleteWebhook will actually delete the webhook from the space as webhooks are currently not environment aware. It is therefore very important to understand which endpoints affect an environment and which affect the entire space to avoid involuntary data loss.