Prerequisites

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

This document outlines the system, software, and tooling prerequisites for developing and maintaining the TheExampleApp application. Adhering to these requirements will ensure a consistent and stable development environment, minimizing issues related to dependency mismatches.

System requirements

The application is built on the .NET Core framework, which is cross-platform. It can be developed and run on Windows, macOS, and Linux. The primary system requirement is the .NET Core runtime and SDK, which have specific version constraints.

The project is explicitly targeted to .NET Core 2.1, as defined in the project file TheExampleApp.csproj:

<!-- TheExampleApp/TheExampleApp.csproj -->
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
  </PropertyGroup>
  ...
</Project>

Key Versioning Details:

| Component | Version | Source / Rationale - | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | .NET Core Target | netcoreapp2.1 | Defined in TheExampleApp.csproj. This is a Long-Term Support (LTS) release, but it has reached its end-of-life. - | | ASP.NET Core | 2.1.5 | The Microsoft.AspNetCore.All metapackage version specified in TheExampleApp.csproj. This bundles the MVC framework, Kestrel server, and other essential libraries. |

Gotcha: End-of-Life Framework As of August 21, 2021, .NET Core 2.1 is no longer supported by Microsoft. The README.md also notes the repository is unmaintained as of January 2023. While the application will still function with the specified SDK, developers should be aware that they will not receive security updates for the framework. Any future development should prioritize migrating the project to a supported .NET LTS version (e.g., .NET 6 or .NET 8).

Required software

To clone, build, and run the application locally, the following software must be installed on your development machine.

.NET Core SDK

The .NET Core 2.1 SDK is required to build and run the project. While newer SDKs can often build older target frameworks, using the original 2.1 SDK is recommended to ensure maximum compatibility and avoid potential build-time or runtime issues.

• Required Version: SDK 2.1.x
• Download: Download .NET Core 2.1 (select the SDK for your OS)

The Dockerfile further confirms this dependency for containerized builds:

# Dockerfile
FROM microsoft/dotnet:2.1-sdk AS builder
...
FROM microsoft/aspnetcore:2.1
...

Git

A Git client is necessary to clone the source code repository.

• Installation: https://git-scm.com/downloads

Code Editor or IDE

While any text editor can be used, an IDE that understands .NET solutions and projects is highly recommended for an efficient development workflow.

• Recommended: Visual Studio 2017. The solution file (TheExampleApp.sln) was created with this version, ensuring the best out-of-the-box experience.

  # TheExampleApp.sln
  Microsoft Visual Studio Solution File, Format Version 12.00
  # Visual Studio 15
  VisualStudioVersion = 15.0.27110.0

• Alternative: Visual Studio Code with the C# Dev Kit extension. This is a modern, cross-platform option that provides excellent support for C# and .NET projects.

The solution contains multiple projects (main application, unit tests, integration tests, and E2E tests), making a full-featured IDE particularly useful for running tests and managing the overall structure.

For a step-by-step guide on building and running the application after installing these tools, please refer to the Local Setup Guide.

Optional tools

The following tools are not strictly required to run the application in its default read-only state but are essential for certain workflows, such as content editing or containerized deployment.

Contentful CLI

The application is designed to run in two modes:

1. Read-Only Mode: Uses a default, public Contentful space. No setup is required.
2. Read/Write Mode (Recommended): Connects to your own private Contentful space, allowing you to edit content and see changes reflected in the app.

To enable the full end-to-end Contentful experience with read/write mode, you must use the Contentful CLI to create and seed a new space with the required content model.

• Purpose: To create a personal Contentful space and populate it with the example content, enabling content editing in the Contentful web app and seeing how changes propagate to the application.
• Installation: The CLI is an npm package. You will need Node.js and npm installed.

  npm install -g contentful-cli

• Usage: Follow the instructions in the Contentful Configuration guide to set up your space and update the appsettings.json file.

The default configuration in appsettings.json points to the read-only space:

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

Docker

The repository includes a Dockerfile for building and running the application in a container. This is an excellent option for isolating the application and its dependencies, ensuring consistency between development and production environments.

• Purpose: To build a container image and run the application without needing to install the .NET SDK on the host machine.
• Installation: Docker Desktop
• Usage: For detailed instructions on building and running the Docker container, see the Docker Deployment Guide.

Bower

Note: Deprecated Tool The project contains a bower.json file, but it lists no dependencies. The tech stack analysis confirms that Bower was the intended tool for frontend package management. However, in its current state, the project does not use it to manage any client-side libraries. Developers should be aware that this tool is deprecated and not required for the current codebase. Do not attempt to run bower install as it will have no effect.