Skip to main content
Optimizely Academy

End-user eLearning

Upcoming events

Certification

Partner training

Community

All Topics

.NET 8 and ASP.NET Basics

  • By Optimizely Education
  • Published: Feb 2, 2026
  • Rating
    Average rating: 0 No reviews

Outline
At a glance:
  • Platform: .NET 8 and ASP.NET Core
  • Target CMS: Optimizely CMS 12
  • Focus: Middleware pipeline, configuration, and PaaS development
  • Audience: Developers familiar with .NET and web fundamentals

Introduction

For developers venturing into Optimizely CMS 12, understanding the underlying technology stack is crucial. CMS 12 is built on ASP.NET Core, leveraging the powerful and modern .NET platform. This guide explores the .NET 8 foundation and the fundamental concepts of the ASP.NET Core request pipeline, providing a technical overview for newcomers to Optimizely's PaaS CMS.

Although CMS 12 initially targeted .NET 6 (an LTS release), the unified .NET platform ensures forward compatibility. Applications built on .NET 6 can run seamlessly on .NET 8, often without code changes, benefiting from improved performance and new features.

1. .NET 8 Foundation: A Modern Platform for Web Applications

.NET 8 is the latest Long Term Support (LTS) release of the .NET platform, offering major improvements in performance, productivity, and cross-platform capabilities. It provides a robust runtime for building modern web applications, including those powered by Optimizely CMS 12.

1.1 Key Aspects of .NET 8

  • Performance Improvements: Faster startup times, reduced memory consumption, and higher throughput via runtime, GC, JIT, and core library enhancements.
  • Cross-Platform: Runs on Windows, Linux, and macOS - critical for cloud-native deployments.
  • Unified Platform: Consolidates .NET flavors into a single framework, simplifying development and deployment.
  • Simplified Program.cs and Application Startup: Combines Startup.cs logic and the main entry point into a single file.

Application Startup Lifecycle

Select a stage to expand and read the details.

WebApplicationBuilder ▼

Initializes the configuration system, logging providers, and the dependency injection container. This is the entry point for wiring up all application infrastructure before the app starts handling requests.

Configuring Services (builder.Services) ▼

Register services such as database contexts, authentication providers, and CMS components into the DI container. Each registration uses one of three lifetimes:

  • Singleton: A single shared instance for the entire application lifetime.
  • Scoped: A new instance created per HTTP request.
  • Transient: A new instance created every time the service is requested.
Building the Application (builder.Build()) ▼

Finalizes all registered services and prepares the WebApplication object. After this point no further service registrations can be made - the DI container is effectively locked.

Middleware Pipeline (app.Use..., app.Map..., app.Run...) ▼

Defines the ordered sequence of middleware components that handle incoming HTTP requests. Each component can inspect, modify, or short-circuit the request before passing it to the next component in the chain. Order is critical - see Section 2 for details.

Running the App (app.Run()) ▼

Starts the web server (Kestrel by default) and begins listening for incoming HTTP requests. This is a blocking call - the application runs until it is shut down or the process is terminated.

1.2 Configuration in .NET 8

.NET 8 uses a hierarchical configuration system that allows environment-specific overrides. Sources are applied in this order, with later sources taking precedence:

  • appsettings.json (base defaults)
  • appsettings.{EnvironmentName}.json (e.g., appsettings.Development.json)
  • Environment variables
  • Command-line arguments
  • Azure Key Vault (for secure secrets in production)

Access configuration throughout your application via IConfiguration for direct key lookup, or via strongly-typed IOptions<T> for structured settings classes.

1.3 Minimal APIs

Minimal APIs allow lightweight HTTP endpoint definitions to be declared directly in Program.cs without full MVC controller scaffolding. They are ideal for microservices, webhooks, or simple API endpoints alongside a CMS 12 application.

2. ASP.NET Core Request Pipeline Basics: Middleware in Action

The ASP.NET Core request pipeline is a sequence of middleware components that process HTTP requests and responses. Each component can inspect or modify the request, pass it to the next component, or terminate the pipeline entirely. Order matters - incorrect ordering is one of the most common sources of subtle bugs in ASP.NET Core applications.

2.1 Understanding Middleware

Each middleware component in the pipeline can do two things:

  • Pass the request to the next component in the chain.
  • Perform logic before and/or after the next component executes, allowing it to inspect or modify both the incoming request and the outgoing response.

2.2 Configuring the Pipeline: Use, Run, Map

Pipeline Configuration Methods

Select a method to expand and read the details.

Use - Pass-through middleware ▼

Can run logic before or after the next middleware. Calls await next.Invoke() to pass control to the next component. Most middleware is registered with Use.

Run - Terminal middleware ▼

Terminal middleware that does not call the next component. It ends the pipeline and writes a response directly. Use this for fallback handlers or when you want to guarantee no further middleware executes.

Map - Branching by path or condition ▼

Branches the pipeline based on a URL path (e.g., app.Map("/admin", ...)), useful for isolating admin routes or custom sub-applications. MapWhen extends this to branch by any arbitrary condition on the request context.

2.3 Importance of Middleware Order

Middleware must be registered in the correct order. The recommended sequence for a typical ASP.NET Core application is:

  • Exception Handling: Register first (e.g., UseExceptionHandler) so it can catch errors thrown by any subsequent middleware.
  • HTTPS Redirection: Before any response-generating middleware to ensure all traffic is secured.
  • Static Files: Early in the pipeline for efficient serving and to short-circuit requests for assets before auth checks.
  • Authentication and Authorization: UseAuthentication must come before UseAuthorization, and both must come before endpoint execution.
  • Routing: UseRouting followed by UseEndpoints or MapControllers at the end of the chain.

Important: Placing UseAuthorization before UseAuthentication is a common mistake that results in authorization decisions being made without an established user identity.

2.4 Common Middleware Components

These are the most frequently used built-in middleware components in a CMS 12 application:

  • app.UseDeveloperExceptionPage() - Detailed error pages (development only)
  • app.UseExceptionHandler("/Error") - Friendly error pages (production)
  • app.UseHsts() - Enforces HTTP Strict Transport Security headers
  • app.UseHttpsRedirection() - Redirects HTTP requests to HTTPS
  • app.UseStaticFiles() - Serves files from wwwroot
  • app.UseRouting() - Enables route matching for endpoints
  • app.UseAuthentication() - Identifies the current user from credentials
  • app.UseAuthorization() - Enforces access policies on identified users
  • app.UseSession() - Enables server-side session state

2.5 Short-Circuiting the Pipeline (.NET 8)

.NET 8 introduces Short-Circuit Routing, which allows specific endpoints - such as /robots.txt or /health - to bypass the full middleware pipeline for faster responses. Use .ShortCircuit() on a mapped endpoint to opt it out of downstream middleware processing.

3. How Optimizely CMS 12 Leverages This

Optimizely CMS 12 plugs directly into the ASP.NET Core pipeline and DI system, using these foundations to provide its editorial and delivery capabilities:

  • Content Routing: CMS middleware resolves incoming URLs to the correct pages and blocks based on the content tree.
  • UI Initialization: Sets up editorial context and scoped services required by the CMS editing interface on each request.
  • Personalization: Integrates the Optimizely personalization engine into the request pipeline for dynamic content delivery.

Core CMS services such as IContentRepository and IContentTypeRepository are registered in the DI container and are available for injection anywhere in your application - controllers, view components, services, and middleware alike.

CMS-specific configuration integrates seamlessly with the standard appsettings.json and environment variable system, meaning DXP Cloud secrets automatically override local settings without any custom plumbing.

4. Developer Tools and Workflow

The following tools form the standard development workflow for a CMS 12 project:

  • Visual Studio / VS Code: Full-featured IDEs providing debugging, IntelliSense, project management, and integrated test runners.
  • .NET CLI: Command-line tool for building, running, testing, and publishing applications. Essential for CI/CD pipelines and scripted workflows.
  • NuGet: Package manager for consuming and managing Optimizely CMS SDKs, third-party libraries, and internal shared packages.
  • Local Development Database: SQL Server (Windows) or SQL Server via Docker (macOS/Linux) for a local CMS database instance mirroring the DXP cloud environment.

Conclusion

The .NET 8 foundation and ASP.NET Core pipeline are key to developing effectively with Optimizely CMS 12. A solid understanding of middleware ordering, the DI container, and the application startup lifecycle enables you to build scalable, maintainable, and cloud-native CMS applications with confidence.