Agility CMS Fetch SDK for .NET

Official .NET SDK for pulling content from your Agility CMS instance via the Fetch API.

What's New in 3.0

• Upgraded to .NET 10 - Now targets net10.0 for the latest performance and language features
• Updated all dependencies to their latest versions
• IsPreview is a parameter set on EACH method call
• GraphQL Content Items support
• Single unified assembly (removed Shared and Core projects)

Installation

Install via NuGet Package Manager:

dotnet add package Agility.NET.FetchAPI

Or add to your .csproj:

<PackageReference Include="Agility.NET.FetchAPI" Version="3.1.0" />

Requirements

• .NET 10.0 or later

Quick Start

1. Configure Services

In your Program.cs or startup configuration:

using Agility.NET.FetchAPI.Helpers;
using Agility.NET.FetchAPI.Services;

// Configure Agility settings
builder.Services.Configure<AppSettings>(options =>
{
    options.InstanceGUID = "your-instance-guid";
    options.FetchAPIKey = "your-fetch-api-key";
    options.PreviewAPIKey = "your-preview-api-key";
    options.Locales = "en-us";
    options.ChannelName = "website";
});

// Register HttpClient and FetchApiService
builder.Services.AddHttpClient<FetchApiService>();

2. Inject and Use the Service

public class MyController : Controller
{
    private readonly FetchApiService _agilityService;

    public MyController(FetchApiService agilityService)
    {
        _agilityService = agilityService;
    }

    public async Task<IActionResult> GetContent()
    {
        var item = await _agilityService.GetContentItem(
            new GetItemParameters
            {
                IsPreview = false,
                Locale = "en-us",
                ContentId = 123,
                ContentLinkDepth = 2
            });

        return Ok(item);
    }
}

Configuration Options

public class AppSettings
{
    public string InstanceGUID { get; set; }      // Your Agility instance GUID
    public string SecurityKey { get; set; }       // Security key (optional)
    public string WebsiteName { get; set; }       // Website name (optional)
    public string FetchAPIKey { get; set; }       // API key for fetch (live) mode
    public string PreviewAPIKey { get; set; }     // API key for preview mode
    public string Locales { get; set; }           // Supported locales (e.g., "en-us")
    public string ChannelName { get; set; }       // Default channel name
    public int CacheInMinutes { get; set; }       // Cache duration in minutes
}

Regional Support

The SDK automatically routes requests to the correct regional endpoint based on your Instance GUID suffix:

Region	GUID Suffix	Endpoint
US (default)	—	https://api.aglty.io
USA 2	-us2	https://api-usa2.aglty.io
Canada	-c	https://api-ca.aglty.io
Europe	-e	https://api-eu.aglty.io
Australia	-a	https://api-aus.aglty.io
Development	-d	https://api-dev.aglty.io

Fetch API Methods

Function	Parameters	Description
GetContentItem	GetItemParameters	Get a single content item
GetContentList	GetListParameters	Get a content list
GetGallery	GetGalleryParameters	Get a gallery
GetPage	GetPageParameters	Get a page
GetSitemapFlat	GetSitemapParameters	Get a flat sitemap
GetSitemapNested	GetSitemapParameters	Get a nested sitemap
GetUrlRedirections	GetUrlRedirectionsParameters	Get URL redirections
GetSyncContent	GetSyncParameters	Sync all content using a sync token
GetSyncPages	GetSyncParameters	Sync all pages using a sync token
GetContentByGraphQL<T>	query, locale, object name, preview	Query content using GraphQL

Typed Methods

The SDK also provides typed versions of the main methods:

Method	Returns
GetTypedContentItem<T>	ContentItemResponse<T>, with your fields class as T
GetTypedContentList<T>	ContentListResponse<T>
GetTypedPage	PageResponse
GetTypedSitemapFlat	List<SitemapPage>
GetTypedSitemapNested	List<SitemapPage>

Parameter Models

GetItemParameters

public class GetItemParameters
{
    public bool IsPreview { get; set; }           // Use preview or fetch mode
    public string Locale { get; set; }
    public int ContentId { get; set; }
    public int ContentLinkDepth { get; set; }
    public bool ExpandAllContentLinks { get; set; }
}

GetListParameters

public class GetListParameters
{
    public bool IsPreview { get; set; }           // Use preview or fetch mode
    public string Locale { get; set; }
    public string ReferenceName { get; set; }
    public string Fields { get; set; }
    public int Take { get; set; }
    public int Skip { get; set; }
    public string Filter { get; set; }
    public string Sort { get; set; }
    public string Direction { get; set; }
    public int ContentLinkDepth { get; set; }
    public bool ExpandAllContentLinks { get; set; }
}

GetGalleryParameters

public class GetGalleryParameters
{
    public bool IsPreview { get; set; }           // Use preview or fetch mode
    public int GalleryId { get; set; }
}

GetPageParameters

public class GetPageParameters
{
    public bool IsPreview { get; set; }           // Use preview or fetch mode
    public string Locale { get; set; }
    public int PageId { get; set; }
    public int ContentLinkDepth { get; set; }     // Must be 0 for GetTypedPage
    public bool ExpandAllContentLinks { get; set; }
}

GetSitemapParameters

public class GetSitemapParameters
{
    public bool IsPreview { get; set; }           // Use preview or fetch mode
    public string Locale { get; set; }
    public string ChannelName { get; set; }
}

GetUrlRedirectionsParameters

public class GetUrlRedirectionsParameters
{
    public bool IsPreview { get; set; }           // Use preview or fetch mode
    public DateTime? LastAccessDate { get; set; }
}

GetSyncParameters

public class GetSyncParameters
{
    public bool IsPreview { get; set; }           // Use preview or fetch mode
    public string Locale { get; set; }
    public long SyncToken { get; set; }
    public int PageSize { get; set; }
}

GraphQL Support

Query content using GraphQL for more flexible data retrieval. Pass the locale to query and the name of the top-level object to return; T is the class for each item's fields:

var query = @"
{
    posts {
        contentID
        fields {
            title
            content
        }
    }
}";

List<ContentItemResponse<PostFields>> posts =
    await _agilityService.GetContentByGraphQL<PostFields>(query, "en-us", "posts", isPreview: false);

Each locale has its own GraphQL endpoint (/v1/{guid}/{fetch|preview}/{locale}/graphql); versions before 3.1.0 always queried en-us.

Development Setup

1. Clone the repo:

   git clone https://github.com/agility/agilitycms-dotnet-fetch-api

2. Open in your IDE and restore packages:

   dotnet restore

3. Build:

   dotnet build

4. Configure test credentials:

   cp tests/Agility.NET.FetchAPI.Tests/test.runsettings.template tests/Agility.NET.FetchAPI.Tests/test.runsettings

   Edit test.runsettings with your Agility credentials.

5. Run tests:

   dotnet test --settings tests/Agility.NET.FetchAPI.Tests/test.runsettings

Requests

Every request sends X-Agility-SDK: agility-fetch-sdk-dotnet/<version> (also used as the User-Agent), so the API can tell SDK traffic apart. A non-200 response throws an ApplicationException (wrapped in AgilityResponseException) whose message starts HttpException: {status} - {reason} and includes the API's response.

CI/CD

This project uses GitHub Actions. The CI workflow builds, tests and packs every pull request and push to main. Its tests call a real instance, so configure these repository secrets:

Secret	Description
AGILITY_INSTANCE_GUID	Your Agility CMS instance GUID
AGILITY_FETCH_API_KEY	API key for fetch (live) mode
AGILITY_PREVIEW_API_KEY	API key for preview mode

Releasing

1. Set <Version> in src/Agility.NET.FetchAPI/Agility.NET.FetchAPI.csproj and add a CHANGELOG.md entry.
2. Merge to main, then tag it: git tag v3.1.0 && git push origin v3.1.0.
3. The Release workflow checks that the tag matches the version, builds, tests, packs, and (after approval in the nuget environment) publishes to NuGet with Trusted Publishing: no API key is stored anywhere.
4. It then creates the GitHub release for the tag, with the version's CHANGELOG.md section as the notes and the .nupkg and .snupkg attached. A tag with no CHANGELOG.md entry fails before anything is published.

Integration with Agility .NET Starter

To use this SDK with the Agility CMS .NET Starter:

1. Add a project reference or install the NuGet package
2. Configure AppSettings with your Agility credentials
3. Register FetchApiService with dependency injection

License

MIT License - see LICENSE for details.

Resources

• Agility CMS Documentation
• Agility CMS .NET Starter
• NuGet Package