Migration Guide

This guide helps you migrate from older Agility CMS .NET implementations to the modern Blazor or MVC starters.

Overview of Changes

The new .NET starters represent a significant modernization of Agility CMS integration:

Aspect	Legacy (.NET MVC 4/5)	Modern (.NET 10)
Content Access	Content Repository	Fetch API
Page Management	global.asax routes	Middleware + DI
URL Redirects	Built-in, required	Opt-in middleware
Caching	Automatic	Configurable
Content Types	Manual mapping	Typed endpoints
API	REST only	REST + GraphQL

Migration Path

Step 1: Assess Your Current Implementation

Identify what you're using from the legacy SDK:

1. Content Repository - Items(), GetById(), GetItemsByIDs()
2. Page Management - Routes in global.asax
3. URL Redirects - Built-in redirect handling
4. Content Models - Manual class definitions

Step 2: Set Up the New Project

The Blazor and MVC starters target .NET 10, the current long-term support (LTS) release, so install the .NET 10 SDK first. .NET 8 and 9 reach end of support on November 10, 2026, so migrate straight to .NET 10 rather than to an older version.

1. Clone the new starter (Blazor or MVC)
2. Configure your API keys
3. Run locally to verify connection

git clone https://github.com/agility/agilitycms-dotnet-starter.git
cd agilitycms-dotnet-starter/Agility.NET.Blazor.Starter
# Add appsettings.local.json with your keys
dotnet watch

Step 3: Migrate Components

Your biggest task is converting views/components. The content models and logic remain similar.

Migrating Content Access

Before: Content Repository

// Legacy approach
public class BlogController : Controller
{
    public ActionResult Index()
    {
        var repository = new ContentRepository();
        var posts = repository.Items<Post>("posts")
            .Where(p => p.Status == "published")
            .OrderByDescending(p => p.Date)
            .Take(10)
            .ToList();

        return View(posts);
    }

    public ActionResult Detail(int id)
    {
        var repository = new ContentRepository();
        var post = repository.GetById<Post>(id);
        return View(post);
    }
}

After: Fetch API Service

// Modern approach - Blazor
@inject FetchApiService FetchApi

@code {
    private List<Post>? posts;

    protected override async Task OnInitializedAsync()
    {
        posts = await FetchApi.GetTypedContentList<Post>(
            referenceName: "posts",
            locale: "en-us",
            take: 10,
            sort: "fields.date",
            direction: "desc"
        );
    }
}

// Modern approach - MVC
public class BlogController : Controller
{
    private readonly FetchApiService _fetchApi;

    public BlogController(FetchApiService fetchApi)
    {
        _fetchApi = fetchApi;
    }

    public async Task<IActionResult> Index()
    {
        var posts = await _fetchApi.GetTypedContentList<Post>(
            referenceName: "posts",
            locale: "en-us",
            take: 10,
            sort: "fields.date",
            direction: "desc"
        );

        return View(posts);
    }
}

Key Differences

Legacy	Modern
repository.Items<T>("reference")	fetchApi.GetTypedContentList<T>("reference", locale)
repository.GetById<T>(id)	fetchApi.GetTypedContentItem<T>(id, locale)
LINQ filtering	API filter parameter
Synchronous	Async/await

Migrating Page Management

Before: Global.asax Routes

// Global.asax.cs
protected void Application_Start()
{
    // Agility route registration
    AgilityRouteConfig.RegisterRoutes(RouteTable.Routes);
}

After: Middleware + Dependency Injection

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// Register services
builder.Services.AddSingleton<FetchApiService>(...);
builder.Services.AddSingleton<AgilityRouteTransformer>();

var app = builder.Build();

// Configure middleware
app.UseStaticFiles();
app.UseRouting();
app.UseAgilityRedirects();  // Optional: URL redirects

// Dynamic page routing
app.MapDynamicPageRoute<AgilityRouteTransformer>("{**slug}");

Key Differences

• Routes are now opt-in via dependency injection
• Page routing uses ASP.NET Core's DynamicRouteValueTransformer
• URL redirects are a separate middleware you can customize or omit

Migrating URL Redirects

Before: Automatic & Required

URL redirects were always enabled with no customization.

After: Opt-In Middleware

// Program.cs - Add only if you need redirects
app.UseAgilityRedirects();

Or create custom redirect logic:

// Custom redirect middleware
public class CustomRedirectMiddleware
{
    private readonly RequestDelegate _next;
    private readonly FetchApiService _fetchApi;

    public async Task InvokeAsync(HttpContext context)
    {
        var redirects = await _fetchApi.GetUrlRedirects("en-us");
        var match = redirects.FirstOrDefault(r =>
            r.OriginUrl.Equals(context.Request.Path, StringComparison.OrdinalIgnoreCase));

        if (match != null)
        {
            // Custom logic here
            context.Response.Redirect(match.DestinationUrl, permanent: true);
            return;
        }

        await _next(context);
    }
}

Migrating Content Models

Before: Manual Class Definitions

// Models/Post.cs
public class Post
{
    public int ContentID { get; set; }
    public string Title { get; set; }
    public string Content { get; set; }
    public DateTime Date { get; set; }
    public string Slug { get; set; }
}

After: Typed Models (Same, but Better Organized)

// Models/AgilityModels.cs
public class Post
{
    public string? Title { get; set; }
    public string? Slug { get; set; }
    public DateTime? Date { get; set; }
    public string? Excerpt { get; set; }
    public string? Content { get; set; }
    public ImageAttachment? Image { get; set; }
    public ContentReference? Category { get; set; }
}

public class ImageAttachment
{
    public string? Url { get; set; }
    public string? Label { get; set; }
    public int? Width { get; set; }
    public int? Height { get; set; }
}

Generating Models (Optional)

There is no Agility tool that generates C# model classes, so write them by hand as shown above. The Agility CLI (@agility/cli on npm) copies content and models between instances; it doesn't generate code.

If you have many models, you can write your own generator: read the model definitions with the .NET Management SDK (client.Models.GetContentModelsAsync) and write out a class for each model.

Don't install a .NET tool named agility-cli. Earlier versions of this guide showed dotnet tool install -g agility-cli. No package with that name is published on NuGet, and anyone could register it, so that command could install code Agility doesn't control.

Migrating Views

Before: MVC 4/5 Views

@* Views/Blog/Index.cshtml *@
@model IEnumerable<Post>

<div class="posts">
    @foreach (var post in Model)
    {
        <article>
            <h2><a href="/blog/@post.Slug">@post.Title</a></h2>
            <time>@post.Date.ToString("MMMM d, yyyy")</time>
            @Html.Raw(post.Excerpt)
        </article>
    }
</div>

After: Blazor Component

@* Components/AgilityComponents/PostsListing.razor *@

<div class="posts grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
    @if (posts != null)
    {
        @foreach (var post in posts)
        {
            <article class="bg-white rounded-lg shadow p-6">
                <h2 class="text-xl font-bold mb-2">
                    <a href="/blog/@post.Slug" class="hover:text-primary-500">
                        @post.Title
                    </a>
                </h2>
                <time class="text-gray-500 text-sm">
                    @post.Date?.ToString("MMMM d, yyyy")
                </time>
                <div class="mt-4 prose">
                    @((MarkupString)(post.Excerpt ?? ""))
                </div>
            </article>
        }
    }
</div>

@code {
    private List<Post>? posts;

    protected override async Task OnInitializedAsync()
    {
        posts = await AgilityService.GetPostsAsync("en-us");
    }
}

After: MVC ViewComponent

// ViewComponents/PageModules/PostsListing.cs
public class PostsListing : ViewComponent
{
    private readonly FetchApiService _fetchApi;

    public PostsListing(FetchApiService fetchApi)
    {
        _fetchApi = fetchApi;
    }

    public async Task<IViewComponentResult> InvokeAsync(ModuleModel moduleModel)
    {
        var posts = await _fetchApi.GetTypedContentList<Post>(
            "posts", moduleModel.Locale, take: 10);

        return View("/Views/PageModules/PostsListing.cshtml", posts);
    }
}

@* Views/PageModules/PostsListing.cshtml *@
@model List<Post>

<div class="posts grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
    @foreach (var post in Model)
    {
        <article class="bg-white rounded-lg shadow p-6">
            <h2 class="text-xl font-bold mb-2">
                <a href="/blog/@post.Slug">@post.Title</a>
            </h2>
            <time class="text-gray-500 text-sm">
                @post.Date?.ToString("MMMM d, yyyy")
            </time>
            <div class="mt-4 prose">
                @Html.Raw(post.Excerpt)
            </div>
        </article>
    }
</div>

API Method Mapping

Legacy Method	Modern Method
repository.Items<T>(ref)	GetTypedContentList<T>(ref, locale)
repository.GetById<T>(id)	GetTypedContentItem<T>(id, locale)
repository.GetItemsByIDs<T>(ids)	Loop with GetTypedContentItem<T> or GraphQL
N/A	GetContentByGraphQL<T>(query, objName, locale)
N/A	GetTypedPage(pageId, locale)
N/A	GetSitemapFlat(channel, locale)
N/A	GetUrlRedirects(locale)

Configuration Migration

Before: Web.config

<appSettings>
    <add key="Agility.ContentAccessor.InstanceGuid" value="..." />
    <add key="Agility.ContentAccessor.ApiKey" value="..." />
</appSettings>

After: appsettings.json

{
  "AppSettings": {
    "InstanceGUID": "your-guid",
    "SecurityKey": "your-key",
    "FetchAPIKey": "defaultlive.your-key",
    "PreviewAPIKey": "defaultpreview.your-key",
    "Locales": "en-us",
    "ChannelName": "website",
    "CacheInMinutes": 5
  }
}

Feature Comparison

What's New

• GraphQL Support - Query exactly the fields you need
• Typed Endpoints - GetTypedContentList<T>, GetTypedPage, etc.
• Preview Mode - Built-in preview with security key validation
• CDN Headers - Stale-while-revalidate for better caching
• Webhook Support - Cache invalidation on publish
• Tailwind CSS - Modern utility-first styling
• One-Click Deploy - ARM templates for Azure

What's Different

• Async by Default - All API methods are async
• Dependency Injection - Services injected, not instantiated
• Explicit Locale - Pass locale to every API call
• Opt-In Features - Page routing and redirects are optional

What's Removed

• Synchronous API - Use async/await everywhere
• Built-In Caching - Implement your own caching strategy
• Global.asax - Use middleware pipeline

Migration Checklist

• Set up new project (Blazor or MVC starter)
• Configure API keys in appsettings.local.json
• Define content models in Models/AgilityModels.cs
• Convert controllers to ViewComponents or Blazor components
• Update views to use new syntax
• Migrate any custom routing logic
• Set up caching if needed
• Configure webhooks for cache invalidation
• Test preview mode
• Deploy to Azure
• Configure production webhooks and preview URLs

Getting Help

If you encounter issues during migration:

1. Check the GitHub Issues
2. Join the Agility CMS Community
3. Contact Agility Support

Next Steps

• Getting Started - Set up the new project
• Blazor Starter - Blazor-specific features
• MVC Starter - MVC-specific features
• Fetching Content - New API methods
• Configuration - Configuration options