buttercms-csharp

.NET Standard (2.1) Library for ButterCMS API.

Documentation

For a comprehensive list of examples, check out the API documentation.

Installation

To install ButterCMS, run the following command in the Package Manager Console

PM> Install-Package ButterCMS

The library can also be installed to the project via .NET CLI

dotnet add package ButterCMS

Or by adding the package manually to the project file

<ItemGroup>
<PackageReference Include="ButterCMS" Version="2.0.2" />
</ItemGroup>

Usage

To get started with the Butter API, instantiate the ButterCMSClient with the API key found in the Butter Admin Settings. An optional timeout parameter can be passed as a TimeSpan; the default is 10 seconds.

using ButterCMS;
...
var butterClient = new ButterCMSClient("API KEY");

If the application will be making many Butter API calls, it is recommended to store and re-use the client object.

Each Butter client method has a synchronous version and an asynchronous version. Asynchronous methods are appended with the word "Async".

Preview mode

Preview mode can be used to setup a staging website for previewing content fields or for testing content during local development. To fetch content from preview mode add an additional argument, true, to the package initialization:

using ButterCMS;
...
bool previewMode = true;

var butterClient = new ButterCMSClient("API KEY", null, 3, null, previewMode);

Sections

• Posts
• Authors
• Categories
• Feeds
• Collections
• Pages
• Class Definitions
• Exceptions

Posts

List Posts

Listing posts returns a PostsResponse object. This object consists of a metadata object and IEnumerable<Post>

ListPosts() Parameters

Examples

PostsResponse posts = butterClient.ListPosts();

PostsResponse filteredPosts = await butterClient.ListPostsAsync(page: 2, pageSize: 5, excludeBody: true, authorSlug: "alice", categorySlug: "dot-net");

Retrieving a Single Post

Retrieving a single Post will return a PostResponse object. This object consists of a single Post and Post Metadata. Post Metadata offers hints about the Previous and Next posts.

RetrievePost() Parameters

Examples

PostResponse controversialPost = butterClient.RetrievePost("tabs-vs-spaces-throwdown");

PostResponse safePost = await butterClient.RetrievePostAsync("puppies-and-kittens");

Searching Posts

Searching posts will return the same object as listing posts, PostsResponse

SearchPosts() Parameters

Examples

PostsResponse posts = butterClient.SearchPosts("spaceships");

PostsResponse caffeinePosts = await butterClient.SearchPostsAsync(query: "coffee", page: 3, pageSize: 5);

Authors

List Authors

Listing Authors returns IEnumerable<Author>

ListAuthors() Parameters

Examples

IEnumerable<Author> authors = butterClient.ListAuthors();

IEnumerable<Author> authorsWithPosts = await butterClient.ListAuthorsAsync(includeRecentPosts: true);

Retrieve a Single Author

Retrieving an author returns an Author object

RetrieveAuthor() Parameters

Examples

Author sally = butterClient.RetrieveAuthor("sally");

Author tylerAndPosts = await butterClient.RetrieveAuthorAsync(authorSlug: "tyler", includeRecentPosts: true);

Categories

List Categories

Listing Categories returns IEnumerable<Category>

ListCategories() Parameters

Examples

IEnumerable<Category> categories = butterClient.ListCategories();

IEnumerable<Category> categoriesWithPosts = await butterClient.ListCategoriesAsync(includeRecentPosts: true);

Retrieve a Single Category

Retrieving a single category returns Category

RetrieveCategory() Parameters

Examples

 Category dotnetCategory = butterClient.RetrieveCategory("dotnet");

 Category fsharpCategoryWithPosts = await butterClient.RetrieveCategoryAsync(categorySlug: "fsharp", includeRecentPosts: true);

Feeds

Each of the feeds methods returns an XmlDocument.

RSS Feed

Retrieve a fully generated RSS feed for your blog.

Examples

 XmlDocument rssFeed = butterClient.GetRSSFeed();

 XmlDocument rssFeed = await butterClient.GetRSSFeedAsync();

Atom Feed

Retrieve a fully generated Atom feed for your blog.

Examples

 XmlDocument atomFeed = butterClient.GetAtomFeed();

 XmlDocument atomFeed = await butterClient.GetAtomFeedAsync();

Sitemap

Retrieve a fully generated sitemap for your blog.

Examples

 XmlDocument siteMap = butterClient.GetSitemap();

 XmlDocument siteMap = await butterClient.GetSitemapAsync();

Collections

New in version 1.3.0

By the power of .NET generics, Collections can now be deserialized by the library! The former method that would defer deserialization is still available to ease transition.

RetrieveContentFields() Parameters

RetrieveContentFields() Exceptions:

Examples

var key = new string[1] { "collection_key" };
var dict = new Dictionary<string, string>()
            {
                { "locale", "de" }
            };
var teamMembersAndHeadline = butterClient.RetrieveContentFields<TeamMembersHeadline>(key, dict);

** Collection JSON documentation** :

As demonstrated in the Collection documentation, any number of user-defined Collections can be retrieved from the API, these can get complicated in C# and you may choose to handle the response yourself. The RetrieveContentFieldsJSON() method will return the raw JSON response from the Butter API.

RetrieveContentFieldsJSON() Parameters

Examples

var key = new string[1] { "collection_key" };
var dict = new Dictionary<string, string>()
            {
                { "locale", "de" }
            };
var contentFields = await butterClient.RetrieveContentFieldsJSONAsync(key, dict);

Pages

ButterCMS Pages can be retrieved by first defining the custom Page Type as a class. These custom Page Types are defined in the Butter admin.

List Pages

Listing Pages returns a PagesResponse<T> object. Full API documentation can be found at https://buttercms.com/docs/api/#list-pages-for-a-page-type.

ListPages() Parameters

ListPages() Exceptions

Retrieve a Single Page

Retrieving a single page returns a PageResponse<T> object

RetrievePage() Parameters

RetrievePage() Exceptions:

Examples

Page Type Definition in the Butter Admin

Controller and ViewModel examples

public namespace HungryDevApp
{
    public class RecipePage
    {
        public string category { get; set; }
        public string recipe_name { get; set; }
        public string main_ingredient { get; set; }
        public double estimated_cooking_time_in_minutes { get; set; }
        public string ingredient_list { get; set; }
        public string instructions { get; set; }
    }

    public class RecipesController : Controller
    {
        [Route(recipes/)]
        public virtual ActionResult Index(int page = 1, int pageSize = 10)
        {
            var butterClient = new ButterCMSClient("API KEY");

            var parameterDict = new Dictionary<string, string>()
            {
                {"page", page.ToString()},
                {"page_size", pageSize.ToString()}
            };

            PagesResponse<RecipePage> recipePages = butterClient.ListPages<RecipePage>("recipe", parameterDict);

            var viewModel = new RecipesViewModel();
            viewModel.PreviousPageNumber = recipePages.Meta.PreviousPage;
            viewModel.NextPageNumber = recipePages.Meta.NextPage;
            viewModel.PagesCount = recipePages.Meta.Count;

            viewModel.Recipes = new List<RecipeViewModel>();
            foreach (Page<RecipePage> recipe in recipePages.Data)
            {
                RecipeViewModel recipeViewModel = new RecipeViewModel();
                recipeViewModel.Category = recipe.Fields.category;
                recipeViewModel.RecipeName = recipe.Fields.recipe_name;
                recipeViewModel.MainIngredient = recipe.Fields.main_ingredient;
                recipeViewModel.EstimatedCookingTimeInMinutes = recipe.Fields.estimated_cooking_time_in_minutes;
                recipeViewModel.IngredientList = recipe.Fields.ingredient_list;
                recipeViewModel.Instructions = recipe.Fields.instructions;

                viewModel.Recipes.Add(recipeViewModel);
            }

            return View(viewModel);
        }

        [Route(recipe/{slug})]
        public virtual ActionResult Recipe(string slug)
        {
            var butterClient = new ButterCMSClient("API KEY");

            PageResponse<RecipePage> recipe = butterClient.RetrievePage<RecipePage>("recipe", slug);

            var viewModel = new RecipeViewModel();
            viewModel.Category = recipe.Data.Fields.category;
            viewModel.RecipeName = recipe.Data.Fields.recipe_name;
            viewModel.MainIngredient = recipe.Data.Fields.main_ingredient;
            viewModel.EstimatedCookingTimeInMinutes = recipe.Data.Fields.estimated_cooking_time_in_minutes;
            viewModel.IngredientList = recipe.Data.Fields.ingredient_list;
            viewModel.Instructions = recipe.Data.Fields.instructions;

            return View(viewModel);
        }
    }

    public class RecipesViewModel
    {
        public List<RecipeViewModel> Recipes { get; set; }
        public int? PreviousPageNumber { get; set; }
        public int? NextPageNumber { get; set; }
        public int PagesCount { get; set; }
    }

    public class RecipeViewModel
    {
        public string Category { get; set; }
        public string RecipeName { get; set; }
        public string MainIngredient { get; set; }
        public double EstimatedCookingTimeInMinutes { get; set; }
        public string IngredientList { get; set; }
        public string Instructions { get; set; }
    }

}

Example View usage for ListPages

@using HungryDevApp
@{
Layout = "~/Views/Shared/Layouts/_Layout.cshtml";
}
@model RecipesViewModel
<div>
    <a href="/recipes/?page=@{Model.PreviousPageNumber}&pageSize=10">Previous page</a>
    <a href="/recipes/?page=@{Model.NextPageNumber}&pageSize=10">Next page</a>
</div>
<div>
    <p>@{Model.PagesCount} recipes total</p>
</div>
<div>
    <ul>
        @foreach(var page in Model.Recipes)
        {
            <li>
                <a href="/recipe/@{page.Slug}">@{page.RecipeName}
            </li>
        }
    </ul>
</div>

Example View usage for RetrievePage

@using HungryDevApp
@{
Layout = "~/Views/Shared/Layouts/_Layout.cshtml";
}
@model RecipeViewModel
<div>
    <h2>@{Model.RecipeName}</h2>
    <p>Estimated cooking time: @{Model.EstimatedCookingTimeInMinutes} minutes</p>
    <h3>Ingredients:</h3>
    <p>@{Model.IngredientList}</p>
    <h3>Instructions:</h3>
    <p>@{Model.Instructions}</p>
</div>

Class Definitions

PostsResponse Class

PostsMeta Class

Post Class

PostStatusEnum

PostResponse Class

PostMeta Class

PostLight Class

Author Class

Category Class

PagesResponse Class

PageMeta Class

PageResponse Class

Page Class

Exceptions

Testing

To run SDK test just simply:

PM> dotnet test

Or use Visual Studio Test Explorer.

InvalidKeyException

The library throws this exception when the Butter API key used to instatiate the client was not valid.

ContentFieldObjectMismatchException

This exception will be thrown when the library can't fit the returned data from a Content Field request into the passed object class.

PagesObjectMismatchException

This exception will be thrown when the library can't fit the returned data from a Pages request into the passed object class.