/contentful.net

.NET Library for Contentful's Content Delivery and Management API

Primary LanguageC#MIT LicenseMIT

header

Join Contentful Community Slack   Join Contentful Community Forum

contentful.net - Contentful .NET Library

.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.

This repository is actively maintained   MIT License   Build Status

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

Core Features

Getting started

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

Usage

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.

Your first request

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); // => 2CfTFQGwogugS6QcOuwO6q

Management API

To 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);

Using the library with the Preview API

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);

Authentication

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.

Further documentation

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 us

You have questions about how to use this library?

  • Reach out to our community forum: Contentful Community Forum
  • Jump into our community slack channel: Contentful Community Slack

You found a bug or want to propose a feature?

  • File an issue here on GitHub: File an issue. Make sure to remove any credentials from your code before sharing it.

You need to share confidential information or have other questions?

  • File a support ticket at our Contentful Customer Support: File support ticket

Get involved

PRs Welcome

We appreciate any help on our repositories. For more details about how to contribute see our CONTRIBUTING.md document.

License

This repository is published under the MIT license.

Code of Conduct

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.

Read our full Code of Conduct.