File structure reference

This document provides a detailed technical breakdown of the TheExampleApp solution's file and directory structure. Understanding this structure is essential for navigating the codebase, locating relevant files, and maintaining the application's architecture. For a higher-level view of how these components fit together, see the Project Structure Overview.

Complete file listing

The solution is organized into a root directory containing configuration and solution files, a primary web application project, and three distinct test projects. This separation of concerns is a standard practice in the .NET ecosystem, promoting modularity and maintainability.

.
├── .circleci/
│   └── config.yml
├── TheExampleApp/
│   ├── Configuration/
│   ├── Models/
│   ├── Pages/
│   ├── TagHelpers/
│   ├── ViewComponents/
│   ├── Views/
│   │   └── Shared/
│   ├── wwwroot/
│   │   ├── images/
│   │   ├── fonts/
│   │   ├── locales/
│   │   ├── scripts/
│   │   └── stylesheets/
│   └── TheExampleApp.csproj
├── TheExampleApp.E2eTests/
├── TheExampleApp.IntegrationTests/
├── TheExampleApp.Tests/
├── .gitignore
├── app.json
├── cypress.json
├── Dockerfile
├── README.md
└── TheExampleApp.sln

Root files

These files at the root of the repository manage the overall solution, dependencies, containerization, and CI/CD pipeline.

• TheExampleApp.sln: The Visual Studio Solution file. It acts as a container for all projects within the repository, defining their relationships and build configurations. It references the main web application and all associated test projects.

  // TheExampleApp.sln
  Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "TheExampleApp", "TheExampleApp\TheExampleApp.csproj", "{D458F723-7F2E-469E-97F8-F4279427B796}"
  EndProject
  Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "TheExampleApp.Tests", "TheExampleApp.Tests\TheExampleApp.Tests.csproj", "{A27BBEDC-DC3F-46FA-92C6-BD531959E449}"
  EndProject
  Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "TheExampleApp.IntegrationTests", "TheExampleApp.IntegrationTests\TheExampleApp.IntegrationTests.csproj", "{5F2776FA-6986-4472-B0C6-615A74D99634}"
  EndProject
  Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TheExampleApp.E2eTests", "TheExampleApp.E2eTests\TheExampleApp.E2eTests.csproj", "{BC150835-FDBF-47E6-9937-F44B3B46C568}"
  EndProject

• README.md: The primary entry point for developers. It contains a project overview, setup instructions for both read-only and read-write access to Contentful, and deployment guides. For a streamlined setup process, refer to the official Local Setup Guide.

• Dockerfile: Defines a multi-stage Docker build process for containerizing the application.

  • Stage 1 (builder): Uses the full .NET Core SDK image (microsoft/dotnet:2.1-sdk) to restore dependencies and publish a release build of the application.
  • Stage 2 (final): Uses the lightweight ASP.NET Core runtime image (microsoft/aspnetcore:2.) and copies the published application from the builder stage. This results in a smaller, more secure production image.
  • Note: The ASPNETCORE_ENVIRONMENT is explicitly set to Heroku, which may load a specific appsettings.Heroku.json configuration if present.

  FROM microsoft/dotnet:2.1-sdk AS builder
  WORKDIR /src
  
  COPY . .
  RUN dotnet restore
  RUN dotnet publish -c Release -o /app/
  
  FROM microsoft/aspnetcore:2.
  WORKDIR /app
  ENV ASPNETCORE_ENVIRONMENT=Heroku
  COPY --from=builder /app .
  ENTRYPOINT ["dotnet", "TheExampleApp.dll"]

• .circleci/config.yml: Configuration for the CircleCI continuous integration and deployment pipeline. This file automates the build, test, and deployment processes triggered by code commits.

• app.json: A manifest file used by the Heroku platform for automated setup and deployment via the "Deploy to Heroku" button in the README.md.

• cypress.json: The configuration file for the Cypress end-to-end testing framework, used by the TheExampleApp.E2eTests project.

TheExampleApp project

This is the main ASP.NET Core 2.1 web application project (Microsoft.NET.Sdk.Web). It handles all server-side logic, content fetching from Contentful, and HTML rendering. For a complete list of libraries and versions, see the Dependencies Reference.

The project file, TheExampleApp.csproj, defines the target framework and key dependencies.

<!-- TheExampleApp/TheExampleApp.csproj -->
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <!-- Locale files removed from standard content handling (will be embedded) -->
    <Content Remove="wwwroot\locales\de-DE.json" />
    <Content Remove="wwwroot\locales\en-US.json" />
  </ItemGroup>
  <ItemGroup>
    <!-- SDK for fetching content from the Contentful headless CMS -->
    <PackageReference Include="contentful.aspnetcore" Version="3.3.6" />
    <!-- Library for parsing and rendering Markdown -->
    <PackageReference Include="Markdig" Version="0.15.4" />
    <!-- Metapackage for ASP.NET Core MVC, Kestrel, etc. -->
    <PackageReference Include="Microsoft.AspNetCore.All" Version="2.1.5" />
    <!-- Razor language services for view compilation -->
    <PackageReference Include="Microsoft.AspNetCore.Razor.Language" Version="2.1.2" />
    <!-- Code generation tools for scaffolding during development -->
    <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.1.5" />
  </ItemGroup>
  <ItemGroup>
    <!-- CLI tool reference for code generation -->
    <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.0" />
  </ItemGroup>
  <ItemGroup>
    <!-- Locale files are embedded into the assembly for runtime access -->
    <EmbeddedResource Include="wwwroot\locales\de-DE.json" />
    <EmbeddedResource Include="wwwroot\locales\en-US.json" />
  </ItemGroup>
  <ItemGroup>
    <!-- Static SVG assets -->
    <None Include="wwwroot\images\badge-app-store.svg" />
    <None Include="wwwroot\images\badge-google-play.svg" />
    <None Include="wwwroot\images\contentful-logo.svg" />
    <None Include="wwwroot\images\logo-node.svg" />
  </ItemGroup>
</Project>

• Configuration/: Contains strongly-typed C# classes that map to configuration values in appsettings.json. This follows the ASP.NET Core Options pattern, providing compile-time safety and IntelliSense for accessing settings like Contentful API keys and Space ID.

• Models/: Defines the C# Plain Old CLR Objects (POCOs) that represent the content models (content types) in Contentful. The contentful.aspnetcore SDK uses these classes to deserialize the JSON responses from the Contentful API into strongly-typed objects.

• Pages/: The core of the application's UI and routing, built using the Razor Pages framework. Each page consists of:

  • A .cshtml file for the Razor view, containing HTML markup and embedded C# for rendering dynamic content.
  • A .cshtml.cs file for the PageModel, which contains the C# logic for handling HTTP requests, fetching data from services (like the Contentful client), and preparing data for the view.

• ViewComponents/: Contains reusable, self-contained UI components that encapsulate both rendering logic (a Razor view) and backend logic (a C# class). These are ideal for complex UI elements that need to fetch their own data, such as a dynamic navigation menu or a sidebar.

• Views/Shared/: Holds shared Razor layout files, partial views, and templates used across multiple pages. The _Layout.cshtml file, which defines the main HTML structure (including <head> and <body> tags) for the entire site, is the most important file here.

• TagHelpers/: Home to custom Tag Helpers, which extend HTML elements with server-side functionality. For example, a custom <markdown> tag helper could be implemented here to invoke the Markdig library, allowing developers to render Markdown content from Contentful directly in a Razor view with a simple, declarative syntax.

• wwwroot/: The web-servable root directory for all static client-side assets.

  • locales/: Contains en-US.json and de-DE.json files for internationalization (i18n). As specified in the .csproj file, these are treated as EmbeddedResources, meaning they are compiled directly into the application's DLL. This allows the localization service to access them at runtime without needing to read them from the file system.
  • images/, fonts/, stylesheets/, scripts/: Standard directories for static assets. The scripts/ directory contains vanilla JavaScript for client-side interactivity, as the project does not use a major JavaScript framework.

Test projects

The solution includes a comprehensive testing suite divided into three projects, each targeting a different level of testing. For a detailed guide on running these tests, refer to the Testing Overview.

• TheExampleApp.Tests/: The Unit Test project.

  • Purpose: To test individual units of code (methods and classes) in complete isolation from external dependencies.
  • Tooling: Uses xUnit as the test framework and Moq as the mocking library to simulate dependencies like the Contentful client.
  • Example: A unit test might verify that a PageModel's method correctly processes data without actually making an HTTP call to the Contentful API.

  <!-- TheExampleApp.Tests/TheExampleApp.Tests.csproj -->
  <Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
      <TargetFramework>netcoreapp2.1</TargetFramework>
      <IsPackable>false</IsPackable>
    </PropertyGroup>
    <ItemGroup>
      <PackageReference Include="Microsoft.NET.Test.Sdk" Version="15.5.0" />
      <PackageReference Include="Moq" Version="4.7.145" />
      <PackageReference Include="xunit" Version="2.3.1" />
      <PackageReference Include="xunit.runner.visualstudio" Version="2.3.1" />
    </ItemGroup>
    <ItemGroup>
      <ProjectReference Include="..\TheExampleApp\TheExampleApp.csproj" />
    </ItemGroup>
  </Project>

• TheExampleApp.IntegrationTests/: The Integration Test project.

  • Purpose: To test how different components of the application work together. It uses the Microsoft.AspNetCore.Mvc.Testing library to host the application in-memory and make HTTP requests to its endpoints.
  • Example: An integration test could send a request to the /courses page and assert that the application correctly invokes the Contentful service (which would be mocked at the DI container level) and renders the expected HTML response with a 200 OK status code.

• TheExampleApp.E2eTests/: The End-to-End (E2E) Test project.

  • Purpose: To validate complete user flows from the perspective of the user. These tests run against a fully deployed instance of the application.
  • Tooling: Uses Cypress to automate a real web browser, simulating user actions like clicking buttons, filling out forms, and navigating between pages.
  • Example: An E2E test might navigate to the homepage, click on a course, verify the course details are displayed, and then check that the "Edit in Contentful" button (if present) links to the correct URL.