Getting Started with Agility CMS and .NET

This guide walks you through setting up your first Agility CMS website using .NET. By the end, you'll have a fully functional site running locally with content from your Agility CMS instance.

Prerequisites

Before you begin, ensure you have:

• .NET SDK 8.0 or higher - Download .NET
• Node.js - Download Node.js (required for Tailwind CSS)
• An Agility CMS account - Sign up free

Step 1: Get Your API Keys

1. Log in to Agility CMS
2. Navigate to Settings > API Keys
3. Note down the following values:
   • Instance GUID - Your unique instance identifier
   • Security Key - Used for preview mode authentication
   • Fetch API Key - For accessing published content (starts with defaultlive)
   • Preview API Key - For accessing draft content (starts with defaultpreview)

Step 2: Clone the Starter Repository

git clone https://github.com/agility/agilitycms-dotnet-starter.git
cd agilitycms-dotnet-starter

Choose your preferred starter:

# For Blazor SSR (recommended for modern apps)
cd Agility.NET.Blazor.Starter

# Or for MVC/Razor Pages (traditional approach)
cd Agility.NET.MVC.Starter

Step 3: Configure Your Credentials

Create a file named appsettings.local.json in the project root:

{
  "AppSettings": {
    "InstanceGUID": "your-instance-guid",
    "SecurityKey": "your-security-key",
    "FetchAPIKey": "defaultlive.your-fetch-api-key",
    "PreviewAPIKey": "defaultpreview.your-preview-api-key"
  }
}

Security Note: The appsettings.local.json file is gitignored and won't be committed to version control. Never commit API keys to your repository.

Step 4: Install Dependencies

# Install .NET dependencies
dotnet restore

# Install Node dependencies (for Tailwind CSS)
npm install

Step 5: Run the Site

# Run with hot reload
dotnet watch

Your site will be available at http://localhost:5000.

What's Next?

Now that your site is running, explore these topics:

Understand the Architecture

• How Pages Work - Learn how Agility's sitemap drives page routing
• How Components Work - Build reusable content modules
• How Page Models Work - Define page layouts and zones

Choose Your Starter

• Blazor SSR Starter - Deep dive into the Blazor implementation
• MVC Starter - Deep dive into the MVC/Razor Pages implementation

Build Features

• Fetching Content - Query content using REST and GraphQL
• Configuration - Environment variables and caching

Go to Production

• Deploy to Azure - One-click deployment guide

Troubleshooting

"No pages found" or blank site

1. Verify your API keys are correct in appsettings.local.json
2. Ensure your Agility instance has published pages
3. Check that ChannelName matches your sitemap channel (default: website)

403 Errors

Clear browser cookies for localhost or hard refresh (Ctrl+Shift+R / Cmd+Shift+R).

CSS not loading

Run npm install to install Tailwind dependencies, then restart dotnet watch.

Preview mode not working

1. Verify your SecurityKey is correct
2. Check the preview URL includes the correct agilitypreviewkey parameter
3. In development, preview mode is always enabled automatically

Project Structure Overview

Both starters follow a similar structure:

├── Components/ or ViewComponents/   # Content modules
├── Models/                          # Content type definitions
├── Middleware/                      # URL redirects, caching
├── Services/                        # Agility API integration
├── appsettings.json                # Default configuration
├── appsettings.local.json          # Your API credentials (gitignored)
└── Program.cs                       # Application setup

See the starter-specific guides for detailed structure documentation:

• Blazor SSR Structure
• MVC Structure