ClientModel: Updates to paging types to support sub-client enumerator pattern

sdk/core/Azure.Core/src/Azure.Core.csproj

@@ -28,6 +28,8 @@
     <PackageReference Include="System.Text.Json" />
     <PackageReference Include="System.Text.Encodings.Web" />
     <PackageReference Include="System.Memory.Data" />
+
+    <ExcludeFromProjectReferenceToConversion Include="System.ClientModel" />
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFramework)' == 'net461'">

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

@@ -7,17 +7,20 @@ 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>
+    public abstract partial class AsyncCollectionResult<T> : System.ClientModel.ClientResult, System.Collections.Generic.IAsyncEnumerable<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; }
+        protected internal AsyncCollectionResult() { }
+        protected internal AsyncCollectionResult(System.ClientModel.Primitives.PipelineResponse response) { }
+        public abstract System.Collections.Generic.IAsyncEnumerator<T> GetAsyncEnumerator(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken));
     }
-    public abstract partial class AsyncResultCollection<T> : System.ClientModel.ClientResult, System.Collections.Generic.IAsyncEnumerable<T>
+    public abstract partial class AsyncPageCollection<T> : System.Collections.Generic.IAsyncEnumerable<System.ClientModel.PageResult<T>>
     {
-        protected internal AsyncResultCollection() { }
-        protected internal AsyncResultCollection(System.ClientModel.Primitives.PipelineResponse response) { }
-        public abstract System.Collections.Generic.IAsyncEnumerator<T> GetAsyncEnumerator(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken));
+        protected AsyncPageCollection() { }
+        public System.Collections.Generic.IAsyncEnumerable<T> GetAllValuesAsync([System.Runtime.CompilerServices.EnumeratorCancellationAttribute] System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        protected abstract System.Collections.Generic.IAsyncEnumerator<System.ClientModel.PageResult<T>> GetAsyncEnumeratorCore(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken));
+        public System.Threading.Tasks.Task<System.ClientModel.PageResult<T>> GetCurrentPageAsync() { throw null; }
+        protected abstract System.Threading.Tasks.Task<System.ClientModel.PageResult<T>> GetCurrentPageAsyncCore();
+        System.Collections.Generic.IAsyncEnumerator<System.ClientModel.PageResult<T>> System.Collections.Generic.IAsyncEnumerable<System.ClientModel.PageResult<T>>.GetAsyncEnumerator(System.Threading.CancellationToken cancellationToken) { throw null; }
     }
     public abstract partial class BinaryContent : System.IDisposable
     {
@@ -54,25 +57,37 @@ 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>
+    public abstract partial class CollectionResult<T> : System.ClientModel.ClientResult, System.Collections.Generic.IEnumerable<T>, System.Collections.IEnumerable
     {
-        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; }
+        protected internal CollectionResult() { }
+        protected internal CollectionResult(System.ClientModel.Primitives.PipelineResponse response) { }
+        public abstract System.Collections.Generic.IEnumerator<T> GetEnumerator();
+        System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator() { throw null; }
     }
-    public abstract partial class ResultCollection<T> : System.ClientModel.ClientResult, System.Collections.Generic.IEnumerable<T>, System.Collections.IEnumerable
+    public partial class ContinuationToken
     {
-        protected internal ResultCollection() { }
-        protected internal ResultCollection(System.ClientModel.Primitives.PipelineResponse response) { }
-        public abstract System.Collections.Generic.IEnumerator<T> GetEnumerator();
+        protected ContinuationToken() { }
+        protected ContinuationToken(System.BinaryData bytes) { }
+        public static System.ClientModel.ContinuationToken FromBytes(System.BinaryData bytes) { throw null; }
+        public virtual System.BinaryData ToBytes() { throw null; }
+    }
+    public abstract partial class PageCollection<T> : System.Collections.Generic.IEnumerable<System.ClientModel.PageResult<T>>, System.Collections.IEnumerable
+    {
+        protected PageCollection() { }
+        public System.Collections.Generic.IEnumerable<T> GetAllValues() { throw null; }
+        public System.ClientModel.PageResult<T> GetCurrentPage() { throw null; }
+        protected abstract System.ClientModel.PageResult<T> GetCurrentPageCore();
+        protected abstract System.Collections.Generic.IEnumerator<System.ClientModel.PageResult<T>> GetEnumeratorCore();
+        System.Collections.Generic.IEnumerator<System.ClientModel.PageResult<T>> System.Collections.Generic.IEnumerable<System.ClientModel.PageResult<T>>.GetEnumerator() { throw null; }
         System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator() { throw null; }
     }
-    public partial class ResultPage<T> : System.ClientModel.ResultCollection<T>
+    public partial class PageResult<T> : System.ClientModel.ClientResult
     {
-        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; }
+        internal PageResult() { }
+        public System.ClientModel.ContinuationToken? NextPageToken { get { throw null; } }
+        public System.ClientModel.ContinuationToken PageToken { get { throw null; } }
+        public System.Collections.Generic.IReadOnlyList<T> Values { get { throw null; } }
+        public static System.ClientModel.PageResult<T> Create(System.Collections.Generic.IReadOnlyList<T> values, System.ClientModel.ContinuationToken pageToken, System.ClientModel.ContinuationToken? nextPageToken, System.ClientModel.Primitives.PipelineResponse response) { throw null; }
     }
 }
 namespace System.ClientModel.Primitives

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

@@ -7,17 +7,20 @@ 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>
+    public abstract partial class AsyncCollectionResult<T> : System.ClientModel.ClientResult, System.Collections.Generic.IAsyncEnumerable<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; }
+        protected internal AsyncCollectionResult() { }
+        protected internal AsyncCollectionResult(System.ClientModel.Primitives.PipelineResponse response) { }
+        public abstract System.Collections.Generic.IAsyncEnumerator<T> GetAsyncEnumerator(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken));
     }
-    public abstract partial class AsyncResultCollection<T> : System.ClientModel.ClientResult, System.Collections.Generic.IAsyncEnumerable<T>
+    public abstract partial class AsyncPageCollection<T> : System.Collections.Generic.IAsyncEnumerable<System.ClientModel.PageResult<T>>
     {
-        protected internal AsyncResultCollection() { }
-        protected internal AsyncResultCollection(System.ClientModel.Primitives.PipelineResponse response) { }
-        public abstract System.Collections.Generic.IAsyncEnumerator<T> GetAsyncEnumerator(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken));
+        protected AsyncPageCollection() { }
+        public System.Collections.Generic.IAsyncEnumerable<T> GetAllValuesAsync([System.Runtime.CompilerServices.EnumeratorCancellationAttribute] System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        protected abstract System.Collections.Generic.IAsyncEnumerator<System.ClientModel.PageResult<T>> GetAsyncEnumeratorCore(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken));
+        public System.Threading.Tasks.Task<System.ClientModel.PageResult<T>> GetCurrentPageAsync() { throw null; }
+        protected abstract System.Threading.Tasks.Task<System.ClientModel.PageResult<T>> GetCurrentPageAsyncCore();
+        System.Collections.Generic.IAsyncEnumerator<System.ClientModel.PageResult<T>> System.Collections.Generic.IAsyncEnumerable<System.ClientModel.PageResult<T>>.GetAsyncEnumerator(System.Threading.CancellationToken cancellationToken) { throw null; }
     }
     public abstract partial class BinaryContent : System.IDisposable
     {
@@ -54,25 +57,37 @@ 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>
+    public abstract partial class CollectionResult<T> : System.ClientModel.ClientResult, System.Collections.Generic.IEnumerable<T>, System.Collections.IEnumerable
     {
-        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; }
+        protected internal CollectionResult() { }
+        protected internal CollectionResult(System.ClientModel.Primitives.PipelineResponse response) { }
+        public abstract System.Collections.Generic.IEnumerator<T> GetEnumerator();
+        System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator() { throw null; }
     }
-    public abstract partial class ResultCollection<T> : System.ClientModel.ClientResult, System.Collections.Generic.IEnumerable<T>, System.Collections.IEnumerable
+    public partial class ContinuationToken
     {
-        protected internal ResultCollection() { }
-        protected internal ResultCollection(System.ClientModel.Primitives.PipelineResponse response) { }
-        public abstract System.Collections.Generic.IEnumerator<T> GetEnumerator();
+        protected ContinuationToken() { }
+        protected ContinuationToken(System.BinaryData bytes) { }
+        public static System.ClientModel.ContinuationToken FromBytes(System.BinaryData bytes) { throw null; }
+        public virtual System.BinaryData ToBytes() { throw null; }
+    }
+    public abstract partial class PageCollection<T> : System.Collections.Generic.IEnumerable<System.ClientModel.PageResult<T>>, System.Collections.IEnumerable
+    {
+        protected PageCollection() { }
+        public System.Collections.Generic.IEnumerable<T> GetAllValues() { throw null; }
+        public System.ClientModel.PageResult<T> GetCurrentPage() { throw null; }
+        protected abstract System.ClientModel.PageResult<T> GetCurrentPageCore();
+        protected abstract System.Collections.Generic.IEnumerator<System.ClientModel.PageResult<T>> GetEnumeratorCore();
+        System.Collections.Generic.IEnumerator<System.ClientModel.PageResult<T>> System.Collections.Generic.IEnumerable<System.ClientModel.PageResult<T>>.GetEnumerator() { throw null; }
         System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator() { throw null; }
     }
-    public partial class ResultPage<T> : System.ClientModel.ResultCollection<T>
+    public partial class PageResult<T> : System.ClientModel.ClientResult
     {
-        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; }
+        internal PageResult() { }
+        public System.ClientModel.ContinuationToken? NextPageToken { get { throw null; } }
+        public System.ClientModel.ContinuationToken PageToken { get { throw null; } }
+        public System.Collections.Generic.IReadOnlyList<T> Values { get { throw null; } }
+        public static System.ClientModel.PageResult<T> Create(System.Collections.Generic.IReadOnlyList<T> values, System.ClientModel.ContinuationToken pageToken, System.ClientModel.ContinuationToken? nextPageToken, System.ClientModel.Primitives.PipelineResponse response) { throw null; }
     }
 }
 namespace System.ClientModel.Primitives

sdk/core/System.ClientModel/src/Convenience/AsyncResultCollectionOfT.cs → sdk/core/System.ClientModel/src/Convenience/AsyncCollectionResultOfT.cs

@@ -8,12 +8,13 @@
 namespace System.ClientModel;
 
 /// <summary>
-/// Represents a collection of results returned from a cloud service operation.
+/// Represents a collection of values returned from a cloud service operation.
+/// The collection values may be returned by one or more service responses.
 /// </summary>
-public abstract class AsyncResultCollection<T> : ClientResult, IAsyncEnumerable<T>
+public abstract class AsyncCollectionResult<T> : ClientResult, IAsyncEnumerable<T>
 {
     /// <summary>
-    /// Create a new instance of <see cref="AsyncResultCollection{T}"/>.
+    /// Create a new instance of <see cref="AsyncCollectionResult{T}"/>.
     /// </summary>
     /// <remarks>If no <see cref="PipelineResponse"/> is provided when the
     /// <see cref="ClientResult"/> instance is created, it is expected that
@@ -24,17 +25,17 @@ public abstract class AsyncResultCollection<T> : ClientResult, IAsyncEnumerable<
     /// is called. Such implementations will typically be returned from client
     /// convenience methods so that callers of the methods don't need to
     /// dispose the return value. </remarks>
-    protected internal AsyncResultCollection() : base()
+    protected internal AsyncCollectionResult() : base()
     {
     }
 
     /// <summary>
-    /// Create a new instance of <see cref="AsyncResultCollection{T}"/>.
+    /// Create a new instance of <see cref="AsyncCollectionResult{T}"/>.
     /// </summary>
     /// <param name="response">The <see cref="PipelineResponse"/> holding the
     /// items in the collection, or the first set of the items in the collection.
     /// </param>
-    protected internal AsyncResultCollection(PipelineResponse response) : base(response)
+    protected internal AsyncCollectionResult(PipelineResponse response) : base(response)
     {
     }
 

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

@@ -0,0 +1,75 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System.Collections.Generic;
+using System.Runtime.CompilerServices;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace System.ClientModel;
+
+/// <summary>
+/// An asynchronous collection of page results returned by a cloud service.
+/// Cloud services use pagination to return a collection of items over multiple
+/// responses.  Each response from the service returns a page of items in the
+/// collection, as well as the information needed to obtain the next page of
+/// items, until all the items in the requested collection have been returned.
+/// To enumerate the items in the collection, instead of the pages in the
+/// collection, call <see cref="GetAllValuesAsync"/>.  To get the current
+/// collection page, call <see cref="GetCurrentPageAsync"/>.
+/// </summary>
+public abstract class AsyncPageCollection<T> : IAsyncEnumerable<PageResult<T>>
+{
+    /// <summary>
+    /// Create a new instance of <see cref="AsyncPageCollection{T}"/>.
+    /// </summary>
+    protected AsyncPageCollection() : base()
+    {
+        // Note that page collections delay making a first request until either
+        // GetCurrentPageAsync is called or the collection returned by
+        // GetAllValuesAsync is enumerated, so this constructor calls the base
+        // class constructor that does not take a PipelineResponse.
+    }
+
+    /// <summary>
+    /// Get the current page of the collection.
+    /// </summary>
+    /// <returns>The current page in the collection.</returns>
+    public async Task<PageResult<T>> GetCurrentPageAsync()
+        => await GetCurrentPageAsyncCore().ConfigureAwait(false);
+
+    /// <summary>
+    /// Get a collection of all the values in the collection requested from the
+    /// cloud service, rather than the pages of values.
+    /// </summary>
+    /// <returns>The values requested from the cloud service.</returns>
+    public async IAsyncEnumerable<T> GetAllValuesAsync([EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        await foreach (PageResult<T> page in this.WithCancellation(cancellationToken).ConfigureAwait(false))
+        {
+            foreach (T value in page.Values)
+            {
+                cancellationToken.ThrowIfCancellationRequested();
+
+                yield return value;
+            }
+        }
+    }
+
+    /// <summary>
+    /// Get the current page of the collection.
+    /// </summary>
+    /// <returns>The current page in the collection.</returns>
+    protected abstract Task<PageResult<T>> GetCurrentPageAsyncCore();
+
+    /// <summary>
+    /// Get an async enumerator that can enumerate the pages of values returned
+    /// by the cloud service.
+    /// </summary>
+    /// <returns>An async enumerator of pages holding the items in the value
+    /// collection.</returns>
+    protected abstract IAsyncEnumerator<PageResult<T>> GetAsyncEnumeratorCore(CancellationToken cancellationToken = default);
+
+    IAsyncEnumerator<PageResult<T>> IAsyncEnumerable<PageResult<T>>.GetAsyncEnumerator(CancellationToken cancellationToken)
+        => GetAsyncEnumeratorCore(cancellationToken);
+}