Azure-cosmos-dotnet-v3: Add support for IAsyncEnumerable<T>

[thomaslevesque]

Is your feature request related to a problem? Please describe.

The API for enumerating query results isn't great, because it forces the user to be aware of the fact that the results are fetched page by page:

var iterator = ...
while (iterator.HasMoreResults)
{
    var page = await iterator.ReadNextAsync();
    foreach (var item in page)
    {
        ...
    }
}

Describe the solution you'd like

The FeedIterator<T> API is useful, because it gives you more information (e.g. request charge), but in most cases the user just wants the results, so it would be nice to have a higher level abstraction. The IAsyncEnumerable<T> interface seems perfect for this.

There could be an AsAsyncEnumerable extension method like this:

public static async IAsyncEnumerable<T> AsAsyncEnumerable<T>(
    this FeedIterator<T> iterator,
    [EnumeratorCancellation] CancellationToken cancellationToken = default)
{
    while (iterator.HasMoreResults)
    {
        var page = await iterator.ReadNextAsync(cancellationToken);
        foreach (var item in page)
        {
            cancellationToken.ThrowIfCancellationRequested();
            yield return item;
        }
    }
}

The consuming code would be simplified to this:

var iterator = ...
await foreach (var item in iterator.AsAsyncEnumerable())
{
    ...
}

Describe alternatives you've considered
N/A

Additional context

The await foreach feature was introduced in C# 8, so this would only be useful to people already using C# 8.
However, the Microsoft.Bcl.AsyncInterfaces package is compatible with netstandard2.0 and net461, so it wouldn't require running .NET Core 3.

[ealsur]

We are working on this at the moment 😄

[thomaslevesque]

Awesome!

[ealsur]

@thomaslevesque See the V4 (preview) package https://docs.microsoft.com/en-us/azure/cosmos-db/create-sql-api-dotnet-v4#query-the-items

[thomaslevesque]

Cool, thanks!

[cfindlayvcs]

@ealsur , I just tried this with the latest version of the Cosmos DB API (3.15.2) on .NET Core 3.1 and GetItemQueryIterator<> does not return IAsyncEnumerable. I get this:

There is no 4.0 preview package.

[lorenpaulsen]

@ealsur , I just tried this with the latest version of the Cosmos DB API (3.15.2) on .NET Core 3.1 and GetItemQueryIterator<> does not return IAsyncEnumerable. I get this:

There is no 4.0 preview package.

The 4.0 preview package can be found here: https://www.nuget.org/packages/Azure.Cosmos

[thomaslevesque]

The 4.0 preview package can be found here: https://www.nuget.org/packages/Azure.Cosmos

Indeed. Honestly, I'm not sure how we're supposed to guess that.

• The README says it's the repo for "Version 3", with no mention of a version 4
• The README still points to the old package and doesn't mention the new one
• The old package doesn't mention that it's been superseded by a new one
• The new package points to this repo, which doesn't seem to know anything about the new package

I think I discovered the new package by accident in an article. There's almost no chance a new user will find it if they end up on this repo.