ClientModel: Pageable abstractions for third-party clients

sdk/core/System.ClientModel/api/System.ClientModel.net6.0.cs

@@ -7,6 +7,12 @@ public ApiKeyCredential(string key) { }
         public static implicit operator System.ClientModel.ApiKeyCredential (string key) { throw null; }
         public void Update(string key) { }
     }
+    public abstract partial class AsyncPageableCollection<T> : System.ClientModel.AsyncResultCollection<T>
+    {
+        protected AsyncPageableCollection() { }
+        public abstract System.Collections.Generic.IAsyncEnumerable<System.ClientModel.ResultPage<T>> AsPages(string? continuationToken = null, int? pageSizeHint = default(int?));
+        public override System.Collections.Generic.IAsyncEnumerator<T> GetAsyncEnumerator(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+    }
     public abstract partial class AsyncResultCollection<T> : System.ClientModel.ClientResult, System.Collections.Generic.IAsyncEnumerable<T>
     {
         protected internal AsyncResultCollection() { }
@@ -48,13 +54,26 @@ protected internal ClientResult(T value, System.ClientModel.Primitives.PipelineR
         public virtual T Value { get { throw null; } }
         public static implicit operator T (System.ClientModel.ClientResult<T> result) { throw null; }
     }
+    public abstract partial class PageableCollection<T> : System.ClientModel.ResultCollection<T>
+    {
+        protected PageableCollection() { }
+        public abstract System.Collections.Generic.IEnumerable<System.ClientModel.ResultPage<T>> AsPages(string? continuationToken = null, int? pageSizeHint = default(int?));
+        public override System.Collections.Generic.IEnumerator<T> GetEnumerator() { throw null; }
+    }
     public abstract partial class ResultCollection<T> : System.ClientModel.ClientResult, System.Collections.Generic.IEnumerable<T>, System.Collections.IEnumerable
     {
         protected internal ResultCollection() { }
         protected internal ResultCollection(System.ClientModel.Primitives.PipelineResponse response) { }
         public abstract System.Collections.Generic.IEnumerator<T> GetEnumerator();
         System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator() { throw null; }
     }
+    public partial class ResultPage<T> : System.ClientModel.ResultCollection<T>
+    {
+        internal ResultPage() { }
+        public string? ContinuationToken { get { throw null; } }
+        public static System.ClientModel.ResultPage<T> Create(System.Collections.Generic.IEnumerable<T> values, string? continuationToken, System.ClientModel.Primitives.PipelineResponse response) { throw null; }
+        public override System.Collections.Generic.IEnumerator<T> GetEnumerator() { throw null; }
+    }
 }
 namespace System.ClientModel.Primitives
 {

sdk/core/System.ClientModel/api/System.ClientModel.netstandard2.0.cs

@@ -7,6 +7,12 @@ public ApiKeyCredential(string key) { }
         public static implicit operator System.ClientModel.ApiKeyCredential (string key) { throw null; }
         public void Update(string key) { }
     }
+    public abstract partial class AsyncPageableCollection<T> : System.ClientModel.AsyncResultCollection<T>
+    {
+        protected AsyncPageableCollection() { }
+        public abstract System.Collections.Generic.IAsyncEnumerable<System.ClientModel.ResultPage<T>> AsPages(string? continuationToken = null, int? pageSizeHint = default(int?));
+        public override System.Collections.Generic.IAsyncEnumerator<T> GetAsyncEnumerator(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+    }
     public abstract partial class AsyncResultCollection<T> : System.ClientModel.ClientResult, System.Collections.Generic.IAsyncEnumerable<T>
     {
         protected internal AsyncResultCollection() { }
@@ -48,13 +54,26 @@ protected internal ClientResult(T value, System.ClientModel.Primitives.PipelineR
         public virtual T Value { get { throw null; } }
         public static implicit operator T (System.ClientModel.ClientResult<T> result) { throw null; }
     }
+    public abstract partial class PageableCollection<T> : System.ClientModel.ResultCollection<T>
+    {
+        protected PageableCollection() { }
+        public abstract System.Collections.Generic.IEnumerable<System.ClientModel.ResultPage<T>> AsPages(string? continuationToken = null, int? pageSizeHint = default(int?));
+        public override System.Collections.Generic.IEnumerator<T> GetEnumerator() { throw null; }
+    }
     public abstract partial class ResultCollection<T> : System.ClientModel.ClientResult, System.Collections.Generic.IEnumerable<T>, System.Collections.IEnumerable
     {
         protected internal ResultCollection() { }
         protected internal ResultCollection(System.ClientModel.Primitives.PipelineResponse response) { }
         public abstract System.Collections.Generic.IEnumerator<T> GetEnumerator();
         System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator() { throw null; }
     }
+    public partial class ResultPage<T> : System.ClientModel.ResultCollection<T>
+    {
+        internal ResultPage() { }
+        public string? ContinuationToken { get { throw null; } }
+        public static System.ClientModel.ResultPage<T> Create(System.Collections.Generic.IEnumerable<T> values, string? continuationToken, System.ClientModel.Primitives.PipelineResponse response) { throw null; }
+        public override System.Collections.Generic.IEnumerator<T> GetEnumerator() { throw null; }
+    }
 }
 namespace System.ClientModel.Primitives
 {

sdk/core/System.ClientModel/src/Convenience/AsyncPageableCollectionOfT.cs

@@ -0,0 +1,62 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace System.ClientModel;
+
+/// <summary>
+/// Represents a collection of results returned from a cloud service operation
+/// sequentially over one or more calls to the service.
+/// </summary>
+public abstract class AsyncPageableCollection<T> : AsyncResultCollection<T>
+{
+    /// <summary>
+    /// Create a new instance of <see cref="AsyncPageableCollection{T}"/>.
+    /// </summary>
+    /// <remarks>This constructor does not take a <see cref="PipelineResponse"/>
+    /// because derived types are expected to defer the first service call
+    /// until the collection is enumerated using <c>await foreach</c>.
+    /// </remarks>
+    protected AsyncPageableCollection() : base()
+    {
+    }
+
+    /// <summary>
+    /// Return an enumerable of <see cref="ResultPage{T}"/> that aynchronously
+    /// enumerates the collection's pages instead of the collection's individual
+    /// values. This may make multiple service requests.
+    /// </summary>
+    /// <param name="continuationToken">A token indicating where the collection
+    /// of results returned from the service should begin. Passing <c>null</c>
+    /// will start the collection at the first page of values.</param>
+    /// <param name="pageSizeHint">The number of items to request that the
+    /// service return in a <see cref="ResultPage{T}"/>, if the service supports
+    /// such requests.</param>
+    /// <returns>An async sequence of <see cref="ResultPage{T}"/>, each holding
+    /// the subset of collection values contained in a given service response.
+    /// </returns>
+    public abstract IAsyncEnumerable<ResultPage<T>> AsPages(string? continuationToken = default, int? pageSizeHint = default);
+
+    /// <summary>
+    /// Return an enumerator that iterates asynchronously through the collection
+    /// values. This may make multiple service requests.
+    /// </summary>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> used
+    /// with requests made while enumerating asynchronously.</param>
+    /// <returns>An <see cref="IAsyncEnumerator{T}"/> that can iterate
+    /// asynchronously through the collection values.</returns>
+    public override async IAsyncEnumerator<T> GetAsyncEnumerator(CancellationToken cancellationToken = default)
+    {
+        await foreach (ResultPage<T> page in AsPages().ConfigureAwait(false).WithCancellation(cancellationToken))
+        {
+            foreach (T value in page)
+            {
+                yield return value;
+            }
+        }
+    }
+}

sdk/core/System.ClientModel/src/Convenience/PageableCollectionOfT.cs

@@ -0,0 +1,57 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+
+namespace System.ClientModel;
+
+/// <summary>
+/// Represents a collection of results returned from a cloud service operation
+/// sequentially over one or more calls to the service.
+/// </summary>
+public abstract class PageableCollection<T> : ResultCollection<T>
+{
+    /// <summary>
+    /// Create a new instance of <see cref="PageableCollection{T}"/>.
+    /// </summary>
+    /// <remarks>This constructor does not take a <see cref="PipelineResponse"/>
+    /// because derived types are expected to defer the first service call
+    /// until the collection is enumerated using <c>foreach</c>.</remarks>
+    protected PageableCollection() : base()
+    {
+    }
+
+    /// <summary>
+    /// Return an enumerable of <see cref="ResultPage{T}"/> that enumerates the
+    /// collection's pages instead of the collection's individual values. This
+    /// may make multiple service requests.
+    /// </summary>
+    /// <param name="continuationToken">A token indicating where the collection
+    /// of results returned from the service should begin. Passing <c>null</c>
+    /// will start the collection at the first page of values.</param>
+    /// <param name="pageSizeHint">The number of items to request that the
+    /// service return in a <see cref="ResultPage{T}"/>, if the service supports
+    /// such requests.</param>
+    /// <returns>A sequence of <see cref="ResultPage{T}"/>, each holding the
+    /// subset of collection values contained in a given service response.
+    /// </returns>
+    public abstract IEnumerable<ResultPage<T>> AsPages(string? continuationToken = default, int? pageSizeHint = default);
+
+    /// <summary>
+    /// Return an enumerator that iterates through the collection values. This
+    /// may make multiple service requests.
+    /// </summary>
+    /// <returns>An <see cref="IEnumerator{T}"/> that can iterate through the
+    /// collection values.</returns>
+    public override IEnumerator<T> GetEnumerator()
+    {
+        foreach (ResultPage<T> page in AsPages())
+        {
+            foreach (T value in page)
+            {
+                yield return value;
+            }
+        }
+    }
+}

sdk/core/System.ClientModel/src/Convenience/ResultPageOfT.cs

@@ -0,0 +1,50 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+
+namespace System.ClientModel;
+
+/// <summary>
+/// Represents the subset (or page) of results contained in a single response
+/// from a cloud service returning a collection of results sequentially over
+/// one or more calls to the service (i.e. a paged collection).
+/// </summary>
+public class ResultPage<T> : ResultCollection<T>
+{
+    private readonly IEnumerable<T> _values;
+
+    private ResultPage(IEnumerable<T> values, string? continuationToken, PipelineResponse response)
+        : base(response)
+    {
+        _values = values;
+        ContinuationToken = continuationToken;
+    }
+
+    /// <summary>
+    /// Creates a new <see cref="ResultPage{T}"/>.
+    /// </summary>
+    /// <param name="values">The values contained in <paramref name="response"/>.
+    /// </param>
+    /// <param name="continuationToken">The token that can be used to request
+    /// the next page of results from the service, or <c>null</c> if this page
+    /// holds the final subset of values.</param>
+    /// <param name="response">The <see cref="PipelineResponse"/> holding the
+    /// collection values returned by the service.</param>
+    /// <returns>An instance of <see cref="ResultPage{T}"/> holding the provided
+    /// values.</returns>
+    public static ResultPage<T> Create(IEnumerable<T> values, string? continuationToken, PipelineResponse response)
+        => new(values, continuationToken, response);
+
+    /// <summary>
+    /// Gets the continuation token used to request the next
+    /// <see cref="ResultPage{T}"/>.  May be <c>null</c> or empty when no values
+    /// remain to be returned from the collection.
+    /// </summary>
+    public string? ContinuationToken { get; }
+
+    /// <inheritdoc/>
+    public override IEnumerator<T> GetEnumerator()
+        => _values.GetEnumerator();
+}

sdk/core/System.ClientModel/tests/Convenience/ClientResultTests.cs

@@ -8,7 +8,7 @@
 
 namespace System.ClientModel.Tests.Results;
 
-public class PipelineResponseTests
+public class ClientResultTests
 {
     #region ClientResult