Installation

This document provides detailed, step-by-step instructions for setting up the TheExampleApp application on a local development machine. It is intended for developers who will be maintaining or contributing to the project.

System Requirements

Before proceeding with the installation, ensure your development environment meets the following prerequisites. The application is built on .NET Core, making it compatible with Windows, macOS, and Linux.

Component	Version	Notes
.NET Core SDK	2.1	Required to build, restore dependencies, and run the application. The specific version is defined in TheExampleApp.csproj.
Git	Latest	Required for cloning the source code repository.
Contentful CLI	Optional	Recommended for a full development experience, including creating and seeding a new Contentful space. Install via npm: npm install -g contentful-cli.

Deprecation Notice: The underlying .NET Core 2.1 framework is out of its official support lifecycle. The project is also marked as unmaintained as of January 2023. Developers should be aware of potential security vulnerabilities and consider planning an upgrade to a more recent .NET version.

Clone the Repository

The first step is to obtain the source code from the Git repository.

1. Open your terminal or command prompt.
2. Navigate to the directory where you want to store the project.
3. Execute the following command to clone the repository:

git clone https://github.com/contentful/the-example-app.csharp.git

This will create a new directory named the-example-app.csharp containing the complete source code.

Install Dependencies

The application relies on several NuGet packages for its core functionality. These dependencies are defined in the TheExampleApp.csproj file and can be installed using the .NET CLI.

1. Navigate into the project's root directory:

   cd the-example-app.csharp

2. Run the dotnet restore command. This command reads the project file and downloads all required packages from the NuGet package registry.

   dotnet restore

This process will install key libraries including:

• Microsoft.AspNetCore.All: The main ASP.NET Core metapackage.
• contentful.aspnetcore: The SDK for interacting with the Contentful API.
• Markdig: The Markdown processor for rendering content.

Contentful Setup

The application is architected to fetch all its primary content from the Contentful headless CMS. You can run the application in two modes: a read-only mode using a shared demo space, or a full read/write mode connected to your own Contentful space. For development, the read/write mode is highly recommended.

Option 1: Read-Only Mode (Quick Start)

The repository comes pre-configured to connect to a public, read-only Contentful space. This is the fastest way to see the application running, but you will not be able to edit content. The default credentials are included in appsettings.json:

// File: TheExampleApp/appsettings.json
{
  // ...
  "ContentfulOptions": {
    "DeliveryApiKey": "df2a18b8a5b4426741408fc95fa4331c7388d502318c44a5b22b167c3c1b1d03",
    "PreviewApiKey": "10145c6d864960fdca694014ae5e7bdaa7de514a1b5d7fd8bd24027f90c49bbc",
    "SpaceId": "qz0n5cdakyl9",
    "UsePreviewApi": false
  }
}

With this configuration, you can proceed directly to the Verify Installation step.

Option 2: Read/Write Mode (Recommended for Development)

To fully experience the development workflow, including content modeling and editing, you must connect the application to your own Contentful space. This involves creating a new space and seeding it with the required content model.

1. Install the Contentful CLI if you haven't already:

   npm install -g contentful-cli

2. Log in to Contentful: This command will open a browser window to authenticate your account.

   contentful login

3. Create a New Space: Execute the following command. Make a note of the SPACE_ID that is returned in the output.

   contentful space create --name 'My space for the example app'

4. Seed the Space: Use the SPACE_ID from the previous step to seed your new space with the necessary content types and entries.

   contentful space seed -s '<SPACE_ID>' -t the-example-app

5. Retrieve API Keys: Head to the Contentful web app's API section and grab your SPACE_ID, DELIVERY_ACCESS_TOKEN, and PREVIEW_ACCESS_TOKEN.

You will now have the three credentials required for the next step.

Configuration

Application settings, including Contentful credentials, are managed through appsettings.json. To connect to your own space, you must update this file.

1. Open TheExampleApp/appsettings.json in your code editor.
2. Locate the ContentfulOptions section.
3. Replace the default values with the credentials you obtained from your Contentful space.

{
  "ContentfulOptions": {
    "DeliveryApiKey": "<DELIVERY_ACCESS_TOKEN>",
    "PreviewApiKey": "<PREVIEW_ACCESS_TOKEN>",
    "SpaceId": "<SPACE_ID>",
    "UsePreviewApi": false
  }
}

Configuration Details

• DeliveryApiKey: The access token for the Contentful Delivery API (published content).
• PreviewApiKey: The access token for the Contentful Preview API (draft content).
• SpaceId: The unique identifier for your Contentful space.
• UsePreviewApi: A boolean flag that controls which Contentful API the application uses.
  • false (default): Fetches only published content.
  • true: Fetches both published and draft content. This is essential for development and for previewing changes before they go live.

These settings are loaded at startup in Startup.cs and injected into the application's service container, making the Contentful client available throughout the application.

// File: TheExampleApp/Startup.cs - How configuration is consumed
public void ConfigureServices(IServiceCollection services)
{
    // ...
    // Registers Contentful services and options from IConfiguration (appsettings.json)
    services.AddContentful(Configuration); 
    // ...
}

Verify Installation

Once the dependencies are installed and the configuration is complete, you can run the application.

1. Execute the following command to start the server:

   dotnet run

2. Open http://localhost:3000 in your web browser. You should see the application's home page.

Using Editorial Features

For development, it is useful to enable the editorial features, which provide direct links to edit content in Contentful and display the status of draft content.

To enable these features, append the editorial_features=enabled query parameter to the URL:

http://localhost:3000?editorial_features=enabled

This will activate UI elements like "Edit" buttons on content entries, as well as "Draft" and "Pending Changes" status indicators, providing a seamless workflow between the running application and the Contentful web app.