Feature | Surface batch information on the SqlClient diagnostic events

[PetarJerinic]

Is your feature request related to a problem? Please describe.

A SqlBatch is invisible to DiagnosticSource subscribers, so nothing outside SqlClient can distinguish a batch from a single command or determine how many operations it contained.
SqlBatch.ExecuteNonQuery() delegates the batch to a single private SqlCommand field, _batchCommand, which SetupBatchCommandExecute() puts into batch-RPC mode (SqlBatch.cs#L89-L94, #L220-L240).

For the subscriber, it has the following consequences:

• SqlCommand exposes no public member revealing batch state. The operation count exists only in the private _RPCList field.

• AddBatchCommand overwrites CommandText (SqlCommand.Batch.cs#L25), making only the last statement available.

For OpenTelemetry.Instrumentation.SqlClient this means db.operation.batch.size can't be emitted.

Describe the solution you'd like

Expose the batch on the command diagnostic payloads in Microsoft.Data.SqlClient.Diagnostics.
Example:

public IReadOnlyList<SqlBatchCommand>? BatchCommands { get; }

Suggested classes where this would be present: SqlClientCommandBefore, SqlClientCommandAfter and SqlClientCommandError.
Alternatively, only operation count could be exposed, but in that case only the last statement of the batch would be present in query text

Describe alternatives you've considered

Use reflection to read _RPCList field, but the idea was rejected since any future change could break the functionality in OpenTelemetry.Instrumentation.SqlClient.

Additional context

• Observed on Microsoft.Data.SqlClient 7.0.2
• The impact on OpenTelemetry.Instrumentation.SqlClient can be seen here (open-telemetry/opentelemetry-dotnet-contrib#2240)
• This looks like the extension case from Emit OpenTelemetry tracing #2210 comment: Emit OpenTelemetry tracing #2210 (comment)
• Happy to create a PR myself if the team is open to it.

[github-actions]

🔍 Triage Summary

Check	Result
Issue type	Feature
Environment	All required environment details provided for investigation
Area	Diagnostics / Area\Engineering
Duplicates	Potentially related: #2210 (referenced by author)
Regression	Not indicated

Analysis

This feature request asks for SqlBatch execution context (batch commands or batch size) to be surfaced in the DiagnosticSource payloads (SqlClientCommandBefore, SqlClientCommandAfter, SqlClientCommandError) within Microsoft.Data.SqlClient.Diagnostics. Currently, SqlBatch delegates to a private internal SqlCommand in batch-RPC mode, and the diagnostic payload only reflects the last overwritten CommandText, making it impossible for OpenTelemetry instrumentation (or other DiagnosticSource subscribers) to emit db.operation.batch.size. The proposed fix is a public IReadOnlyList<SqlBatchCommand>? BatchCommands property on the diagnostic payload classes. This is a P2 feature with a clear, well-scoped design and direct ecosystem impact (OpenTelemetry).

Next Steps

• Add a BatchCommands property (or at minimum a BatchCommandCount property) to SqlClientCommandBefore, SqlClientCommandAfter, and SqlClientCommandError in Microsoft.Data.SqlClient.Diagnostics.
• Populate the property during SqlBatch execution in SqlBatch.SetupBatchCommandExecute / the diagnostic write paths.
• Update the reference assemblies (netcore/ref/ and netfx/ref/) to reflect the new public API surface.
• The author has offered to submit a PR — the team should confirm the desired API shape and signal acceptance before the author invests in implementation.
• Review linked upstream issue open-telemetry/opentelemetry-dotnet-contrib#2240 and Emit OpenTelemetry tracing #2210 for any prior design decisions.

Note: This triage summary is auto-generated by an AI agent. The analysis and suggestions above have not been verified by a human maintainer. Please treat as preliminary guidance only.

Generated by SqlClient Issue Auto-Triage for issue #4545 · 32.7 AIC · ⌖ 9 AIC · ⊞ 8.6K · ◷

[cheenamalhotra]

Thanks for the detailed writeup @PetarJerinic — the analysis matches what I see in the code. SqlBatch executes through a private SqlCommand in batch-RPC mode, AddBatchCommand overwrites CommandText, and the batch commands only exist in the private _RPCList, so there is currently no supported way for a DiagnosticSource subscriber to see the batch.

Here is the API shape I'd like to go with — essentially your proposal:

Proposed API

Add one property to SqlClientCommandBefore, SqlClientCommandAfter and SqlClientCommandError:

// null when the command is not executing as part of a SqlBatch
public IReadOnlyList<SqlBatchCommand> BatchCommands { get; }

Why this shape

• 3 new properties, no new types. SqlBatchCommand is already public on net462, net8.0 and net9.0, so the surface addition is minimal.
• Gives both signals. Subscribers get db.operation.batch.size from .Count and usable per-command db.query.text, which the count-only alternative would not.
• We considered exposing SqlBatch itself on the payload instead, but that leaks a disposable, user-owned object into the diagnostic payload (SqlBatch.BatchCommands throws once disposed), so we prefer the list.

Implementation notes

• Add an internal SqlCommand.BatchCommands, populated in SqlBatch.SetupBatchCommandExecute() from a cached ReadOnlyCollection<SqlBatchCommand> wrapper over SqlBatch.Commands — allocated once per SqlBatch, and it prevents subscribers from downcasting and mutating the live list.
• SqlDiagnosticListener.WriteCommandBefore / WriteCommandAfter / WriteCommandError pass it through to the payloads.
• Non-batch commands stay null, so there is no added cost on the common path.
• Include the new member in the IReadOnlyList<KeyValuePair<string, object>> view, appended at the last index. Count goes 6 → 7 (Before) and 7 → 8 (After/Error); existing indices 0–6 keep their current meaning.
• Update src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Diagnostics.cs and the doc/snippets/.../SqlClientDiagnostic.xml docs.
• Tests should cover sync and async paths (ExecuteNonQuery/ExecuteNonQueryAsync, ExecuteReader/ExecuteReaderAsync, ExecuteScalar/ExecuteScalarAsync) and assert BatchCommands is null for plain SqlCommand execution.

We're happy for you to send the PR — please target this API shape and we'll review. Thanks for offering!

[PetarJerinic]

@cheenamalhotra thanks for the quick feedback and additional implementation notes. I am starting work on it and will create a PR in the next few days.