Using Agility CMS with ASP.NET Core

We are pleased to announce that Agility.Web for ASP.NET Core is now available on Nuget.org.

Install-Package Agility.AspNetCore

Upgrading to .NET Core 3.1 has a few breaking changes. With Microsoft's latest version of .NET Core, it has deprecated dependencies on MVC libraries. Even though they are not breaking changes new versions after 3.1 will not be supported.

For more details, you can review Migrating Agility CMS to .NET Core 3.1. This article goes into depth on the reasoning and changes from .NET Core 2.2 to 3.1.

Instance-Specific Agility Configuration

What used to be Web.config in a traditional ASP.NET MVC app is now replaced with appsettings.json in ASP.NET Core and it will look like the following for agility configuration:

{
  "Logging": {
    "IncludeScopes": false,
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "Agility": {
    "applicationName": "Sample Website (Local)",
    "websiteName": "Sample Website",
    "securityKey": "your instance's security code",
    "contentCacheFilePath": "/home/AgilityContent/",
    "contentServerUrl": "https://contentserver-ca.agilitycms.com/agilitycontentserver.svc",
    "developmentMode": "false",
    "Trace": {
      "traceLevel": "Verbose",
      "logFilePath": "/home/AgilityLogs/AgilityWebsite.log"
    },
    "UGC": {
      "Url": "http://ugc-ca.agilitycms.com/Agility-UGC-API-JSONP.svc",
      "Key": "your ugc key",
      "Password": "your ugc password"
    }
  }

}

Registering Agility Routes

Default Agility Routes for the Page Tree are registered in the Configure method of ASP.NET Core projects Startup.cs file as follows:

app.UseRouting();

app.UseEndpoints(endpoints =>
{
  //Agility Builtin Route
  endpoints.MapControllerRoute("Agility", "{*sitemapPath}", new { controller = "Agility", action = "RenderPage" },
   new { isAgilityPath = new Agility.Web.Mvc.AgilityRouteConstraint() });

  endpoints.MapControllerRoute("default", "{controller=Home}/{action=Index}/{id?}");
    
});

Please note older versions of Agility CMS used UseMvc for routing this has been deprecated and now replaced with UseEndpoints.

Registering Authentication

MVC Authorization filters are no longer supported and the HTTP context is now separate. Therefore we need to register authentication on startup:

app.UseAuthentication();
app.UseAuthorization();

Registering Agility Context

Register new IWebHostEnvironment with Agility Context. AspNetCore has been updated to support IWebHostEnvironment from IHostingEnvironment:

 AgilityContext.Configure(app, env);

Module Setup with ViewComponents

In a traditional ASP.NET MVC project, Controllers and Actions are used to render Agility Modules. ASP.NET Core replaces them with ViewComponents. Using ViewComponents enables Agility.Web for ASP.NET Core to render modules on a page asynchronously.

The above code snippet would look like the following snippet in an ASP.NET MVC project.