Skip to main content
Optimizely Academy

End-user eLearning

Upcoming events

Certification

Partner training

Community

All Topics

ASP.NET Core Identity

  • By Optimizely Education
  • Published: Mar 3, 2026
  • Rating
    Average rating: 0 No reviews

Outline
At a glance:
  • Goal: Get a repeatable local setup (Windows/macOS) and understand DXP Cloud considerations.
  • Core stack: .NET SDK, IDE, SQL Server, Optimizely templates and CLI, NuGet feed.
  • macOS note: SQL Server typically runs via Docker.
  • DXP note: Secrets and services are managed; local dev integrates with them.

Introduction

Setting up an efficient development environment is the cornerstone of successful Optimizely CMS 12 projects. This guide provides a step-by-step walkthrough for developers to configure their local machines for Optimizely CMS 12 development on both Windows and macOS, and covers key considerations for working with the Optimizely Digital Experience Platform (DXP) Cloud.

1. Prerequisites (all platforms)

Before diving into the setup, ensure you have the following core components:

  • .NET SDK: Install the latest Long Term Support (LTS) version (.NET 8 SDK). This includes the .NET runtime and CLI tools.
  • IDE: Visual Studio 2022 on Windows (select the "ASP.NET and web development" and ".NET desktop development" workloads); Visual Studio Code with the C# extension on macOS.
  • SQL Server: SQL Server Express or Developer Edition on Windows. On macOS, SQL Server runs via Docker Desktop.
  • Optimizely NuGet feed: Ensure your NuGet configuration includes https://nuget.optimizely.com/feed/packages.svc/. This is typically added automatically when installing templates.
  • Optimizely templates and CLI tool: Required for creating new projects and managing CMS-specific tasks.
Bash
# Install Optimizely project templates dotnet new -i EPiServer.Templates # Install Optimizely CLI Tool dotnet tool install EPiServer.Net.Cli --global --add-source https://nuget.optimizely.com/feed/packages.svc/

Note: The latest versions of EPiServer.Templates and the CLI tool require .NET 6 or higher.

2. Local setup: Windows

Follow these steps to set up your Optimizely CMS 12 development environment on Windows.

Windows setup steps

Select a step to expand and read the details.

Step 1: Install .NET SDK and Visual Studio 2022 ▼
  1. Download and install the latest .NET LTS SDK.
  2. Download and install Visual Studio 2022. During installation, select the "ASP.NET and web development" and ".NET desktop development" workloads.
Step 2: Install and configure SQL Server ▼
  1. Download and install SQL Server Express or Developer Edition.
  2. During installation, ensure Mixed Mode Authentication is selected and set a strong password for the sa account.
  3. Install SQL Server Management Studio (SSMS) for database management.
  4. Verify SQL Server is running and accessible.
Step 3: Install Optimizely templates and CLI tool ▼

Run the following in a command prompt or PowerShell:

Bash
dotnet new -i EPiServer.Templates dotnet tool install EPiServer.Net.Cli --global --add-source https://nuget.optimizely.com/feed/packages.svc/
Step 4: Create a new CMS 12 project ▼

Navigate to your desired development directory and scaffold a new empty CMS project:

Bash
mkdir C:\Projects\MyOptimizelySite cd C:\Projects\MyOptimizelySite dotnet new epicmsempty --name MyOptimizelyCmsProject cd MyOptimizelyCmsProject
Step 5: Configure hostname (optional - IIS only) ▼

For a custom local domain (e.g., mylocalcms.local), open Notepad as Administrator, navigate to C:\Windows\System32\drivers\etc\hosts, and add:

Bash
127.0.0.1 mylocalcms.local
Step 6: Set up IIS (optional - production-like local testing) ▼
  1. Enable IIS features: Go to "Turn Windows features on or off" and enable "Internet Information Services" along with "ASP.NET 4.8" and "ASP.NET Core" components.
  2. Install .NET Core Hosting Bundle: Download and install the latest bundle for your .NET SDK version. This installs the ASP.NET Core Module for IIS.
  3. Create IIS website: Open IIS Manager, right-click Sites, choose Add Website, set the physical path to your project root, and set the host name to mylocalcms.local.
  4. Configure application pool: Set ".NET CLR Version" to "No Managed Code". Ensure the identity has appropriate permissions.
  5. Set folder permissions: Grant read/write permissions to the IIS AppPool identity on your project folder, especially App_Data and wwwroot.
Step 7: Create the CMS database ▼

Use the Optimizely CLI to create and initialise the CMS database. Replace -S, -U, and -P with your SQL Server instance name, username, and password:

Bash
dotnet-episerver create-cms-database MyOptimizelyCmsProject.csproj -S .\SQLEXPRESS -U sa -P "YourStrongPassword"
Step 8: Create an administrator user ▼
  1. Add a class (e.g., UsersInstaller.cs) implementing IFirstRequestInitializer that creates a default admin user. Optimizely provides examples in their sample projects.
  2. Register the initializer in Program.cs in the ConfigureServices method.
  3. After the first run, remove or comment out the initializer for security. Default credentials are typically admin@example.com / Episerver123!.
Step 9: Run the application ▼
  • Via Kestrel (default): Run dotnet run from your project root. The application starts on http://localhost:5000.
  • Via IIS: Browse to http://mylocalcms.local.
  • Access the CMS editorial interface at /episerver/cms and log in with your admin credentials.

3. Local setup: macOS

Follow these steps to set up your Optimizely CMS 12 development environment on macOS.

macOS setup steps

Select a step to expand and read the details.

Step 1: Install .NET SDK and Visual Studio Code ▼
  1. Download and install the latest .NET LTS SDK.
  2. Download and install Visual Studio Code.
  3. Install the C# extension for Visual Studio Code from the Extensions marketplace.
Step 2: Install and configure SQL Server (via Docker) ▼

SQL Server does not run natively on macOS - Docker is the recommended approach.

  1. Install Docker Desktop for Mac.
  2. Pull the SQL Server image:
    Bash
    docker pull mcr.microsoft.com/mssql/server:2019-latest
  3. Run the SQL Server container. Use a strong password for SA_PASSWORD:
    Bash
    docker run -e "ACCEPT_EULA=Y" -e "SA_PASSWORD=YourStrongPasswordHere" -p 1433:1433 --name sqlserver -d mcr.microsoft.com/mssql/server:2019-latest
  4. Install Azure Data Studio and connect to localhost,1433 using the sa account.
Step 3: Install Optimizely templates and CLI tool ▼
Bash
dotnet new -i EPiServer.Templates dotnet tool install EPiServer.Net.Cli --global --add-source https://nuget.optimizely.com/feed/packages.svc/
Step 4: Create a new CMS 12 project ▼
Bash
mkdir ~/Projects/MyOptimizelySite cd ~/Projects/MyOptimizelySite dotnet new epicmsempty --name MyOptimizelyCmsProject cd MyOptimizelyCmsProject
Step 5: Create the CMS database ▼

The server is typically localhost when using Docker:

Bash
dotnet-episerver create-cms-database MyOptimizelyCmsProject.csproj -S localhost -U sa -P "YourStrongPasswordHere"
Step 6: Create an administrator user ▼

Implement an IFirstRequestInitializer to create a default admin user and register it in Program.cs. After the first successful run, remove or comment out the initializer for security.

Step 7: Run the application ▼

Run dotnet run from your project root. The application typically starts on http://localhost:5000. Access the editorial UI at http://localhost:5000/episerver/cms.

4. DXP Cloud development considerations

When working with Optimizely CMS 12 on the DXP Cloud, your local development environment integrates with managed cloud services.

DXP at a glance:
  • Environments: Integration, Preproduction, Production.
  • Deployments: Usually via CI/CD (Azure DevOps / GitHub Actions).
  • Secrets: Managed in the DXP Portal and override appsettings.
  • Managed services: App Service, Azure SQL, Blob Storage, Cognitive Search.

DXP Cloud topics

Select a topic to expand and read the details.

DXP environments ▼
  • Integration: Your primary development and testing environment.
  • Preproduction: A staging environment for final testing before live deployment.
  • Production: The live environment serving your customers.
Deployment via CI/CD ▼

Deployments to DXP environments are typically handled via CI/CD pipelines configured in Azure DevOps or GitHub Actions. Your local development focuses on building and testing code that will eventually be pushed to these pipelines.

Secrets management ▼

Sensitive settings (connection strings, API keys) are managed securely in the DXP Portal for cloud environments and override corresponding values in appsettings.json. For local development use:

  • appsettings.Development.json for non-sensitive local settings.
  • User secrets for sensitive local secrets that should not be committed to source control.
  • Environment variables as another option, especially in containerised environments.
Database synchronisation ▼

For local development, you often need a copy of the DXP database. Optimizely DXP provides tools through the self-service portal to download database backups from your Integration environment. You can restore this backup to your local SQL Server instance to work with production-like data. Similarly, local database changes can be pushed back to the Integration environment.

Azure managed services ▼

The DXP Cloud leverages managed Azure services for your CMS 12 application:

  • Azure App Service: For hosting your web application.
  • Azure SQL Database: For the CMS database.
  • Azure Blob Storage: For media and assets.
  • Azure Cognitive Search: For Optimizely Search and Navigation.

Conclusion

A well-configured development environment is paramount for effective Optimizely CMS 12 development. By following these step-by-step guides for Windows and macOS, developers can establish robust local setups. Understanding the integration points and considerations for the Optimizely DXP Cloud ensures a smooth transition from local development to cloud-hosted environments.