Add backcompat support for top parameter

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/src/Providers/RestClientProvider.cs

@@ -871,27 +871,22 @@ private static bool TryGetSpecialHeaderParam(InputParameter inputParameter, [Not
                 : null;
         }
 
-        private static string GetCorrectedPageSizeName(string originalName, ClientProvider client)
+        private static string GetCorrectedParameterName(string originalName, string? updatedName, ClientProvider client)
         {
-            // Check if parameter exists in LastContractView for backward compatibility
+            // Check if the original parameter name exists in LastContractView for backward compatibility
             var existingParam = client.LastContractView?.Methods
                 ?.SelectMany(method => method.Signature.Parameters)
                 .FirstOrDefault(parameter => string.Equals(parameter.Name, originalName, StringComparison.OrdinalIgnoreCase))
                 ?.Name;
 
             if (existingParam != null)
             {
+                // Preserve the exact name (including casing) from the previous contract for backward compatibility
                 return existingParam;
             }
 
-            // Normalize badly-cased "maxpagesize" variants to Camel Case
-            if (string.Equals(originalName, MaxPageSizeParameterName, StringComparison.OrdinalIgnoreCase))
-            {
-                return MaxPageSizeParameterName;
-            }
-
-            // Keep original name for all other cases
-            return originalName;
+            // If an updated name is provided, use it; otherwise keep the original name
+            return updatedName ?? originalName;
         }
 
         private static bool ShouldUpdateReinjectedParameter(InputParameter inputParameter, InputPagingServiceMethod? pagingServiceMethod)
@@ -965,7 +960,11 @@ internal static List<ParameterProvider> GetMethodParameters(
             string? correctedPageSizeName = null;
             if (pageSizeParameterName != null)
             {
-                correctedPageSizeName = GetCorrectedPageSizeName(pageSizeParameterName, client);
+                // For page size parameters, normalize badly-cased "maxpagesize" variants to proper camelCase
+                var normalizedPageSizeName = string.Equals(pageSizeParameterName, MaxPageSizeParameterName, StringComparison.OrdinalIgnoreCase)
+                    ? MaxPageSizeParameterName
+                    : pageSizeParameterName;
+                correctedPageSizeName = GetCorrectedParameterName(pageSizeParameterName, normalizedPageSizeName, client);
             }
 
             ModelProvider? spreadSource = null;
@@ -1013,11 +1012,15 @@ internal static List<ParameterProvider> GetMethodParameters(
                     continue;
                 }
 
-                // For paging operations, rename "top" parameter to "maxCount"
+                // For paging operations, rename "top" parameter to "maxCount" (with backward compatibility)
                 if (serviceMethod is InputPagingServiceMethod &&
                     string.Equals(inputParam.Name, TopParameterName, StringComparison.OrdinalIgnoreCase))
                 {
-                    inputParam.Update(name: MaxCountParameterName);
+                    var correctedMaxCountName = GetCorrectedParameterName(TopParameterName, MaxCountParameterName, client);
+                    if (!string.Equals(inputParam.Name, correctedMaxCountName, StringComparison.Ordinal))
+                    {
+                        inputParam.Update(name: correctedMaxCountName);
+                    }
                 }
 
                 // For paging operations, ensure page size parameter uses the correct casing

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/CollectionResultDefinitions/ListPageableTests.cs

@@ -1,10 +1,14 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+using System;
+using System.Collections.Generic;
 using System.Linq;
+using System.Threading.Tasks;
 using Microsoft.TypeSpec.Generator.ClientModel.Providers;
 using Microsoft.TypeSpec.Generator.Input;
 using Microsoft.TypeSpec.Generator.Primitives;
+using Microsoft.TypeSpec.Generator.Providers;
 using Microsoft.TypeSpec.Generator.Tests.Common;
 using NUnit.Framework;
 
@@ -69,6 +73,67 @@ public void TopParameterRenamedToMaxCountInPagingOperation()
             Assert.Contains("maxCount", parameterNames, "Should contain 'maxCount' parameter");
             Assert.IsFalse(parameterNames.Contains("top"), "Should not contain 'top' parameter after renaming");
         }
+
+        [Test]
+        public async Task TopParameterPreservedWhenExistsInLastContractView()
+        {
+            // This test verifies that when a "top" parameter exists in LastContractView,
+            // it is preserved for backward compatibility instead of being converted to "maxCount"
+            var topParameter = InputFactory.QueryParameter("top", InputPrimitiveType.Int32, isRequired: false, serializedName: "top");
+
+            List<InputParameter> parameters = [topParameter];
+            List<InputMethodParameter> methodParameters =
+            [
+                InputFactory.MethodParameter("top", InputPrimitiveType.Int32, isRequired: false,
+                    location: InputRequestLocation.Query, serializedName: "top"),
+            ];
+
+            var inputModel = InputFactory.Model("Item", properties:
+            [
+                InputFactory.Property("id", InputPrimitiveType.String, isRequired: true),
+            ]);
+
+            var pagingMetadata = new InputPagingServiceMetadata(
+                ["items"],
+                new InputNextLink(null, ["nextLink"], InputResponseLocation.Body, []),
+                null,
+                null);
+
+            var response = InputFactory.OperationResponse(
+                [200],
+                InputFactory.Model(
+                    "PagedItems",
+                    properties: [
+                        InputFactory.Property("items", InputFactory.Array(inputModel)),
+                        InputFactory.Property("nextLink", InputPrimitiveType.Url)
+                    ]));
+
+            var operation = InputFactory.Operation("getItems", responses: [response], parameters: parameters);
+            var inputServiceMethod = InputFactory.PagingServiceMethod(
+                "getItems",
+                operation,
+                pagingMetadata: pagingMetadata,
+                parameters: methodParameters);
+
+            var client = InputFactory.Client("testClient", methods: [inputServiceMethod]);
+
+            var generator = await MockHelpers.LoadMockGeneratorAsync(
+                clients: () => [client],
+                lastContractCompilation: async () => await Helpers.GetCompilationFromDirectoryAsync());
+
+            var clientProvider = generator.Object.OutputLibrary.TypeProviders.OfType<ClientProvider>().FirstOrDefault();
+            Assert.IsNotNull(clientProvider);
+            Assert.IsNotNull(clientProvider!.LastContractView);
+
+            var methodParams = RestClientProvider.GetMethodParameters(inputServiceMethod, ScmMethodKind.Convenience, clientProvider!);
+
+            var topParam = methodParams.FirstOrDefault(p =>
+                string.Equals(p.Name, "top", StringComparison.Ordinal));
+
+            Assert.IsNotNull(topParam, "Top parameter should be present in method parameters");
+            Assert.AreEqual("top", topParam!.Name,
+                "Parameter name should be 'top' (from LastContractView), not 'maxCount' (conversion should be prevented)");
+        }
 
         [Test]
         public void NoNextLinkOrContinuationTokenOfT()

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/CollectionResultDefinitions/TestData/ListPageableTests/TopParameterPreservedWhenExistsInLastContractView/TestClient.cs

@@ -0,0 +1,15 @@
+#nullable disable
+
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using System.Threading.Tasks;
+
+namespace Sample
+{
+    public partial class TestClient
+    {
+        // This represents the previous contract with top parameter
+        public virtual Task<ClientResult> GetItemsAsync(int? top, CancellationToken cancellationToken = default) { return null; }
+        public virtual ClientResult GetItems(int? top, CancellationToken cancellationToken = default) { return null; }
+    }
+}

packages/http-client-csharp/generator/docs/backward-compatibility.md

@@ -11,7 +11,9 @@
   - [API Version Enum](#api-version-enum)
   - [Non-abstract Base Models](#non-abstract-base-models)
   - [Model Constructors](#model-constructors)
-  - [Parameter Name Casing](#parameter-name-casing)
+  - [Parameter Naming](#parameter-naming)
+    - [Page Size Parameter Casing Correction](#scenario-page-size-parameter-casing-correction)
+    - [Top Parameter Conversion to MaxCount](#scenario-top-parameter-conversion-to-maxcount)
 
 ## Overview
 
@@ -361,9 +363,9 @@ public abstract partial class SearchIndexerDataIdentity
 - The modifier is changed from `private protected` to `public`
 - No additional constructors are generated; only the accessibility is adjusted
 
-### Parameter Name Casing
+### Parameter Naming
 
-The generator maintains backward compatibility for parameter names to ensure that existing code continues to compile when parameter name casing is corrected or standardized.
+The generator maintains backward compatibility for parameter names to ensure that existing code continues to compile when parameter names are corrected, standardized, or converted to follow naming conventions.
 
 #### Scenario: Page Size Parameter Casing Correction
 
@@ -475,3 +477,116 @@ public virtual AsyncPageable<Item> GetItemsAsync(int? maxPageSize = null, Cancel
 - **Case 2 (Normalization)**: If the parameter does NOT exist in LastContractView, badly-cased variants are normalized to proper camelCase
 - The HTTP query parameter always uses the original serialized name from the spec (e.g., `maxpagesize`)
 - Existing client code continues to compile without changes
+
+#### Scenario: Top Parameter Conversion to MaxCount
+
+**Description:** For paging operations, the generator converts the `top` parameter to `maxCount` to follow standard naming conventions. However, backward compatibility is maintained in two ways:
+
+1. **If the `top` parameter exists in LastContractView**: The generator preserves the `top` parameter name (with its exact casing) to maintain backward compatibility
+2. **If the `top` parameter does NOT exist in LastContractView**: The generator converts `top` to the standardized `maxCount` parameter name
+
+This commonly occurs when:
+
+- Migrating from an older API version or generator that used `top` for pagination limits
+- TypeSpec defines paging operations with a `top` parameter
+- The generator needs to standardize on `maxCount` while maintaining backward compatibility
+
+**Example:**
+
+**Case 1: Top parameter exists in LastContractView - preserved for backward compatibility**
+
+Previous version had `top` parameter:
+
+```csharp
+public virtual AsyncPageable<Item> GetItemsAsync(int? top = null, CancellationToken cancellationToken = default)
+{
+    HttpMessage CreateRequest()
+    {
+        var message = pipeline.CreateMessage();
+        var request = message.Request;
+        request.Method = RequestMethod.Get;
+        var uri = new RequestUriBuilder();
+        uri.Reset(endpoint);
+        uri.AppendPath("/items", false);
+        if (top != null)
+        {
+            uri.AppendQuery("top", top.Value, true);  // Serialized name from spec
+        }
+        // ...
+    }
+    // ...
+}
+```
+
+Current TypeSpec still defines `top` parameter:
+
+```typespec
+op getItems(@query top?: int32): Page<Item>;
+```
+
+**Generated Compatibility Result:**
+
+The generator detects the `top` parameter in LastContractView and preserves it exactly to maintain backward compatibility:
+
+```csharp
+public virtual AsyncPageable<Item> GetItemsAsync(int? top = null, CancellationToken cancellationToken = default)
+{
+    HttpMessage CreateRequest()
+    {
+        var message = pipeline.CreateMessage();
+        var request = message.Request;
+        request.Method = RequestMethod.Get;
+        var uri = new RequestUriBuilder();
+        uri.Reset(endpoint);
+        uri.AppendPath("/items", false);
+        if (top != null)
+        {
+            uri.AppendQuery("top", top.Value, true);  // Still uses "top" for backward compatibility
+        }
+        // ...
+    }
+    // ...
+}
+```
+
+**Case 2: Top parameter does NOT exist in LastContractView - converted to maxCount**
+
+New paging operation with `top` parameter (no previous version):
+
+```typespec
+op getItems(@query top?: int32): Page<Item>;
+```
+
+**Generated Result:**
+
+The generator converts the parameter name to standardized `maxCount` since there's no previous version to maintain compatibility with:
+
+```csharp
+public virtual AsyncPageable<Item> GetItemsAsync(int? maxCount = null, CancellationToken cancellationToken = default)
+{
+    HttpMessage CreateRequest()
+    {
+        var message = pipeline.CreateMessage();
+        var request = message.Request;
+        request.Method = RequestMethod.Get;
+        var uri = new RequestUriBuilder();
+        uri.Reset(endpoint);
+        uri.AppendPath("/items", false);
+        if (maxCount != null)
+        {
+            uri.AppendQuery("top", maxCount.Value, true);  // Serialized name still uses "top" from spec
+        }
+        // ...
+    }
+    // ...
+}
+```
+
+**Key Points:**
+
+- **Case 1 (Backward compatibility)**: If `top` parameter exists in LastContractView, its exact name and casing are preserved
+- **Case 2 (Standardization)**: If `top` parameter does NOT exist in LastContractView, it is converted to `maxCount` for consistency
+- The HTTP query parameter always uses the original serialized name from the spec (e.g., `top`)
+- This conversion is specific to paging operations only
+- Existing client code with `top` continues to compile without changes
+- New code benefits from the standardized `maxCount` naming convention