Generated clients lack pagination support (@odata.nextLink)

[daviburg]

Summary

The generated DirectClient typed clients do not support paginated responses. Operations that return paged collections (e.g., ListUsersAsync on MsgraphgroupsanduserClient) return only the first page with no way to follow @odata.nextLink for subsequent pages.

Affected Connectors

All connectors with list/search operations that return paged OData responses:

• MS Graph Groups & Users: ListUsersAsync, ListGroupsByDisplayNameSearchAsync, ListDirectGroupMembersAsync
• Office365: email listing operations
• SharePoint: list/folder operations
• Teams: GetAllTeamsAsync, GetChannelsForGroupAsync, GetMessagesFromChannelAsync

Current Behavior

The generated ListUsersResponse type includes @odata.context and value but does not include an @odata.nextLink property. The CallConnectorAsync<T> method deserializes the response into the typed model, discarding any nextLink that may be present in the JSON.

Example response from the connector:
json { "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users", "@odata.nextLink": "https://graph.microsoft.com/v1.0/users?$skiptoken=...", "value": [...] }

The @odata.nextLink field is silently lost during deserialization.

Expected Behavior

The SDK should support pagination in one or more of these ways:

1. Include nextLink in response types — Add an @odata.nextLink property to all list response types so callers can detect when more pages exist
2. Provide a follow-up method — e.g., GetNextPageAsync<T>(nextLink) on the client that accepts a nextLink URL and returns the next page with the same typed response
3. Provide an async enumerable — e.g., ListUsersPagedAsync() that yields all pages automatically

Root Cause

The BPM CodefulSdkGenerator does not emit @odata.nextLink properties in the generated response POCOs, and the CallConnectorAsync<T> helper does not preserve unmodeled JSON properties.

Impact

Without pagination support, the connector is limited to the first page of results (typically 100 items). This makes the connector unsuitable for production scenarios with large datasets. The connector should not be considered fully supported until this is resolved.

Workaround

None — callers cannot access nextLink through the typed client. The only option is to make raw HTTP calls outside the generated client.

[wsilveiranz]

@daviburg - I think option 2 or 3 would be the best options.

I think option 2 gives more flexibility as implementing your own Get Async that loops through next pages until there is no more pages to load. But could we do something like GetNextPageAsync() instead of (nextLink)? You will already be in the context of the action result/action, so you will have access to the properties.

Number 3 can be a problem on very large datasets, so parsing pages individually gives us a lot more flexibility. My two cents.

[nzthiago]

I like Option 2 beter too. Is this only for actions, or do triggers also expose pages? because for triggers we need to discuss deeper with the Functions engineers for how to best handle it given the distributed nature of a scaled out function app.

[daviburg]

Design Study: Auto-Pagination Options

Investigated the feasibility of four design options, with particular focus on whether the SDK can "get the next page without the caller providing the next link" as @wsilveiranz requested.

Current Architecture

• Paginated methods (e.g., ListFolderAsync) return page objects with Value + NextLink
• CallConnectorAsync constructs URLs as $"{connectionRuntimeUrl}{path}" — only handles relative paths, not absolute NextLink URLs
• Teams uses @odata.nextLink (OData); OneDrive uses nextLink (camelCase) — two wire conventions
• Python SDK's BlobMetadataPage is missing next_link entirely — the generator didn't emit it
• Node SDK: empty repo, no implementation yet

Why "client.GetNextPageAsync()" Without Arguments Is Dangerous

@wsilveiranz asked: "could we do something like GetNextPageAsync() instead of (nextLink)?"

This would require storing the last NextLink as mutable state on the client instance. Problems:

1. Thread safety — Azure SDK guidelines: clients must be immutable and thread-safe. A mutable _currentNextLink field breaks that contract.
2. Concurrent operations — ListFolderAsync("A") and ListFolderAsync("B") on the same client would fight over whose NextLink is "current."
3. Ambiguity — GetNextPageAsync() — next page of which operation? Which folder? Which connector method?
4. Cross-language pain — Python needs asyncio.Lock; Node needs careful async state management. Complexity spirals.
5. Evolution — would likely need IAsyncDisposable, scoped contexts, or operation IDs to disambiguate. Over-engineering.

The Four Options Evaluated

Option A: IAsyncEnumerable<T> (Azure SDK Standard) ✅ SELECTED

// Caller code — no NextLink, no manual loop
await foreach (BlobMetadata file in client.ListFolderAsync("root"))
{
    Console.WriteLine(file.Name);
}

State lives in the enumerator (a new object per call), not the client. Each await foreach creates its own independent cursor.

Dimension	Assessment
Client state	None — enumerator is the cursor
Thread safety	✅ Safe — each await foreach creates its own enumerator
C#	IAsyncEnumerable<T> (C# 8+), System.Linq.Async for LINQ
Python	async for item in client.list_folder("root") via __aiter__/__anext__ — native
Node/TS	for await (const file of client.listFolder("root")) via Symbol.asyncIterator — native
Breaking change	Yes — return type changes from Task<Page> to IAsyncEnumerable<T>
Pre-1.0	Acceptable — we haven't shipped a customer preview yet

Option B: Separate Pager/Iterator Object

var pager = client.CreateListFolderPager("root");
while (await pager.MoveNextAsync()) { /* pager.Current */ }

Non-breaking (additive), but adds API surface duplication. Good if we couldn't break.

Option C: Helper Method GetNextPageAsync<T>(page)

var page = await client.ListFolderAsync("root");
while (page?.NextLink != null)
    page = await client.GetNextPageAsync<BlobMetadataPage>(page);

Minimal effort but still a manual loop — cosmetic improvement only.

Option D: Client-Level Mutable State ❌ REJECTED

var page = await client.ListFolderAsync("root");
var next = await client.GetNextPageAsync(); // no args — state on client

Introduces mutable shared state, violates Azure SDK immutability principles, breaks thread safety, creates cross-language impedance mismatch. Do not pursue.

Decision: Option A

Since we haven't shipped a customer private preview, we can absorb the breaking return-type change now. Option A is:

• The Azure SDK standard (AsyncPageable<T> / Pageable<T>)
• Idiomatic in all three target languages (C# await foreach, Python async for, Node for await)
• Zero client state — the enumerator holds the cursor
• Compatible with System.Linq.Async for ToListAsync(), Take(N), Where(), etc.
• Exactly what @wsilveiranz wants: no NextLink in caller code

Implementation Plan

1. Fix CallConnectorAsync to handle absolute NextLink URLs — detect if path is already absolute, skip prepending base URL
2. Add IAsyncEnumerable<T> infrastructure to ConnectorClientBase or a helper class
3. Update CodefulSdkGenerator to emit IAsyncEnumerable<TItem> return types for paginated operations (operations whose response has a nextLink + value array pattern)
4. Retain page-level access via .AsPages() pattern for callers who need page boundaries or continuation tokens
5. Fix Python generator to emit next_link on page types, then add __aiter__ support
6. Node SDK will implement Symbol.asyncIterator when its generator is built

Prerequisites

• Microsoft.Bcl.AsyncInterfaces NuGet dependency for netstandard2.0 target
• Generator must detect which operations return paginated responses (presence of nextLink in response schema)

@wsilveiranz @nzthiago — to answer Thiago's question: this is actions-only. Triggers deliver individual callback payloads; they don't paginate. The Functions extension receives one trigger event at a time through the Connector Gateway webhook.