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.

paulmedynski · 2025-07-25T17:47:39Z

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

+        _cachedPayload = AdjustJsonPayloadSize(_dto);
+    }
+
+    static UserAgentInfoDto BuildDto()


This should have internal visibility.

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?

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.

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!

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.

benrr101 · 2025-07-25T18:47:57Z

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

+    public const string DriverJsonKey = "driver";
+    public const string VersionJsonKey = "version";
+    public const string OsJsonKey = "os";
+    public const string ArchJsonKey = "arch";


Sort alphabetically please

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

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

+    public const string RuntimeJsonKey = "runtime";
+
+
+    // TODO: Does this need to be nullable?


According to @paulmedynski - no!

benrr101 · 2025-07-25T19:03:51Z

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

+#nullable enable
+
+namespace Microsoft.Data.SqlClient.UserAgent;
+internal class UserAgentInfoDto


It seems unnecessary to make this a class - it could probably be done as a struct

DTO does not satisfy criteria for a struct: https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/choosing-between-class-and-struct
1). Instance size should be under 16 bytes for a struct. DTO holds 5 strings and one 'OSInfo', around 48+bytes, triple the guideline.
2). We are mutating this object in UserAgentInfo by dropping fields, serializing and dropping again if needed(structs need to be immutable).
3). There won't be any perf benefits as a struct would introduce boxing allocations during serializations.

benrr101 · 2025-07-25T19:04:10Z

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

+    [JsonPropertyName(RuntimeJsonKey)]
+    public string? Runtime { get; set; }
+
+    public class OsInfo


Likewise, this could probably be a struct?

benrr101 · 2025-07-25T19:06:02Z

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

+    {
+        // 1. Cached payload is within the 2,047‑byte spec and never null
+        [Fact]
+        public void CachedPayload_IsNotNull_And_WithinSpecLimit()


If we can, it would be good to structure these as

// Arrange .. any kind of setup work // Act .. preferably one line of action to exercise the desired code // Assert .. whatever checks need to be done to validate the behavior

Yes, agreed. I have tried to follow this structure as much as possible but grouped statements logically together. Will double check if there are any changes in accordance with the structure.

Let's not introduce a bunch of temp variables just to capture state from Act and then Assert it a few lines below. That becomes error prone and can obscure what's happening in the tests. I would prefer to see:

Assert.Equal(foo.SomeAction(), "expected result");

than

var actualResult = foo.SomeAction(); ... Assert.Equal(actualResult, expectedResult);

If there is complicated actions and it makes sense to capture output along the way, then sure. But I would advise against introducing ways to break a test just to follow a pattern.

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: Consider introducing EF and its version into the connection string's Application Name dotnet/efcore#35730

Open

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

		public const string RuntimeJsonKey = "runtime";


		// TODO: Does this need to be nullable?


		#nullable enable

		#if WINDOWS

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!

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!

benrr101 left a comment

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Jul 18, 2025 •

edited

Loading