Merge pull request #33 from FrendsPlatform/issue-32

Pagination support for querying objects

Author: jefim

Frends.LDAP.SearchObjects/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [4.0.0] - 2025-04-04
+### Added
+- [Breaking] - Parameter for PageSize to control how many entries are fetched per page during an LDAP search.
+- Default value for the new parameter:
+  - PageSize: 500
+- If you want the Task to work exactly as before (non-paged search), set PageSize = 0.
+- Default paging behavior (PageSize = 500) may improve performance on large result sets, 
+  but changes how results are retrieved from the server.
+
 ## [3.1.0] - 2025-04-01
 ### Added
 - Added example values for new parameters.

Frends.LDAP.SearchObjects/Frends.LDAP.SearchObjects.Tests/UnitTests.cs

@@ -367,6 +367,7 @@ public void Search_Filter_Test()
             SearchDereference = SearchDereference.DerefNever,
             MaxResults = default,
             BatchSize = default,
+            PageSize = 500,
             TypesOnly = default,
             Attributes = null,
         };
@@ -557,4 +558,58 @@ public void CreateTestUsers()
 
         conn.Disconnect();
     }
+
+    [TestMethod]
+    public void Search_MaxResults_LessThanAvailable_ReturnsLimitedResults()
+    {
+        input = new()
+        {
+            SearchBase = _path,
+            Scope = Scopes.ScopeSub,
+            Filter = null,
+            MaxResults = 2,
+            PageSize = 3,
+        };
+
+        var result = LDAP.SearchObjects(input, connection, default);
+
+        Assert.IsTrue(result.Success, "Search failed.");
+        Assert.AreEqual(2, result.SearchResult.Count, "Should return only 2 results.");
+    }
+
+    [TestMethod]
+    public void Search_PageSizeSmallerThanTotal_ShouldReturnAll()
+    {
+        input = new()
+        {
+            SearchBase = _path,
+            Scope = Scopes.ScopeSub,
+            Filter = null,
+            MaxResults = 5,
+            PageSize = 2,
+        };
+
+        var result = LDAP.SearchObjects(input, connection, default);
+
+        Assert.IsTrue(result.Success, "Search failed.");
+        Assert.AreEqual(5, result.SearchResult.Count, "Should return all 5 results using paging.");
+    }
+
+    [TestMethod]
+    public void Search_PageSizeZero_DisablesPaging()
+    {
+        input = new()
+        {
+            SearchBase = _path,
+            Scope = Scopes.ScopeSub,
+            Filter = null,
+            MaxResults = 5,
+            PageSize = 0, // No paging
+        };
+
+        var result = LDAP.SearchObjects(input, connection, default);
+
+        Assert.IsTrue(result.Success, "Search failed.");
+        Assert.AreEqual(5, result.SearchResult.Count, "Should return all 5 results without paging.");
+    }
 }

Frends.LDAP.SearchObjects/Frends.LDAP.SearchObjects/Definitions/Input.cs

@@ -51,19 +51,30 @@ public class Input
     public SearchDereference SearchDereference { get; set; }
 
     /// <summary>
-    /// The maximum number of search results to return for a search request.
+    /// The maximum number of search results to return. 
+    /// This acts as a hard limit—regardless of page size or batch size, no more than this number of results will be returned.
+    /// Set to 0 for no limit.
     /// </summary>
     /// <example>1000</example>
     [DefaultValue(1000)]
     public int MaxResults { get; set; }
 
     /// <summary>
-    /// The number of results to return in a batch. Specifying 0 means to block until all results are received. Specifying 1 means to return results one result at a time.
+    /// This parameter controls the chunk size in which data will be read from the server. This does not affect the output result amount.
     /// </summary>
     /// <example>1</example>
-    [DefaultValue(1)]
+    [DefaultValue(100)]
     public int BatchSize { get; set; }
 
+    /// <summary>
+    /// Controls how many entries are requested from the server in a single page during a paged LDAP search.
+    /// This directly affects how results are fetched from the server.
+    /// If set to 0, paging is disabled and all entries are requested in a single operation (not recommended for large directories).
+    /// </summary>
+    /// <example>1</example>
+    [DefaultValue(500)]
+    public int PageSize { get; set; }
+
     /// <summary>
     /// If true, returns the names but not the values of the attributes found. 
     /// If false, returns the names and values for attributes found.

Frends.LDAP.SearchObjects/Frends.LDAP.SearchObjects/Frends.LDAP.SearchObjects.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
 	<TargetFrameworks>net6.0</TargetFrameworks>
-	<Version>3.1.0</Version>
+	<Version>4.0.0</Version>
 	<Authors>Frends</Authors>
 	<Copyright>Frends</Copyright>
 	<Company>Frends</Company>

Frends.LDAP.SearchObjects/Frends.LDAP.SearchObjects/SearchObjects.cs

@@ -1,6 +1,7 @@
 using Frends.LDAP.SearchObjects.Definitions;
 using System.ComponentModel;
 using Novell.Directory.Ldap;
+using Novell.Directory.Ldap.Controls;
 using System;
 using System.Collections.Generic;
 using System.Threading;
@@ -41,10 +42,10 @@ public static Result SearchObjects([PropertyTab] Input input, [PropertyTab] Conn
         if (connection.IgnoreCertificates)
             ldco.ConfigureRemoteCertificateValidationCallback((sender, certificate, chain, errors) => true);
 
-        LdapConnection conn = new LdapConnection(ldco);
         var defaultPort = connection.SecureSocketLayer ? 636 : 389;
         var atr = new List<string>();
         var searchResults = new List<SearchResult>();
+
         var searchConstraints = new LdapSearchConstraints(
                 input.MsLimit,
                 input.ServerTimeLimit,
@@ -53,7 +54,8 @@ public static Result SearchObjects([PropertyTab] Input input, [PropertyTab] Conn
                 false,
                 input.BatchSize,
                 null,
-                0);
+                0
+        );
 
         if (input.Attributes != null && input.SearchOnlySpecifiedAttributes)
             foreach (var i in input.Attributes)
@@ -75,8 +77,10 @@ public static Result SearchObjects([PropertyTab] Input input, [PropertyTab] Conn
 
         try
         {
+            using var conn = new LdapConnection(ldco);
             conn.SecureSocketLayer = connection.SecureSocketLayer;
             conn.Connect(connection.Host, connection.Port == 0 ? defaultPort : connection.Port);
+
             if (connection.TLS)
                 conn.StartTls();
 
@@ -85,35 +89,28 @@ public static Result SearchObjects([PropertyTab] Input input, [PropertyTab] Conn
             else
                 conn.Bind(version: ldapVersion, connection.User, connection.Password);
 
-            LdapSearchQueue queue = conn.Search(
-                input.SearchBase,
-                SetScope(input),
-                string.IsNullOrEmpty(input.Filter) ? null : input.Filter,
-                atr.ToArray(),
-                input.TypesOnly,
-                null,
-                searchConstraints);
+            byte[] cookie = null;
 
-            LdapMessage message;
-            while ((message = queue.GetResponse()) != null)
+            do
             {
-                if (message is LdapSearchResult ldapSearchResult)
+                if (input.PageSize > 0)
                 {
-                    var entry = ldapSearchResult.Entry;
-                    var attributeDict = new Dictionary<string, dynamic>();
-                    var getAttributeSet = entry.GetAttributeSet();
-                    var ienum = getAttributeSet.GetEnumerator();
+                    var pagedResultsControl = new SimplePagedResultsControl(input.PageSize, cookie);
+                    searchConstraints.SetControls(pagedResultsControl);
+                }
 
-                    while (ienum.MoveNext())
-                    {
-                        cancellationToken.ThrowIfCancellationRequested();
-                        LdapAttribute attribute = ienum.Current;
-                        AddAttributeValueToList(input, attribute, attributeDict, encoding, cancellationToken);
-                    }
+                LdapSearchQueue queue = conn.Search(
+                    input.SearchBase,
+                    SetScope(input),
+                    string.IsNullOrEmpty(input.Filter) ? null : input.Filter,
+                    atr.ToArray(),
+                    input.TypesOnly,
+                    null,
+                    searchConstraints);
+
+                ProcessSearchResults(queue, searchResults, cancellationToken, encoding, input, ref cookie);
+            } while (cookie != null && cookie.Length > 0);
 
-                    searchResults.Add(new SearchResult() { DistinguishedName = entry.Dn, AttributeSet = attributeDict });
-                }
-            }
             return new Result(true, null, searchResults);
         }
         catch (LdapException ex)
@@ -124,12 +121,47 @@ public static Result SearchObjects([PropertyTab] Input input, [PropertyTab] Conn
         }
         catch (Exception ex)
         {
-            throw new Exception($"SearchObjects error: {ex}");
+            throw new Exception("SearchObjects error", ex);
         }
-        finally
+    }
+
+    private static void ProcessSearchResults(LdapSearchQueue queue, List<SearchResult> searchResults, CancellationToken cancellationToken, Encoding encoding, Input input, ref byte[] cookie)
+    {
+        LdapMessage message;
+        while ((message = queue.GetResponse()) != null)
         {
-            if (connection.TLS) conn.StopTls();
-            conn.Disconnect();
+            cancellationToken.ThrowIfCancellationRequested();
+
+            if (message is LdapSearchResult ldapSearchResult)
+            {
+                var entry = ldapSearchResult.Entry;
+                var attributeDict = new Dictionary<string, dynamic>();
+                var getAttributeSet = entry.GetAttributeSet();
+                var ienum = getAttributeSet.GetEnumerator();
+
+                while (ienum.MoveNext())
+                {
+                    cancellationToken.ThrowIfCancellationRequested();
+                    LdapAttribute attribute = ienum.Current;
+                    AddAttributeValueToList(input, attribute, attributeDict, encoding, cancellationToken);
+                }
+
+                searchResults.Add(new SearchResult() { DistinguishedName = entry.Dn, AttributeSet = attributeDict });
+            }
+            else if (message is LdapResponse ldapResponse)
+            {
+                var controls = ldapResponse.Controls;
+                if (controls != null)
+                {
+                    foreach (var control in controls)
+                    {
+                        if (control is SimplePagedResultsControl pagedResultsResponse)
+                        {
+                            cookie = pagedResultsResponse.Cookie;
+                        }
+                    }
+                }
+            }
         }
     }