Add Json Payload Functionality for User Agent Feature Extension #3489

samsharma2700 · 2025-07-17T20:41:41Z

Description

Part 2 of UserAgent work. Previous PR: #3451

Adding necessary classes for UserAgentInfo json payload.
Implements the current spec guidelines for this FE(https://microsoft.sharepoint-df.com/:w:/t/sqldevx/ERIWTt0zlCxLroNHyaPlKYwBI_LNSff6iy_wXZ8xX6nctQ?e=iP8q75)
The payload is defined by a DTO(Data Transfer Object) class and a UserAgentInfo that implements spec constraints(character limits, bytes limits and field dropping logic etc.)
Part 3 will make the changes to write the payload as a part of login flow

Testing

Builds are running and added unit tests to verify changes.

…eat_jsonuagent

Copilot

Pull Request Overview

This PR implements the JSON payload functionality for the User Agent feature extension in Microsoft.Data.SqlClient, adding the core infrastructure for generating and managing user agent information that will be sent to SQL Server during connection establishment.

Implements UserAgentInfo class with OS detection, architecture detection, and runtime information gathering
Adds UserAgentInfoDto as a serializable data transfer object with size constraints and field-dropping logic
Includes comprehensive unit tests covering field truncation, payload sizing, and JSON serialization

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
UserAgentInfo.cs (netfx/netcore)	Core implementation with OS/runtime detection and JSON payload generation with size constraints
UserAgentInfoDto.cs (netfx/netcore)	Data transfer object for JSON serialization with property name constants
UserAgentInfoTests.cs	Unit tests covering truncation logic, payload sizing, and JSON contract validation
Microsoft.Data.SqlClient.csproj (netfx/netcore)	Project file updates to include the new UserAgent classes
Microsoft.Data.SqlClient.UnitTests.csproj	Test project configuration with empty folder reference

Comments suppressed due to low confidence (2)

src/Microsoft.Data.SqlClient/tests/UnitTests/Microsoft.Data.SqlClient.UnitTests.csproj

src/Microsoft.Data.SqlClient/netfx/src/Microsoft/Data/SqlClient/UserAgentInfo.cs

roji · 2025-07-17T20:45:28Z

@samsharma2700 @cheenamalhotra great to see this work happening. I've taken a look at the spec doc linked above, and could you clarify how we'd go about injecting EF information into the user agent? We'd need to identify EF Core (as opposed to direct users of SqlClient), it's version, etc.

paulmedynski · 2025-07-18T10:40:46Z

Hi @roji - There is a V2 of the design that adds a public API for middleware like EF to pass version information, but we need to go through a security and privacy review before we can implement it. This V1 phase only includes values we can pull from the runtime that don't have any such concerns.

paulmedynski

Need to move the UserAgent files into the src/ project and avoid duplicating them. I'll complete my review after the move.

src/Microsoft.Data.SqlClient/tests/UnitTests/Microsoft.Data.SqlClient.UnitTests.csproj

src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/UserAgentInfo.cs

roji · 2025-07-18T13:47:29Z

@paulmedynski ok - can you clarify what's planned for the 6.1.0 (v1, v2?)

paulmedynski · 2025-07-18T15:43:53Z

The V1 work will arrive in 7.0.0. The V2 work to support EF and other middleware may also make it into that timeframe, but depends on which reviews we need and how long they take. There is also ongoing SQL Server support that we need to align with to make any of this driver side work useful.

@samsharma2700 will be completing the V1 work over several PRs. We have (and will) put them into the 7.0.0-preview1 milestone.

codecov · 2025-07-18T22:29:23Z

Codecov Report

Attention: Patch coverage is 51.90840% with 63 lines in your changes missing coverage. Please review.

Project coverage is 66.89%. Comparing base (42146a3) to head (7b2ad0e).
Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
...icrosoft/Data/SqlClient/UserAgent/UserAgentInfo.cs	49.19%	63 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3489      +/-   ##
==========================================
- Coverage   68.85%   66.89%   -1.97%     
==========================================
  Files         277      279       +2     
  Lines       62237    62316      +79     
==========================================
- Hits        42854    41684    -1170     
- Misses      19383    20632    +1249

Flag	Coverage Δ
addons	`91.04% <ø> (+0.22%)`	⬆️
netcore	`68.96% <50.38%> (-3.72%)`	⬇️
netfx	`69.34% <51.58%> (+1.15%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

roji · 2025-07-19T09:24:59Z

@paulmedynski thanks for the clarifications!

paulmedynski

You're on the right track here. We can discuss my comments and suggestions.

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfo.cs

src/Microsoft.Data.SqlClient/tests/UnitTests/UserAgentInfoTests.cs

paulmedynski

Very close now; just a few more comments.

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfo.cs

paulmedynski · 2025-07-25T17:50:09Z

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfo.cs

+        // - If the payload exceeds 2,047 bytes but remains within sensible limits, we still send it, but note that
+        //   some servers may silently drop or reject such packets — behavior we may use for future probing or diagnostics.
+        // - If payload exceeds 10KB even after dropping fields , we send an empty payload.
+        var driverName = TruncateOrDefault(DriverName, DriverNameMaxChars);


We can just assign directly to the DTO properties/fields instead of making temporaries here:

return new() { Driver = TruncateOrDefault(DriverName, DriverNameMaxChars). ... }

You don't even need to repeat UserAgentInfoDto since the compiler knows what the return type is.

paulmedynski · 2025-07-25T17:54:21Z

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfoDto.cs

+
+    // TODO: Does this need to be nullable?
+    [JsonPropertyName(DriverJsonKey)]
+    public string? Driver { get; set; }


These two should be non-nullable.

paulmedynski · 2025-07-25T17:55:41Z

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfoDto.cs

+        public const string DetailsJsonKey = "details";
+
+        [JsonPropertyName(TypeJsonKey)]
+        public string? Type { get; set; }


This doesn't need to be nullable.

We do drop this field though.

I thought we drop the entire Os field, but never just the Type field.

paulmedynski · 2025-07-25T17:57:51Z

src/Microsoft.Data.SqlClient/tests/UnitTests/UserAgentInfoTests.cs

-            // Convert to string for field presence checks
-            string json = Encoding.UTF8.GetString(payload);
+            // High‑priority fields must survive.
+            Assert.True(root.TryGetProperty(UserAgentInfoDto.DriverJsonKey, out _));


You can at least verify the driver name is "MS-MDS". You could also probably verify the version if you can access the ADP helper that returns it.

In this particular test all values are replaced as xxxx... so driver name and version will not be the default values.

Is there a way to test that you produce the expected real values?

Added a new test that verifies we populate the correct default values for driver name and version.

You can still verify that the present fields contain the expected 'xxx...' values, truncated to their respective max lengths.

paulmedynski · 2025-07-25T17:58:57Z

src/Microsoft.Data.SqlClient/tests/UnitTests/UserAgentInfoTests.cs

            {
-                Assert.Equal("{}", json.Trim());
-                return;
+                Assert.True(os.TryGetProperty(UserAgentInfoDto.OsInfo.TypeJsonKey, out _));


You should verify the value here, since we have a constrained set of allowable values and you can predict what they will be.

Same as above, all values are still xxxx... since we pass the DTO values directly and are only testing AdjustJsonPayloadSize functionality.

Added a new test to verify the field value handling.

This is a special case because UserAgentInfo normally populates default values automatically. Here, we intentionally bypass UserAgentInfo to create our own DTO directly, without calling BuildDto() or TruncateOrDefault().
As a result, no truncation of field values occurs. The main purpose of this test is to validate the field-dropping logic under these conditions.

paulmedynski · 2025-07-25T17:59:48Z

src/Microsoft.Data.SqlClient/tests/UnitTests/UserAgentInfoTests.cs

        }

-        // 4. DTO serializes with expected JSON property names
+        // 4. DTO JSON contract - verify names and values


Test serialization when the nullable fields are null.

benrr101

😬 I'm gonna force braces for if statements if it's the last thing I do

benrr101 · 2025-07-25T18:41:06Z

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfo.cs

+
+#nullable enable
+
+#if WINDOWS


Is this actually supported in netfx?

Should not by default, but need to remove this as we changed the implementation. Good catch!

We're definitely going to have something like this once the common project is finished up. Didn't want you jumping the gun :)

benrr101 · 2025-07-25T18:41:28Z

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfo.cs

+    /// <summary>
+    /// Maximum number of characters allowed for the driver version.
+    /// </summary>
+    private const int VersionMaxChars = 16;


Please order alphabetically

Is it a new guideline we are following? Haven't seen alphabetical ordering in other classes.

These currently reflect the order of the JSON fields defined in the spec. I would prefer we retain that order throughout the implementation. Perhaps a comment explaining that here would help.

benrr101 · 2025-07-25T18:42:48Z

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfo.cs

+            },
+            Arch = architecture,
+            Runtime = runtime
+


nit: extra line

benrr101 · 2025-07-25T18:44:17Z

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfo.cs

+        {
+            // first we try with built-in checks (Android and FreeBSD also report Linux so they are checked first)
+#if NET6_0_OR_GREATER
+            if (OperatingSystem.IsAndroid())  return OsType.Android;


Ok, sorry to do this but, please always always always use braces around if/else blocks

benrr101 · 2025-07-25T18:44:53Z

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfo.cs

+            if (OperatingSystem.IsMacOS())   return OsType.macOS;
+#endif
+            // second we fallback to OSPlatform checks
+#if NETCOREAPP3_0_OR_GREATER || NET5_0_OR_GREATER


We don't support < net6, so these conditions seem unnecessary

We do target net462 which does not support OSPlatform.FreeBSD : https://apisof.net/catalog/138b234eefee5c6692118fe8c4d64920
Will change the check to reflect that.

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfoDto.cs

src/Microsoft.Data.SqlClient/tests/UnitTests/UserAgentInfoTests.cs

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfo.cs

src/Microsoft.Data.SqlClient/tests/UnitTests/UserAgentInfoTests.cs

benrr101 · 2025-07-30T19:13:27Z

src/Microsoft.Data.SqlClient/tests/UnitTests/UserAgentInfoTests.cs


-            // Assert – nested os object
+            // optional Arch
+            if (dto.Arch is null)


In my opinion, this test is doing too many scenarios...

I understand the test may feel tedious. I’ve added additional comments to improve readability.
This section needs to be tested in one run to properly verify the field-dropping logic.

paulmedynski · 2025-08-07T11:29:54Z

/azp run

azure-pipelines · 2025-08-07T11:30:14Z

Azure Pipelines successfully started running 2 pipeline(s).

paulmedynski

Getting closer!

paulmedynski · 2025-08-07T11:38:25Z

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfo.cs

    /// </summary>
-    private const int OsTypeMaxChars = 16;
+    internal const int JsonPayloadMaxBytes = 2047;


Yuck - now the JSON field constants are mixed in with other constants, and they're no longer in logical order.

Yeah we have to decide between logical groupings or lexicographical ordering. The groupings are maintained in case of UserAgentInfoDto

paulmedynski · 2025-08-07T11:41:17Z

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfo.cs

+    private static readonly UserAgentInfoDto s_dto;
+    private static readonly byte[] s_cachedPayload;
+
+    public static byte[] CachedPayload => s_cachedPayload;


This public property deserves some documentation, most importantly that it doesn't calculate anything.

Can this be readonly?

Is CachedPayload the best name? Maybe it's fine when you add documentation.

Will add some documentation here. We cannot mark properties as readonly. In case of s_cachedPayload despite it being readonly someone can still modify it after initialization. I think CachedPayload can be ReadOnlyMemory<byte>, which would communicate the read-only intent at the API boundary.

paulmedynski · 2025-08-07T11:45:10Z

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfo.cs

+        }
+
+        dto.OS = null; // drop OS entirely
+        // Last attempt to send minimal payload driver + version only


Note that we know driver + version cannot be larger than the max, pointing to the explanation in the BuildDto() commentary.

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfo.cs

paulmedynski · 2025-08-07T11:50:48Z

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfoDto.cs

    [JsonPropertyName(DriverJsonKey)]
-    public string? Driver { get; set; }
+    public string Driver { get; set; } = UserAgentInfo.DriverName;


These initialization values don't belong here. The DTO doesn't know anything about where its values come from. That's UserAgentInfo's responsibility.

I think string.Empty is the correct choice here.

paulmedynski · 2025-08-07T11:54:27Z

src/Microsoft.Data.SqlClient/tests/UnitTests/UserAgentInfoTests.cs

-            // Convert to string for field presence checks
-            string json = Encoding.UTF8.GetString(payload);
+            // High‑priority fields must survive.
+            Assert.True(root.TryGetProperty(UserAgentInfoDto.DriverJsonKey, out _));


You can still verify that the present fields contain the expected 'xxx...' values, truncated to their respective max lengths.

paulmedynski · 2025-08-07T12:01:17Z

src/Microsoft.Data.SqlClient/tests/UnitTests/UserAgentInfoTests.cs

            Assert.False(root.TryGetProperty(UserAgentInfoDto.ArchJsonKey, out _));
            Assert.False(root.TryGetProperty(UserAgentInfoDto.RuntimeJsonKey, out _));

-            // If the "os" object survived, only its "type" sub‑field may remain.
+            // if OS block remains, only its Type sub-field may survive
            if (root.TryGetProperty(UserAgentInfoDto.OsJsonKey, out JsonElement os))


This if-statement allows the test to pass whether or not the OS block is present. So we're not really testing one of the adjust scenarios. Here's what we need:

Keep this test, rename it to indicate that all low priority fields are stripped, and then replace this if-statement with Assert.False(root.TryGetProperty(OsJsonKey)).

Add a new test that checks the middle-ground adjusting, where only arch, runtime, and os.description are stripped (i.e. the return on UserAgentInfo line 115).

Great catch! will do that.

paulmedynski · 2025-08-07T12:05:02Z

src/Microsoft.Data.SqlClient/tests/UnitTests/UserAgentInfoTests.cs

+                {
+                    Assert.Equal(dto.OS.Details, os.GetProperty(UserAgentInfoDto.OsInfo.DetailsJsonKey).GetString());
+                }
+            }
        }

        // 5. End-to-end test that combines truncation, adjustment, and serialization


Maybe this is the missing test I was referring to above, just not named/documented accurately.

cheenamalhotra · 2025-08-15T20:36:15Z

src/Microsoft.Data.SqlClient/tests/UnitTests/UserAgentInfoTests.cs

@@ -0,0 +1,263 @@
+using System.Text;


Include .NET headers

cheenamalhotra · 2025-08-15T20:36:26Z

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfoDto.cs

@@ -0,0 +1,49 @@
+using System.Text.Json;


Include headers

cheenamalhotra · 2025-08-15T20:36:47Z

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfo.cs

@@ -0,0 +1,348 @@
+using System;


Include headers

cheenamalhotra · 2025-08-15T20:39:51Z

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/UserAgent/UserAgentInfoDto.cs

+
+#nullable enable
+
+namespace Microsoft.Data.SqlClient.UserAgent;


For consistency in reading, keep curly brackets for namespace definition, as in other classes.

There was feedback to move to file-scoped namespace declarations : #3489 (comment)

samsharma2700 added 3 commits July 16, 2025 16:47

Add UserAgent Json payload

5fc8f70

Merge branch 'main' of https://github.com/dotnet/SqlClient into sam_f…

6b2b6d8

…eat_jsonuagent

Add unit tests and update UserAgentInfo payload checks

5147858

Copilot AI review requested due to automatic review settings July 17, 2025 20:41

samsharma2700 requested a review from a team as a code owner July 17, 2025 20:41

Copilot AI reviewed Jul 17, 2025

View reviewed changes

roji mentioned this pull request Jul 17, 2025

SQL Server: Introduce EF and its version into the connection string's Application Name dotnet/efcore#35730

Closed

paulmedynski requested changes Jul 18, 2025

View reviewed changes

paulmedynski added this to the 7.0-preview1 milestone Jul 18, 2025

PR review changes 1

7b2ad0e

samsharma2700 requested a review from paulmedynski July 18, 2025 21:08

paulmedynski requested changes Jul 22, 2025

View reviewed changes

Review updates for Detect functions and tests

56a4c6c

paulmedynski requested changes Jul 25, 2025

View reviewed changes

benrr101 requested changes Jul 25, 2025

View reviewed changes

Adding more tests

ede42a1

benrr101 requested changes Jul 30, 2025

View reviewed changes

samsharma2700 mentioned this pull request Jul 30, 2025

Enable User Agent Extension #3530

Draft

Naming changes and additional tests

fe4d20f

samsharma2700 requested review from benrr101 and paulmedynski July 31, 2025 22:59

paulmedynski requested changes Aug 7, 2025

View reviewed changes

roji mentioned this pull request Aug 14, 2025

Switch to using the new SqlClient user-agent feature dotnet/efcore#36571

Open

cheenamalhotra reviewed Aug 15, 2025

View reviewed changes

Cached payload changes and test update

c4b0278

samsharma2700 requested a review from paulmedynski August 19, 2025 16:04

cheenamalhotra requested a review from apoorvdeshmukh August 19, 2025 17:30


		#nullable enable

		namespace Microsoft.Data.SqlClient.UserAgent;

Add Json Payload Functionality for User Agent Feature Extension #3489

Are you sure you want to change the base?

Add Json Payload Functionality for User Agent Feature Extension #3489

Uh oh!

Conversation

samsharma2700 commented Jul 17, 2025

Description

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

roji commented Jul 17, 2025

Uh oh!

paulmedynski commented Jul 18, 2025

Uh oh!

paulmedynski left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

roji commented Jul 18, 2025

Uh oh!

paulmedynski commented Jul 18, 2025

Uh oh!

codecov bot commented Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

roji commented Jul 19, 2025

Uh oh!

paulmedynski left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

paulmedynski left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Jul 18, 2025 •

edited

Loading