In this article you can learn more about the .NET client library that you can clone and use with your Umbraco Heartcore projects.

It is a library for .NET Core and is based on .NET Standard 2.0. This means that it can be used on the most .NET frameworks, for example UWP, Xamarin.Android, Xamarin.Mac and Desktop .NET 4.6.1.

Download and install

The .NET library can be found on GitHub: .NET client library for Umbraco Heartcore.

You can also install it through NuGet:

> Install-Package Umbraco.Headless.Client.Net

You will receive a Visual Studio solution file that references the client library (Umbraco.Headless.Client.Net). Additionally, there is a test project (Umbraco.Headless.Client.Net.Tests) utilizing xUnit for unit and integration tests.

Along with the client library you will also find two samples based on the library. We have built an MVC sample and a console sample.

MVC sample

Test your Umbraco Heartcore project against a small MVC site. You can choose to use our sample project and content, or connect to your own project and build your own views and controllers.

Content Management sample

Get to know the content management service and how to use it to manage content and media programmatically.

In /samples/Umbraco.Headless.Client.Samples.Web/ you will find a .NET 6.0-based MVC website implementation. It presents one possible approach to creating a website using Umbraco Heartcore for Content Delivery.

The sample is built around a sample project with the alias demo-headless. You can choose to test the sample with the sample project or connect the sample to your own project.

Prerequisites

• .NET 6.0

Run the sample on your local machine

Before running the sample, you must define which Umbraco Heartcore project you want to fetch content from.

• Open the appsettings.json found in samples/Umbraco.Headless.Client.Samples.Web/Umbraco.Headless.Client.Samples.Web/

• Add your project alias or use the default alias of the sample project, demo-headless

{
    "Heartcore": {
        "ProjectAlias": "demo-headless",
        "ApiKey": ""
    }
}

The ApiKey can be left blank when using the demo-headless sample project. If you are testing with your project and have chosen to protect the content exposed via the Content Delivery API, you will need an API Key. It is an option that has to be actively turned on via the Umbraco Backoffice in the Headless tree in the Settings section. Read more about this feature in the Backoffice users and API Keys article.

The MVC sample can be run in one of two ways:

1. Use the command line

Using a command-line tool, run the following two commands in the Umbraco.Headless.Client.Samples.Web folder:

dotnet restore
dotnet run

The first command will restore the packages and the second will run the site. Alternatively, you can use the new hot-reload functionality:

dotnet watch run

To run the project and hot reload or recompile the project whenever changes are detected.

2. Using an Integrated Development Environment (IDE)

Run the application in Visual Studio or Visual Studio Code by hitting F5.

Show your content

For the following section, a Umbraco Heartcore project with the following content structure will be used:

When you have connected the client project to your Umbraco project and run the client project, you will be presented with a default page. The page shows the properties and the data from the content node at the root of your website. This is because no view or controller has yet been defined for your content structure.

We will need to define and build a view and/or an MVC controller for the content types (Document Types) in our client project in order for us to start rendering content.

There are two ways to do this:

• Define a view file using the Document Type alias or

• Build a controller using the already defined UmbracoController

Each approach is explained in more detail below.

Define a view file

1. Create a model class for the content type you want to render, e.g., Models/HomePage.cs. Make sure the model extends the abstract class Content and that the properties you want to render from the Umbraco content node are defined as public properties with PascalCasing. PascalCasing means that a content node property called personName will be mapped to the PersonName property in the model.

2. Create a homePage.cshtml file in Views/DefaultUmbraco - the name of the file should be the alias of the Document Type the root content node is using.

3. Set HomePage as the model.

4. Set layout to null - this can be used later on when you want to share one layout between more views.

@model Umbraco.Headless.Client.Net.Delivery.Models.Content
@{
    Layout = null;
}

When you build the solution and start it up, this view file will now be used to populate the frontend.

Build a controller

1. Right-click the Controllers folder in Visual Studio and select Add > Controller...

2. Select MVC Controller - Empty

3. Use the alias of the Document Type used on the root content node for the name of the controller, e.g. HomePageController

4. Set the controller to use UmbracoController

5. Set the Index() action to return UmbracoContext.Content

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Umbraco.Headless.Client.Samples.Web.Mvc;

namespace Umbraco.Headless.Client.Samples.Web.Controllers
{
    public class HomePageController : Controller
    {
        public HomePageController(UmbracoContext umbracoContext) : base(umbracoContext)
        {
        }

        public IActionResult Index()
        {
            return View(UmbracoContext.Content);
        }
    }
}

The controller is now in place but to show our content we also need to define a view.

1. Create a folder in /Views using the alias of the Document Type, e.g. /HomePage.

2. Create an Index.cshtml file in the new folder.

3. Follow steps 2-3 from the Define a view file section.

4. Build and run the solution.

Building view files

To render the data from the properties on our content, we need to use the @Model.PropertyName approach, where the value is the Name of the property you want to display the data from.

An example could be a text string property with the alias heading. To render the data from this property on the frontend, we will need to use @Model.Heading.

note To render data from a property, the property must be defined in the view model (@model), and it must match an alias on the corresponding content node from your Umbraco project.

Below is a complete example of how a view for a root node could look.

@using Umbraco.Headless.Client.Net.Delivery.Models;
@model HeroPage
@{
    Layout = null;
}

<!DOCTYPE HTML>
<html>

<head>
    <title>@Model.Title</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />
</head>

<body>

    <h1>@Model.Heading</h1>

    <div>

        <p>@Html.Raw(Model.BodyText)</p>

        <img src="@(Model.PromoImage?.Url)?width=300" />

    </div>

</body>
</html>

HTML is used to build the general structure of the article, while we use Razor to render data from our Umbraco Heartcore project.

References

• Overview of ASP.NET Core MVC

• Tutorial: Get started with ASP.NET Core MVC

• API Documentation for Umbraco Heartcore

• Create an Umbraco Heartcore project

This sample guide will cover how you can access and work with the from the client library.

Requirements

• .NET/.NET Core (2.0 or newer) or .NET Framework (4.6.1 or newer)

Getting Started

1. Add the Umbraco.Headless.Client.Net package to your project.

   dotnet add package Umbraco.Headless.Client.Net

2. Add environment variables for your project alias and your API key.

3. Register the ContentManagementService to your dependency injection container. The registration of the ContentManagementService is handled by the AddUmbracoHeartcore extension method.

1. Inject the ContentManagementService into your non-static class.

Now you are ready to start using the ContentManagementService.

Content

When working with content, the ContentManagementService can Get, Create, Update, Publish, Unpublish, and Delete content.

Get Content

The ContentManagementService has three methods for getting content.

GetRoot()

Gets all content at the root of the tree.

To use this method, call the method on the ContentManagementService instance:

GetById(Guid id)

Gets a specific content item matching a GUID.

To use this method, call the method on the ContentManagementService instance and pass in the GUID of the content item you want to get:

GetChildren(Guid id)

Gets all content that is a child of a specific content item.

To use this method, call the method on the ContentManagementService instance and pass the GUID of the content item to get the children:

Create Content

The ContentManagementService has one method for creating content.

Create(Content content)

Creates a new content item based on the passed-in Content object.

To use this method, call the method on the ContentManagementService instance and pass in the content item you want to create:

Update Content

The ContentManagementService has one method for updating content.

Update(Content content)

Updates an existing content item based on the passed-in Content object.

To use this method, call the method on the ContentManagementService instance and pass in the content item you want to update:

Publish Content

The ContentManagementService has one method for publishing content.

Publish(Guid id, string culture = "*")

Publishes an existing content item based on the passed-in GUID and culture.

To use this method, call the method on the ContentManagementService instance and pass in the GUID of the content item you want to publish:

Optionally, you can also pass in the culture of the content item you want to publish:

Unpublish Content

The ContentManagementService has one method for unpublishing content.

Unpublish(Guid id, string culture = "*")

Unpublishes an existing content item based on the passed-in GUID and culture.

To use this method, call the method on the ContentManagementService instance and pass in the GUID of the content item you want to unpublish:

Optionally, you can also pass in the culture you want to unpublish the content item in:

Delete Content

The ContentManagementService has one method for deleting content.

Delete(Guid id)

Deletes an existing content item based on the passed-in GUID.

To use this method, call the method on the ContentManagementService instance and pass in the GUID of the content item you want to delete:

Media

When working with media, the ContentManagementService can Get, Create, Update and Delete media.

Get Media

The ContentManagementService has three methods for getting media.

GetRoot()

Gets all media at the root of the tree.

To use this method, call the method on the ContentManagementService instance:

GetById(Guid id)

Gets a specific media item matching a GUID.

To use this method, call the method on the ContentManagementService instance and pass in the GUID of the media item you want to get:

GetChildren(Guid id)

Gets all media that is a child of a specific media item.

To use this method, call the method on the ContentManagementService instance and pass in the GUID of the media item to get the children:

Create Media

The ContentManagementService has one method for creating media.

Create(Media media)

Creates a new media item based on the passed-in Media object.

To use this method, call the method on the ContentManagementService instance and pass in the media item you want to create:

Update Media

The ContentManagementService has one method for updating media.

Update(Media media)

Updates an existing media item based on the passed-in Media object.

To use this method, call the method on the ContentManagementService instance and pass in the media item you want to update:

Delete Media

The ContentManagementService has one method for deleting media.

Delete(Guid id)

Deletes an existing media item based on the passed-in GUID.

To use this method, call the method on the ContentManagementService instance and pass in the GUID of the media item you want to delete:

Further reading