[http-client-csharp] Place contentType after body per .NET SDK parameter ordering guideline (#10403)

Operations with a `contentType` header placed it before body, violating
the <a
href="https://azure.github.io/azure-sdk/dotnet_implementation.html#parameter-presence-and-ordering">.NET
SDK parameter ordering guideline</a>. This applies to all operations
(both multipart and non-multipart).

**Before:**
```csharp
UpdateSkillDefaultVersion(string skillId, string contentType, BinaryContent content, RequestOptions options = null)
```

**After:**
```csharp
UpdateSkillDefaultVersion(string skillId, BinaryContent content, string contentType, RequestOptions options = null)
```

### Changes

- **`RestClientProvider.GetMethodParameters`**: Added a `contentType`
sorting bucket (350) between body (200/300) and optional query/header
(400). Content-type headers detected via
`InputHeaderParameter.IsContentType` are routed to this bucket instead
of the regular required/optional header buckets. Updated the
`IsMultipartFormData` content-type insertion to also use the
`contentType` bucket for consistency.
- **Back-compat via `BackCompatProvider`**: Added
`HasContentTypeBeforeBodyInLastContract` helper that checks
`client.BackCompatProvider.LastContractView` for a matching method where
`contentType` appears before `content` (body). If the previous contract
had that ordering, the content-type parameter falls through to the
regular header bucket to preserve backward compatibility.
- **Tests**: Added parameterized
`TestGetMethodParameters_ContentTypeAfterBody(bool isRequired, bool
isExtensibleEnum)` using `[TestCase]` to cover all four combinations of
required/optional and string/extensible-enum content-type headers. Added
`ContentTypeOrderPreservedFromLastContractView` validating that the
previous ordering is preserved when the last contract had contentType
before body, and `ContentTypeAfterBodyInLastContractView` validating
correct ordering when the last contract already had contentType after
body.
- **Documentation**: Updated `backward-compatibility.md` with a new
"Content-Type Parameter Ordering" section documenting the back-compat
preservation case.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com>

Author: Copilot

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

@@ -1007,6 +1007,7 @@ internal static List<ParameterProvider> GetMethodParameters(
             int required = 100;
             int bodyRequired = 200;
             int bodyOptional = 300;
+            int contentType = 350;
             int optional = 400;
 
             var operation = serviceMethod.Operation;
@@ -1124,7 +1125,12 @@ internal static List<ParameterProvider> GetMethodParameters(
                         break;
                     case ParameterLocation.Query:
                     case ParameterLocation.Header:
-                        if (parameter.DefaultValue == null)
+                        if (inputParam is InputHeaderParameter { IsContentType: true }
+                            && !HasContentTypeBeforeBodyInLastContract(serviceMethod.Name, client.BackCompatProvider))
+                        {
+                            sortedParams.Add(contentType++, parameter);
+                        }
+                        else if (parameter.DefaultValue == null)
                         {
                             sortedParams.Add(required++, parameter);
                         }
@@ -1144,7 +1150,7 @@ internal static List<ParameterProvider> GetMethodParameters(
 
             if (operation.IsMultipartFormData)
             {
-                sortedParams.Add(bodyRequired++, ScmKnownParameters.ContentType);
+                sortedParams.Add(contentType++, ScmKnownParameters.ContentType);
             }
 
             if (methodType == ScmMethodKind.CreateRequest)
@@ -1159,6 +1165,62 @@ internal static List<ParameterProvider> GetMethodParameters(
             return [.. sortedParams.Values];
         }
 
+        /// <summary>
+        /// Checks if the last contract view contains a method matching the given name where
+        /// a "contentType" parameter appears before the body ("content") parameter.
+        /// If so, we should preserve that ordering for backward compatibility.
+        /// </summary>
+        private static bool HasContentTypeBeforeBodyInLastContract(string methodName, TypeProvider backCompatProvider)
+        {
+            const string contentTypeParamName = "contentType";
+            const string contentParamName = "content";
+
+            var lastContractMethods = backCompatProvider.LastContractView?.Methods;
+            if (lastContractMethods == null || lastContractMethods.Count == 0)
+            {
+                return false;
+            }
+
+            var syncMethodName = methodName;
+            var asyncMethodName = methodName + "Async";
+
+            foreach (var method in lastContractMethods)
+            {
+                if (!string.Equals(method.Signature.Name, syncMethodName, StringComparison.OrdinalIgnoreCase)
+                    && !string.Equals(method.Signature.Name, asyncMethodName, StringComparison.OrdinalIgnoreCase))
+                {
+                    continue;
+                }
+
+                int contentTypeIndex = -1;
+                int bodyIndex = -1;
+                for (int i = 0; i < method.Signature.Parameters.Count; i++)
+                {
+                    var param = method.Signature.Parameters[i];
+                    if (string.Equals(param.Name, contentTypeParamName, StringComparison.OrdinalIgnoreCase))
+                    {
+                        contentTypeIndex = i;
+                    }
+                    else if (string.Equals(param.Name, contentParamName, StringComparison.OrdinalIgnoreCase))
+                    {
+                        bodyIndex = i;
+                    }
+
+                    if (contentTypeIndex >= 0 && bodyIndex >= 0)
+                    {
+                        break;
+                    }
+                }
+
+                if (contentTypeIndex >= 0 && bodyIndex >= 0 && contentTypeIndex < bodyIndex)
+                {
+                    return true;
+                }
+            }
+
+            return false;
+        }
+
         internal static InputModelType GetSpreadParameterModel(InputParameter inputParam)
         {
             if (inputParam.Type is InputModelType model)

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/RestClientProviders/RestClientProviderTests.cs

@@ -233,6 +233,135 @@ public void TestGetMethodParameters_ProperOrdering()
             Assert.AreEqual("b", orderedPathParams[2].Name);
         }
 
+        [TestCase(true, false)]
+        [TestCase(false, false)]
+        [TestCase(true, true)]
+        [TestCase(false, true)]
+        public void TestGetMethodParameters_ContentTypeAfterBody(bool isRequired, bool isExtensibleEnum)
+        {
+            InputType contentTypeType = isExtensibleEnum
+                ? InputFactory.StringEnum("ContentTypeEnum",
+                    [("application/json", "application/json"), ("application/xml", "application/xml")],
+                    isExtensible: true)
+                : InputPrimitiveType.String;
+            var contentTypeHeader = InputFactory.HeaderParameter(
+                "contentType",
+                contentTypeType,
+                isRequired: isRequired,
+                isContentType: true,
+                serializedName: "Content-Type",
+                defaultValue: isRequired ? null : InputFactory.Constant.String("application/json"));
+            var bodyParam = InputFactory.BodyParameter("body", InputPrimitiveType.String, isRequired: true);
+            var pathParam = InputFactory.PathParameter("skillId", InputPrimitiveType.String, isRequired: true);
+
+            var operation = InputFactory.Operation(
+                "UpdateSkillDefaultVersion",
+                parameters: [pathParam, contentTypeHeader, bodyParam]);
+
+            var serviceMethod = InputFactory.BasicServiceMethod(
+                "UpdateSkillDefaultVersion",
+                operation);
+
+            var inputClient = InputFactory.Client("TestClient", methods: [serviceMethod]);
+            var clientProvider = ScmCodeModelGenerator.Instance.TypeFactory.CreateClient(inputClient);
+            Assert.IsNotNull(clientProvider);
+
+            var methodParameters = RestClientProvider.GetMethodParameters(serviceMethod, ScmMethodKind.Protocol, clientProvider!);
+
+            Assert.AreEqual(3, methodParameters.Count);
+            Assert.AreEqual("skillId", methodParameters[0].Name);
+            Assert.AreEqual("content", methodParameters[1].Name);
+            Assert.AreEqual("contentType", methodParameters[2].Name);
+        }
+
+        [Test]
+        public async Task ContentTypeOrderPreservedFromLastContractView()
+        {
+            // Create an operation with a content-type header (union) and body
+            var contentTypeEnum = InputFactory.StringEnum("ContentTypeEnum",
+                [("application/json", "application/json"), ("application/xml", "application/xml")],
+                isExtensible: true);
+            var contentTypeHeader = InputFactory.HeaderParameter(
+                "contentType",
+                contentTypeEnum,
+                isRequired: true,
+                isContentType: true,
+                serializedName: "Content-Type");
+            var bodyParam = InputFactory.BodyParameter("body", InputPrimitiveType.String, isRequired: true);
+            var pathParam = InputFactory.PathParameter("skillId", InputPrimitiveType.String, isRequired: true);
+
+            var operation = InputFactory.Operation(
+                "UpdateSkillDefaultVersion",
+                parameters: [pathParam, contentTypeHeader, bodyParam]);
+
+            var serviceMethod = InputFactory.BasicServiceMethod(
+                "UpdateSkillDefaultVersion",
+                operation);
+
+            var client = InputFactory.Client("TestClient", methods: [serviceMethod]);
+
+            // Load with a last contract that has contentType before body
+            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 methodParameters = RestClientProvider.GetMethodParameters(serviceMethod, ScmMethodKind.Protocol, clientProvider!);
+
+            // When the last contract had contentType before body, the ordering should be preserved
+            Assert.AreEqual(3, methodParameters.Count);
+            Assert.AreEqual("skillId", methodParameters[0].Name);
+            Assert.AreEqual("contentType", methodParameters[1].Name); // contentType stays before body for back-compat
+            Assert.AreEqual("content", methodParameters[2].Name);
+        }
+
+        [Test]
+        public async Task ContentTypeAfterBodyInLastContractView()
+        {
+            // Create an operation with a content-type header (union) and body
+            var contentTypeEnum = InputFactory.StringEnum("ContentTypeEnum",
+                [("application/json", "application/json"), ("application/xml", "application/xml")],
+                isExtensible: true);
+            var contentTypeHeader = InputFactory.HeaderParameter(
+                "contentType",
+                contentTypeEnum,
+                isRequired: true,
+                isContentType: true,
+                serializedName: "Content-Type");
+            var bodyParam = InputFactory.BodyParameter("body", InputPrimitiveType.String, isRequired: true);
+            var pathParam = InputFactory.PathParameter("skillId", InputPrimitiveType.String, isRequired: true);
+
+            var operation = InputFactory.Operation(
+                "UpdateSkillDefaultVersion",
+                parameters: [pathParam, contentTypeHeader, bodyParam]);
+
+            var serviceMethod = InputFactory.BasicServiceMethod(
+                "UpdateSkillDefaultVersion",
+                operation);
+
+            var client = InputFactory.Client("TestClient", methods: [serviceMethod]);
+
+            // Load with a last contract that already has contentType after body
+            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 methodParameters = RestClientProvider.GetMethodParameters(serviceMethod, ScmMethodKind.Protocol, clientProvider!);
+
+            // When the last contract already had contentType after body, the new ordering is used
+            Assert.AreEqual(3, methodParameters.Count);
+            Assert.AreEqual("skillId", methodParameters[0].Name);
+            Assert.AreEqual("content", methodParameters[1].Name);
+            Assert.AreEqual("contentType", methodParameters[2].Name); // contentType after body
+        }
+
         [TestCase(true, true)]
         [TestCase(true, false)]
         [TestCase(false, true)]

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/RestClientProviders/TestData/RestClientProviderTests/ContentTypeAfterBodyInLastContractView/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 a previous contract where contentType already appears after body (content)
+        public virtual Task<ClientResult> UpdateSkillDefaultVersionAsync(string skillId, BinaryContent content, string contentType, RequestOptions options = null) { return null; }
+        public virtual ClientResult UpdateSkillDefaultVersion(string skillId, BinaryContent content, string contentType, RequestOptions options = null) { return null; }
+    }
+}

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/RestClientProviders/TestData/RestClientProviderTests/ContentTypeOrderPreservedFromLastContractView/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 a previous contract where contentType appears before body (content)
+        public virtual Task<ClientResult> UpdateSkillDefaultVersionAsync(string skillId, string contentType, BinaryContent content, RequestOptions options = null) { return null; }
+        public virtual ClientResult UpdateSkillDefaultVersion(string skillId, string contentType, BinaryContent content, RequestOptions options = null) { return null; }
+    }
+}

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

@@ -14,6 +14,8 @@
   - [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)
+  - [Content-Type Parameter Ordering](#content-type-parameter-ordering)
+    - [Content-Type Before Body Preserved from Last Contract](#scenario-content-type-before-body-preserved-from-last-contract)
 
 ## Overview
 
@@ -590,3 +592,47 @@ public virtual AsyncPageable<Item> GetItemsAsync(int? maxCount = null, Cancellat
 - 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
+
+### Content-Type Parameter Ordering
+
+The generator places the `contentType` parameter after the body (`content`) parameter in method signatures. However, backward compatibility is maintained when the last contract had a different ordering.
+
+#### Scenario: Content-Type Before Body Preserved from Last Contract
+
+**Description:** The generator places `contentType` after the `content` (body) parameter. However, if the last contract had `contentType` before `content`, the generator preserves that ordering to avoid breaking existing code.
+
+This commonly occurs when a library was previously generated with contentType before body and has already been released (GA'd).
+
+**Example:**
+
+**contentType before body exists in LastContractView - preserved for backward compatibility**
+
+Previous version had `contentType` before `content`:
+
+```csharp
+public virtual ClientResult UpdateSkillDefaultVersion(string skillId, string contentType, BinaryContent content, RequestOptions options = null)
+{
+    // ...
+}
+```
+
+Current TypeSpec defines a content type:
+
+```typespec
+op UpdateSkillDefaultVersion(
+  @path skill_id: string,
+  @header contentType: string,
+  @body body: SetDefaultSkillVersionBody,
+): SkillResource;
+```
+
+**Generated Compatibility Result:**
+
+The generator detects that the previous contract had `contentType` before `content` and preserves that ordering:
+
+```csharp
+public virtual ClientResult UpdateSkillDefaultVersion(string skillId, string contentType, BinaryContent content, RequestOptions options = null)
+{
+    // contentType stays before content for backward compatibility
+}
+```