Orchard Core Setup - Prompt Templates

Create and Set Up an Orchard Core Application

You are an Orchard Core expert. Generate project setup instructions and configuration for Orchard Core web applications.

Guidelines

• Orchard Core applications are ASP.NET Core web apps that reference Orchard Core NuGet packages.
• Use the dotnet new templates or manual project creation.
• The Program.cs file configures Orchard Core services and middleware.
• Setup recipes (Blog, Agency, SaaS, Blank) define the initial site configuration.
• Database providers include Sqlite (default), SqlServer, PostgreSql, and MySql.
• CMS modules are added as NuGet package references in the .csproj file.
• Orchard Core packages ship ConfigurationSchema.json files, so Visual Studio offers IntelliSense and validation for the OrchardCore sections of appsettings.json, including known database providers, setup recipes, time zones, and cultures.
• The Use CDN site setting is disabled after setup so resources load without internet access; enable it afterwards if wanted.
• Always seal classes defined in your module code.

Creating a New Orchard Core Web Application

# Install the Orchard Core templates
dotnet new install OrchardCore.ProjectTemplates

# Create a new CMS web application
dotnet new occms -n {{ProjectName}}
cd {{ProjectName}}

# Run the application
dotnet run

Manual Project Setup (Without Templates)

Create a new ASP.NET Core web application:

dotnet new web -n {{ProjectName}}
cd {{ProjectName}}

# Add the Orchard Core CMS package
dotnet add package OrchardCore.Application.Cms.Targets --version 3.*

Program.cs Configuration

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOrchardCms();

var app = builder.Build();

app.UseStaticFiles();
app.UseOrchardCore();

app.Run();

Program.cs with Additional CMS Configuration

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddOrchardCms()
    .AddSetupFeatures("OrchardCore.AutoSetup")
    .ConfigureServices(tenantServices =>
    {
        // Register tenant-level services here
    })
    .Configure((app, routes, services) =>
    {
        // Configure tenant-level middleware here
    });

var app = builder.Build();

app.UseStaticFiles();
app.UseOrchardCore();

app.Run();

Adding CMS Modules to the Project

Add NuGet packages for the modules you need. All modules — whether from OrchardCore directly, Lombiq, or any community source — must be installed in the web project (the startup project of the solution):

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="OrchardCore.Application.Cms.Targets" Version="3.*" />

    <!-- Third-party modules are also added to the web project -->
    <PackageReference Include="Lombiq.HelpfulExtensions.OrchardCore" Version="1.*" />
  </ItemGroup>

</Project>

Adding a Custom CMS Module to the Web Project

To add a local CMS module to the web project (your own or any third-party module):

<ItemGroup>
  <!-- Reference a local module project in the web project -->
  <ProjectReference Include="../MyModule/MyModule.csproj" />
  <ProjectReference Include="../ThirdParty.Module/ThirdParty.Module.csproj" />
</ItemGroup>

Setup via the Admin UI

After running the application, navigate to / to access the setup screen:

1. Choose a Site Name.
2. Select a Recipe (Blog, Agency, SaaS, Blank, or custom).
3. Choose a Database Provider (Sqlite, SQL Server, PostgreSQL, MySQL).
4. Provide the Connection String (except for Sqlite).
5. Set an Admin Username and Password.
6. Click Finish Setup.

If OrchardCore:DatabaseProvider is configured, the provider is fixed and cannot be changed on the Setup screen. If the provider requires a connection string, it remains available unless both OrchardCore:DatabaseProvider and OrchardCore:ConnectionString are configured; in that case the connection string is also fixed and is not editable. Setup requires a connection string only when the selected provider needs one and no saved value exists.

Setup Screen Cultures

Configure the cultures offered by the setup screen under OrchardCore:Setup (the 3.x name OrchardCore_Setup is deprecated):

{
  "OrchardCore": {
    "Setup": {
      "DefaultCulture": "en",
      "SupportedCultures": [ "en", "fr", "de", "es" ]
    }
  }
}

An empty DefaultCulture uses the operating system culture; the invariant culture is not supported.

Recipe Parameters and Configuration Keys

During setup, recipes can read the setup values with [js: parameters('Name')]: SiteName, AdminUserId, AdminUsername, AdminEmail, AdminPassword, DatabaseProvider, DatabaseConnectionString, and DatabaseTablePrefix. Read tenant or host configuration with [js: configuration('Key', 'default')], for example [js: configuration('Admin:AdminUrlPrefix', 'Admin')] for OrchardCore:Admin:AdminUrlPrefix.

{
  "steps": [
    {
      "name": "Settings",
      "SiteName": "[js: parameters('SiteName')]",
      "SuperUser": "[js: parameters('AdminUserId')]"
    }
  ]
}

Auto-Setup via Configuration

Configure automatic setup in appsettings.json under OrchardCore:AutoSetup (see orchardcore-auto-setup):

{
  "OrchardCore": {
    "AutoSetup": {
      "AutoSetupPath": "",
      "Tenants": [
        {
          "ShellName": "Default",
          "SiteName": "{{SiteName}}",
          "SiteTimeZone": "America/New_York",
          "DatabaseProvider": "Sqlite",
          "RecipeName": "Blog",
          "AdminUsername": "admin",
          "AdminEmail": "admin@example.com",
          "AdminPassword": "{{SecurePassword}}"
        }
      ]
    }
  }
}

Recipe files that setup writes to disk go through ITempDirectoryProvider, so set OrchardCore:TempDirectory:Path when the system temp volume is small (see orchardcore-temp-file-storage).

Testing with the Blog Recipe

The Blog recipe sets up a complete blogging site with:

• Blog content type and listing
• Theme (TheBlogTheme)
• Menu and layers configured
• Sample content items

# Create a project and run it
dotnet new occms -n MyBlogSite
cd MyBlogSite
dotnet run

# Navigate to https://localhost:5001
# Select the "Blog" recipe during setup

Creating a Custom Setup Recipe

Place recipe files in the Recipes folder of your module:

{
  "name": "{{RecipeName}}",
  "displayName": "{{DisplayName}}",
  "description": "{{Description}}",
  "author": "{{Author}}",
  "website": "{{Website}}",
  "version": "1.0.0",
  "issetuprecipe": true,
  "categories": ["default"],
  "tags": [],
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "OrchardCore.Contents",
        "OrchardCore.ContentTypes",
        "OrchardCore.Title",
        "OrchardCore.Alias",
        "OrchardCore.Autoroute",
        "OrchardCore.Html",
        "OrchardCore.Menu",
        "OrchardCore.Navigation",
        "OrchardCore.Themes",
        "OrchardCore.Admin",
        "OrchardCore.Settings",
        "TheTheme",
        "TheAdmin"
      ],
      "disable": []
    },
    {
      "name": "Themes",
      "Site": "TheTheme",
      "Admin": "TheAdmin"
    }
  ]
}

Upgrading from 3.x

• Rename OrchardCore_AutoSetup to AutoSetup and OrchardCore_Setup to Setup under the OrchardCore section; the old names are deprecated but still read.