[Bug]: C# client emits wrong query string for @query(#{explode: true}) on nested object models

[JoshLove-msft]

Describe the bug

Split out from #10973 to track the C# (@typespec/http-client-csharp) portion specifically.

When a @query parameter uses @query(#{explode: true}) on a model type that contains complex/nested objects (e.g. arrays of objects), the generated C# client serializes the whole model via its .ToString() instead of expanding it into bracket-notation key/value pairs.

Reproduction

TypeSpec

import "@typespec/http";
using TypeSpec.Http;

model Condition {
  field: string;
  value: string;
}

model SearchFilter {
  items?: Condition[];
}

model ItemCollection { data: unknown[]; }

@service
@route("/api/v1")
namespace Example {
  @route("/items")
  interface Items {
    @get list(
      @query(#{explode: true}) filter?: SearchFilter,
    ): ItemCollection;
  }
}

Generated C#

The generated RestClient calls:

uri.AppendQuery("filter", TypeFormatters.ConvertToString(filter), true);

TypeFormatters.ConvertToString(filter) falls back to filter.ToString(), which returns the type name.

Actual behavior

GET /api/v1/items?filter=Example.SearchFilter

Expected behavior

Deep-object (OpenAPI style: deepObject, explode: true) serialization, e.g.:

GET /api/v1/items?filter[items][0][field]=status&filter[items][0][value]=active&filter[items][1][field]=type&filter[items][1][value]=admin

Root cause

The C# emitter does not implement "deep object" serialization for complex nested query-parameter types. It emits a single uri.AppendQuery(name, TypeFormatters.ConvertToString(value), ...) call, and TypeFormatters.ConvertToString has no branch for arbitrary models/collections of models, so it uses object.ToString().

Suggested next steps

• Decide on the target serialization format for nested query objects (bracket notation filter[items][0][field]=status).
• Generate proper serialization code for complex/exploded query-parameter types instead of calling TypeFormatters.ConvertToString.
• Add Spector/mock-api coverage for nested object models with explode: true in the C# emitter.

Note: the JS emitter (@typespec/http-client-js) has the same underlying gap and remains tracked in #10973.

[JoshLove-msft]

Root cause (pinpointed)

The broken code path is in RestClientProvider.BuildAppendQueryStatement:

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

private static MethodBodyStatement BuildAppendQueryStatement(...)
{
    if (paramType?.IsCollection != true)
    {
        var toStringExpression = GetQueryParameterStringExpression(paramType, valueExpression, serializationFormat);
        return uri.AppendQuery(Literal(inputQueryParameter.SerializedName), toStringExpression, true).Terminate();
    }
    // ... collection/dictionary handling (incl. explode) below
}

For a non-collection model type (e.g. SearchFilter), GetQueryParameterStringExpression →
GetParameterValueExpression → valueExpression.ConvertToString(...), and TypeFormatters.ConvertToString
has no branch for arbitrary models, so it falls back to object.ToString() and emits the type name:

uri.AppendQuery("filter", TypeFormatters.ConvertToString(filter), true); // => filter=Example.SearchFilter

There is currently no handling for complex/model-typed query parameters — only primitives, enums,
arrays and dictionaries are handled (dictionaries already support explode, see the
InputDictionaryType branch as a template).

No existing Spector coverage (prerequisite)

There is currently no Spector scenario exercising a complex/model-typed query parameter, so this
bug is untested. Existing coverage:

• parameters/collection-format/query/multi — @query(#{ explode: true }) but only on colors: string[]
  (array of scalars).
• parameters/query — only constant and special-char (plain string).
• No deepObject / nested-object query scenario anywhere in @typespec/http-specs or @azure-tools/azure-http-specs.

A new shared scenario (in http-specs, e.g. under parameters/query or a new deep-object group) that
sends a model with an array of objects via @query(#{ explode: true }) is a prerequisite for
validating this fix end-to-end. Because it lives in the shared spec set, it also unblocks the JS
emitter side tracked in #10973.

Open design decision

Before implementing we need to agree on the target wire format for a nested object query param. The
reporter's expected output is qs.stringify-style bracket notation with array indices:

filter[items][0][field]=status&filter[items][0][value]=active&filter[items][1][field]=type&filter[items][1][value]=admin

This goes beyond OpenAPI style: deepObject (which only defines a single level, filter[prop]=value,
and does not define nested arrays-of-objects). We should confirm we want the full recursive/indexed
form and that it matches what the service side / other emitters expect.

Proposed implementation plan

1. Detect the complex case in BuildAppendQueryStatement: paramType is a model (InputModelType),
   not a framework/primitive/enum type, and (for now) inputQueryParameter.Explode is true.
2. Emit a call to a small generated runtime helper (e.g. QueryStringHelpers.AppendDeepObject(uri, name, value)),
   rather than trying to unroll arbitrary nested structures at emit time. The helper serializes the model
   via its existing JSON model writer, parses the resulting JsonDocument, and walks it recursively,
   appending name[key][index][...] = scalar pairs (skipping nulls), using bracket notation.
3. Reuse the existing null-check wrapping already applied in BuildQueryParameterStatement.
4. Tests:
   • Unit test in RestClientProvider tests asserting the generated statement for a model-typed
     explode query param routes to the deep-object helper (not ConvertToString).
   • Spector/mock-api coverage: a scenario with a model containing an array of objects and
     @query(#{explode: true}), asserting the bracketed query string.

Note

This is split out from #10973 for C# only. The JS emitter (@typespec/http-client-js) has the same
underlying gap and remains tracked in #10973.

[github-actions]

🎯 Issue Triage

The C# client emitter falls back to TypeFormatters.ConvertToString() for @query(#{explode: true}) on nested model types, producing ?filter=Example.SearchFilter instead of proper deep-object bracket notation.

Category: Bug
Area: emitter:client:csharp

🔗 [Playground Reproduction]((typespec.io/redacted)

📋 Reproduction code

import "`@typespec/http`";
using TypeSpec.Http;

model Condition {
  field: string;
  value: string;
}

model SearchFilter {
  items?: Condition[];
}

model ItemCollection { data: unknown[]; }

`@service`
`@route`("/api/v1")
namespace Example {
  `@route`("/items")
  interface Items {
    `@get` list(
      `@query`(#{explode: true}) filter?: SearchFilter,
    ): ItemCollection;
  }
}

🔍 Analysis

• Root cause: The C# emitter emits uri.AppendQuery(name, TypeFormatters.ConvertToString(value), ...) for all query parameters regardless of type complexity. TypeFormatters.ConvertToString has no branch for model types or arrays of models, so it falls back to object.ToString().
• Expected behavior: OpenAPI style: deepObject, explode: true semantics — bracket-notation serialization like filter[items][0][field]=status&filter[items][0][value]=active.
• Affected component: http-client-csharp query parameter serialization code generation.
• Related issue: [Bug]: query params with nested objects are encoded wrong #10973 tracks the same root cause for the JS emitter; this issue was intentionally split from it to track the C# fix separately.

📝 Suggested next steps

• Agree on the target serialization format for deep-object query parameters (bracket notation).
• Update the C# emitter to generate proper deep-object serialization code instead of calling TypeFormatters.ConvertToString for complex/nested model types with explode: true.
• Add Spector/mock-api test coverage for nested object models with explode: true in the C# emitter.

Generated by Agentic Triage