Local setup

Note: This repository is no longer officially maintained as of January 2023. Feel free to use it, fork it, and patch it for your own needs.

This document provides a comprehensive guide for setting up TheExampleApp on a local development machine. It is intended for developers who will be contributing to and maintaining the application. Following these steps will result in a fully functional local instance connected to a Contentful space.

Before proceeding, ensure you have met all the necessary system requirements outlined in the Prerequisites documentation.

Clone the repository

The first step is to clone the source code from the repository to your local machine. Use Git to clone the project into a directory of your choice.

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

This will create a local copy of the repository, giving you access to the entire codebase.

Install dependencies

The application's dependencies are managed by the .NET Core SDK. The project file (TheExampleApp/TheExampleApp.csproj) defines all required backend packages.

To install all necessary dependencies, run the dotnet restore command from the root of the project directory:

dotnet restore

This command reads the project's .csproj file and downloads the specified packages.

Dependency Graph Overview

The dotnet restore command resolves the following key dependencies defined in TheExampleApp.csproj:

<!-- TheExampleApp/TheExampleApp.csproj -->
<ItemGroup>
  <PackageReference Include="contentful.aspnetcore">
    <Version>3.3.6</Version>
  </PackageReference>
  <PackageReference Include="Markdig">
    <Version>0.15.4</Version>
  </PackageReference>
  <PackageReference Include="Microsoft.AspNetCore.All" Version="2.1.5" />
  <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design">
    <Version>2.1.5</Version>
  </PackageReference>
</ItemGroup>
<ItemGroup>
  <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.0" />
</ItemGroup>

Package	Role & Purpose
Microsoft.AspNetCore.All	A metapackage for ASP.NET Core 2.1. It bundles the MVC framework, Kestrel web server, logging, configuration, and other essential libraries for building the web application.
contentful.aspnetcore	The official Contentful SDK for ASP.NET Core. This is crucial for integrating with the Contentful Delivery and Preview APIs to fetch content. It is configured in Startup.cs.
Markdig	A high-performance Markdown processor. This indicates that content fields retrieved from Contentful are likely in Markdown format and are parsed into HTML on the server before being rendered in Razor views.
Microsoft.VisualStudio.Web.CodeGeneration.Design	A design-time tool used for scaffolding controllers, views, and other ASP.NET Core components, streamlining development workflows.

Note on Frontend Dependencies: The project uses Bower for frontend package management, but the bower.json file is empty. This confirms the application's server-side rendered (SSR) architecture and the absence of a major client-side JavaScript framework like React or Angular.

Run the application

Once dependencies are installed, you can run the application using the .NET Core CLI.

Starting the development server

The application is launched via the dotnet run command. This command compiles the project and starts the Kestrel web server.

dotnet run

The application's entry point is Program.cs, which sets up and runs the web host. The host is configured to use the Startup class for service and pipeline configuration.

// TheExampleApp/Program.cs
public class Program
{
    public static void Main(string[] args)
    {
        BuildWebHost(args).Run();
    }

    public static IWebHost BuildWebHost(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>() // Configures the application using Startup.cs
            .Build();
}

Accessing the application

By default, the application will be available at: http://localhost:3000.

Default Configuration Overview

Out of the box, the application is configured to connect to a public, read-only Contentful space. This configuration is located in appsettings.json and is loaded at runtime.

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

The Startup.cs class uses this configuration to register the Contentful client with the dependency injection container.

// TheExampleApp/Startup.cs - in ConfigureServices method
public void ConfigureServices(IServiceCollection services)
{
    // ... other services
    services.AddContentful(Configuration);
    // ...
}

To enable full read/write capabilities and test content editing workflows, you must set up your own Contentful space and update these settings. For detailed instructions, refer to the Contentful Setup Guide and the general Application Settings documentation.

Verify installation

After running the application, you can verify that the local setup is working correctly.

1. Open your web browser and navigate to http://localhost:3000.
2. Confirm content is displayed: You should see the example application's homepage, populated with course content. This confirms that the application is successfully connecting to the default Contentful space and rendering the content via Razor views.
3. Test Editorial Features: To simulate an editor's experience, navigate to http://localhost:3000?editorial_features=enabled. This URL flag enables UI indicators for draft content and adds "Edit" buttons that link to the Contentful web app. Note that the "Edit" buttons will only function correctly if you have configured the app with your own read/write Contentful space.

Common Troubleshooting

If the application fails to start or run correctly, consider the following common issues:

• Port Conflict: If another service is using port 3000, the application will fail to start. You can configure a different port in the Properties/launchSettings.json file (you may need to create this file if it doesn't exist) or by using command-line arguments.
• .NET Core SDK Version: This project targets .NET Core 2.1 (<TargetFramework>netcoreapp2.1</TargetFramework>). You must have the .NET Core 2.1 SDK installed. If you only have a newer version (e.g., .NET 6.0), the build may fail.
• Contentful API Errors: If the default read-only API keys have been rotated or are otherwise invalid, the application will throw errors when trying to fetch content. You will see an exception page or the application's custom error page. To resolve this, follow the Contentful Setup Guide to create and configure your own space and keys.

For a more extensive list of potential problems and solutions, please consult the Common Issues documentation.