Pagination

Certain API operations return lists of objects. When the number of objects in the list is large, the API will paginate the results.

The Files.com .NET SDK provides several ways to load paginated lists.

Creating a list with client.Folders.ListFor("/") sends no request. Pages are requested when you load them. Every page comes from the client the list was made with. Lists made with static methods, such as Folder.ListFor("/"), use the default client.

A page can be empty even when more items follow it. Each of these ways continues for as long as Files.com says there is another page, so none of them stops early at an empty page.

Automatic Pagination

ListAutoPagingAsync goes through every item with await foreach. It loads a page when you reach it and holds only that page, so a long list does not fill memory, and it does not block while a page loads. Leaving the loop early, with break, loads no further page.

Pass a CancellationToken, or use WithCancellation, to stop before the next page is loaded. Failures, such as NotFoundException or OperationCanceledException, are thrown from the await foreach.

await foreach needs C# 8 or later. .NET 8 and .NET 10 projects already use a later C# version. In a .NET Framework project, set <LangVersion>8.0</LangVersion> or later, or call GetAsyncEnumerator and MoveNextAsync directly.

Example Request

using FilesCom.Models;

try
{
    await foreach (var file in client.Folders.ListFor("/").ListAutoPagingAsync(cancellationToken))
    {
        Console.WriteLine("- Path: {0}", file.Path);
    }
}
catch (FilesCom.NotAuthenticatedException e)
{
    Console.WriteLine($"Authentication Error Occurred ({e.GetType().Name}): " + e.Message);
}
catch (FilesCom.SdkException e)
{
    Console.WriteLine($"Unknown Error Occurred ({e.GetType().Name}): " + e.Message);
}

Automatic Pagination in Synchronous Code

ListAutoPaging does the same with foreach, blocking while each page loads.

With a CancellationToken, failures are thrown as they are, such as NotFoundException or OperationCanceledException. Without one, they are wrapped in an AggregateException.

Example Request

using FilesCom.Models;

try
{
    foreach (var file in client.Folders.ListFor("/").ListAutoPaging(cancellationToken))
    {
        Console.WriteLine("- Path: {0}", file.Path);
    }
}
catch (FilesCom.NotAuthenticatedException e)
{
    Console.WriteLine($"Authentication Error Occurred ({e.GetType().Name}): " + e.Message);
}
catch (FilesCom.SdkException e)
{
    Console.WriteLine($"Unknown Error Occurred ({e.GetType().Name}): " + e.Message);
}

Manual Pagination

The LoadNextPageAsync/HasNextPage methods allow for manual pagination and loading of each page into memory.

If loading a page fails, the list keeps the page it had and HasNextPage is unchanged, so you can try again. Reset starts the list again from its first page.

Example Request

using FilesCom.Models;

try
{
    FilesList<RemoteFile> listing = client.Folders.ListFor("/");
    do
    {
        foreach (var file in await listing.LoadNextPageAsync(cancellationToken))
        {
            Console.WriteLine("- Path: {0}", file.Path);
        }
    } while (listing.HasNextPage);
}
catch (FilesCom.NotAuthenticatedException e)
{
    Console.WriteLine($"Authentication Error Occurred ({e.GetType().Name}): " + e.Message);
}
catch (FilesCom.SdkException e)
{
    Console.WriteLine($"Unknown Error Occurred ({e.GetType().Name}): " + e.Message);
}

Load All Items

The AllAsync method loads every page, then returns all their items together, so they are all in memory at once.

ListAutoPagingAsync, ListAutoPaging and AllAsync each start from the list's first page, whatever pages LoadNextPageAsync has loaded.

Example Request

using FilesCom.Models;

try
{
    var files = await client.Folders.ListFor("/").AllAsync(cancellationToken);
    foreach (var file in files)
    {
        Console.WriteLine("- Path: {0}", file.Path);
    }
}
catch (FilesCom.NotAuthenticatedException e)
{
    Console.WriteLine($"Authentication Error Occurred ({e.GetType().Name}): " + e.Message);
}
catch (FilesCom.SdkException e)
{
    Console.WriteLine($"Unknown Error Occurred ({e.GetType().Name}): " + e.Message);
}