.NET library for the Contentful Content Delivery API, Content Preview API and the Contentful Management API. It helps you to easily access your Content stored in Contentful with your .NET applications.
What is Contentful?
Contentful provides content infrastructure for digital teams to power websites, apps, and devices. Unlike a CMS, Contentful was built to integrate with the modern software stack. It offers a central hub for structured content, powerful management and delivery APIs, and a customizable web app that enable developers and content creators to ship their products faster.
Table of contents
- Content retrieval through the Content Delivery API and Content Preview API.
- Content management through the Content Management API
- Synchronization
- Localization support
- Link resolution
- Built in rate limiting with recovery procedures
We recommend you use the NuGet Package Manager to add the library to your .NET Application using one of the following options:
-
In Visual Studio, open Package Manager Console window and run the following command:
PM> Install-Package contentful.csharp
-
In a command-line, run the following .NET CLI command:
> dotnet add package contentful.csharp
The ContentfulClient handles all communication with the Contentful Content Delivery API.
To create a new client you need to pass an HttpClient, your delivery API key and any other configuration options:
var httpClient = new HttpClient();
var client = new ContentfulClient(httpClient, "<content_delivery_api_key>", "<content_preview_api_key>", "<space_id>");or:
var httpClient = new HttpClient();
var options = new ContentfulOptions
{
DeliveryApiKey = "<content_delivery_api_key>",
PreviewApiKey = "<content_preview_api_key>",
SpaceId = "<space_id>"
};
var client = new ContentfulClient(httpClient, options);If you are running asp.net core and wish to take advantage of the options pattern you can do so by passing an IOptions<ContentfulOptions> to the constructor. This lets you keep your authorization token in your application settings, in environment variables or your own custom Microsoft.Extensions.Configuration.IConfigurationSource provider.
After creating a ContentfulClient, you can now query for a single entry:
var entry = await client.GetEntry<Product>("<entry_id>");
Console.WriteLine(entry.ProductName); // => Contentful
Console.WriteLine(entry.Price); // => 12.38
Console.WriteLine(entry.Description); // => A fantastic product.public class Product
{
public string ProductName { get; set; }
public string Price { get; set; }
public string Description { get; set; }
}The properties of your class will be automatically deserialized from fields with matching names.
If you're interested in the system properties of the entry, add a SystemProperties property to the class.
public class Product
{
public SystemProperties Sys { get; set; }
public string ProductName { get; set; }
public string Price { get; set; }
public string Description { get; set; }
}var productEntry = await client.GetEntry<Product>("<entry_id>");
Console.WriteLine(productEntry.Price); // => 12.38
Console.WriteLine(productEntry.Sys.Id); // => 2CfTFQGwogugS6QcOuwO6qTo edit, update and delete content you use the ContentfulManagementClient class which uses the same familiar pattern as the regular client.
var httpClient = new HttpClient();
var managementClient = new ContentfulManagementClient(httpClient, "<content_management_api_key>", "<space_id>");You can then use the client to, for example, create a content type.
var contentType = new ContentType();
contentType.SystemProperties = new SystemProperties()
{
Id = "new-content-type"
};
contentType.Name = "New contenttype";
contentType.Fields = new List<Field>()
{
new Field()
{
Name = "Field1",
Id = "field1",
Type = "Text"
},
new Field()
{
Name = "Field2",
Id = "field2",
Type = "Integer"
}
};
await managementClient.CreateOrUpdateContentType(contentType);The Management API supports working with taxonomies through concept schemes and concepts. Here's how you can work with taxonomies:
// Create a taxonomy concept scheme
var conceptScheme = new TaxonomyConceptScheme
{
Name = "Product Categories",
Description = "Categories for our products"
};
var createdScheme = await managementClient.CreateTaxonomyConceptScheme(organizationId, conceptScheme);
// Create a scheme with a specific ID
var schemeWithId = await managementClient.CreateTaxonomyConceptSchemeWithId(organizationId, "my-scheme-id", conceptScheme);
// Get a specific concept scheme
var scheme = await managementClient.GetTaxonomyConceptScheme(organizationId, "scheme-id");
// Get all concept schemes
var schemes = await managementClient.GetTaxonomyConceptSchemes(organizationId, limit: 100);
// Get total number of concept schemes
var totalSchemes = await managementClient.GetTotalTaxonomyConceptSchemes(organizationId);
// Update a concept scheme
var patches = new List<JsonPatchOperation>
{
new JsonPatchOperation { Op = "replace", Path = "/name", Value = "Updated Name" }
};
var updatedScheme = await managementClient.UpdateTaxonomyConceptScheme(organizationId, "scheme-id", version, patches);
// Delete a concept scheme
await managementClient.DeleteTaxonomyConceptScheme(organizationId, "scheme-id", version);// Create a taxonomy concept
var concept = new TaxonomyConcept
{
Name = "Electronics",
Description = "Electronic products"
};
var createdConcept = await managementClient.CreateTaxonomyConcept(organizationId, concept);
// Create a concept with a specific ID
var conceptWithId = await managementClient.CreateTaxonomyConceptWithId(organizationId, "my-concept-id", concept);
// Get a specific concept
var concept = await managementClient.GetTaxonomyConcept(organizationId, "concept-id");
// Get all concepts
var concepts = await managementClient.GetTaxonomyConcepts(organizationId, limit: 100);
// Get concepts for a specific scheme
var schemeConcepts = await managementClient.GetTaxonomyConcepts(organizationId, conceptScheme: "scheme-id");
// Get total number of concepts
var totalConcepts = await managementClient.GetTotalTaxonomyConcepts(organizationId);
// Get concept descendants (child concepts)
var descendants = await managementClient.GetTaxonomyConceptDescendants(organizationId, "concept-id", depth: 2);
// Get concept ancestors (parent concepts)
var ancestors = await managementClient.GetTaxonomyConceptAncestors(organizationId, "concept-id", depth: 2);
// Update a concept
var patches = new List<JsonPatchOperation>
{
new JsonPatchOperation { Op = "replace", Path = "/name", Value = "Updated Name" }
};
var updatedConcept = await managementClient.UpdateTaxonomyConcept(organizationId, "concept-id", version, patches);
// Delete a concept
await managementClient.DeleteTaxonomyConcept(organizationId, "concept-id", version);// Add taxonomy concepts to an entry
var entry = new Entry<dynamic>();
entry.Metadata = new ContentfulMetadata
{
Concepts = new List<Reference>
{
new Reference
{
Sys = new ReferenceProperties
{
Id = "concept-id",
LinkType = SystemLinkTypes.TaxonomyConcept
}
}
}
};
await managementClient.CreateOrUpdateEntry(entry);
// Add taxonomy concepts to an asset
var asset = new ManagementAsset();
asset.Metadata = new ContentfulMetadata
{
Concepts = new List<Reference>
{
new Reference
{
Sys = new ReferenceProperties
{
Id = "concept-id",
LinkType = SystemLinkTypes.TaxonomyConcept
}
}
}
};
await managementClient.CreateOrUpdateAsset(asset);You can also add taxonomy concepts to content types to enable concept-based categorization at the content type level:
// Create a content type with taxonomy concepts
var contentType = new ContentType();
contentType.SystemProperties = new SystemProperties()
{
Id = "product"
};
contentType.Name = "Product";
contentType.Fields = new List<Field>()
{
new Field()
{
Name = "Title",
Id = "title",
Type = "Text"
},
new Field()
{
Name = "Description",
Id = "description",
Type = "Text"
}
};
// Add taxonomy concepts to the content type
contentType.Metadata = new ContentfulMetadata
{
Concepts = new List<Reference>
{
new Reference
{
Sys = new ReferenceProperties
{
Id = "product-category-concept",
LinkType = SystemLinkTypes.TaxonomyConcept
}
}
}
};
await managementClient.CreateOrUpdateContentType(contentType);This allows you to:
- Categorize entire content types with specific taxonomy concepts
- Filter and query content based on content type-level concepts
- Maintain consistent categorization across all entries of a content type
- Apply concept-based workflows and validations at the content type level
This library can also be used with the Preview API. Make sure you have a preview API key configured and set UsePreviewAPI on your client.
var httpClient = new HttpClient();
var options = new ContentfulOptions()
{
DeliveryApiKey = "<content_delivery_api_key>",
PreviewApiKey, "<content_preview_api_key>"
SpaceId = "<space_id>",
UsePreviewApi = true
}
var client = new ContentfulClient(httpClient, options);To get your own content from Contentful, an app should authenticate with an OAuth bearer token.
You can create API keys using the Contentful web interface. Go to the app, open the space that you want to access (top left corner lists all the spaces), and navigate to the APIs area. Open the API Keys section and create your first token. Done.
For more information, check the Contentful REST API reference on Authentication.
You can read the full documentation at https://www.contentful.com/developers/docs/net/ and explore the api at https://contentful.github.io/contentful.net-docs/
- Reach out to our community forum:
- Jump into our community slack channel:
- File an issue here on GitHub:
. Make sure to remove any credentials from your code before sharing it.
- File a support ticket at our Contentful Customer Support:
We appreciate any help on our repositories. For more details about how to contribute see our CONTRIBUTING.md document.
This repository is published under the MIT license.
We want to provide a safe, inclusive, welcoming, and harassment-free space and experience for all participants, regardless of gender identity and expression, sexual orientation, disability, physical appearance, socioeconomic status, body size, ethnicity, nationality, level of experience, age, religion (or lack thereof), or other identity markers.