Add API documentation generation for the Logging package by apoorvdeshmukh · Pull Request #4021 · dotnet/SqlClient

apoorvdeshmukh · 2026-03-09T12:24:49Z

Description

Adds XML documentation comments to all public APIs in Microsoft.Data.SqlClient.Extensions.Logging and configures the project to generate, preserve, and trim XML documentation — following the same patterns used by the main Microsoft.Data.SqlClient package.

Issues

AB#42969

Changes

Added <GenerateDocumentationFile>true</GenerateDocumentationFile> so the compiler generates an XML doc file alongside the assembly. SDK Pack automatically includes it in the NuGet package under lib/<tfm>/.
Added SaveUntrimmedDocs target — copies the full (untrimmed) XML documentation to artifacts/doc/<tfm>/ after build, preserving <remarks> and <example> content for public documentation workflows (e.g., API Drop → Content CI → dotnet/sqlclient-api-docs).
Added TrimDocsForIntelliSense target — runs TrimDocs.ps1 to strip and nodes from the in-place XML file so the NuGet package ships a cleaner IntelliSense experience, matching how the main MDS package handles this.
Added <summary>, <param>, <typeparam>, <returns>, and <remarks> tags to all ~80+ public members across:
SqlClientEventSource.cs — class-level docs with and , all Enable/Disable methods, Trace overloads (with and without if guards), Scope enter/leave methods, Execution Trace, Notification Trace/Scope, Pooler Trace/Scope, Advanced Trace/Scope/Bin/Error, Correlation Trace, State Dump, SNI Trace/Scope, and all WriteEvent methods

Notes

No pipeline changes needed: SDK Pack automatically includes the XML doc file in the NuGet package when GenerateDocumentationFile is set. Both the CI pipeline (pack-logging-package-ci-job.yml) and the OneBranch official pipeline use dotnet pack, which handles this natively.

Copilot

Pull request overview

Adds XML documentation support to the Microsoft.Data.SqlClient.Extensions.Logging package by enabling compiler-generated XML docs, preserving a full “untrimmed” copy for doc workflows, and trimming the packaged IntelliSense XML to remove <remarks>/<example> content.

Changes:

Added XML doc comments to public APIs in SqlClientEventSource.
Updated Logging.csproj to generate XML documentation and added build targets to copy untrimmed docs to artifacts/doc/<tfm>/ and then trim the in-place XML file.
Minor project metadata formatting tweaks (e.g., package description wrapping).

Reviewed changes

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

File	Description
src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs	Adds/updates XML documentation comments across public APIs for the Logging EventSource.
src/Microsoft.Data.SqlClient.Extensions/Logging/src/Logging.csproj	Enables XML doc generation and introduces post-build targets to preserve and trim XML docs for packaging/IntelliSense.

src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs

Copilot · 2026-03-09T12:29:34Z

src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs

+        // Do not change the first 4 arguments in this Event writer as OpenTelemetry and ApplicationInsight are relating to the same format,
        // unless you have checked with them and they are able to change their design. Additional items could be added at the end.


Typo in the comment: the product name is "Application Insights" (plural). Consider also rephrasing "are relating" to something grammatically correct (e.g., "are related") while you're touching this comment.

paulmedynski

Lookg good overall! Just a few comments/questions.

src/Microsoft.Data.SqlClient.Extensions/Logging/src/Logging.csproj

src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs

Copilot

Pull request overview

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

Copilot · 2026-03-09T16:52:41Z

src/Microsoft.Data.SqlClient.Extensions/Logging/src/Logging.csproj

+    <Exec
+      Command="$(PowerShellCmd) -NonInteractive -ExecutionPolicy Unrestricted -Command &quot;$(ToolsDir)intellisense\TrimDocs.ps1 -inputFile '$(DocumentationFile)' -outputFile '$(DocumentationFile)'&quot;" />


The Exec command invokes TrimDocs.ps1 using an unquoted script path ($(ToolsDir)intellisense\TrimDocs.ps1) inside -Command. If the repo path (and therefore $(ToolsDir)) contains spaces, PowerShell will split the path and fail to locate/execute the script. Quote the script path (and ideally use the call operator & or -File) so the target is robust for local builds in paths with spaces.

Seems legit.

Copilot · 2026-03-09T16:52:41Z

src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs


        #region Write Events
-        // Do not change the first 4 arguments in this Event writer as OpenTelemetry and ApplicationInsight are relating to the same format, 
+        // Do not change the first 4 arguments in this Event writer as OpenTelemetry and ApplicationInsight are relating to the same format,


Minor grammar issue in the comment: "are relating" is ungrammatical here (should be e.g. "relate" / "are related"). Since this line was touched, consider fixing the wording to avoid carrying the typo forward.

codecov · 2026-03-09T18:32:52Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 65.06%. Comparing base (569ada7) to head (d9b8741).
⚠️ Report is 2 commits behind head on main.

❗ There is a different number of reports uploaded between BASE (569ada7) and HEAD (d9b8741). Click for more details.

HEAD has 1 upload less than BASE

Flag BASE (569ada7) HEAD (d9b8741)

CI-SqlClient 1 0

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4021      +/-   ##
==========================================
- Coverage   72.36%   65.06%   -7.30%     
==========================================
  Files         287      282       -5     
  Lines       43149    66073   +22924     
==========================================
+ Hits        31223    42988   +11765     
- Misses      11926    23085   +11159

Flag	Coverage Δ
CI-SqlClient	`?`
PR-SqlClient-Project	`65.06% <ø> (?)`

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.

mdaigle

I may be missing something, but I grabbed the npkg file from the PR-package pipeline and it still includes remarks comments. I also do not see an untrimmed artifact uploaded to the pipeline artifacts or included in the package.

apoorvdeshmukh · 2026-03-10T04:23:18Z

I may be missing something, but I grabbed the npkg file from the PR-package pipeline and it still includes remarks comments. I also do not see an untrimmed artifact uploaded to the pipeline artifacts or included in the package.

MDS package has untrimmed documentation xml files under lib and contains documentation for IntelliSense under ref directory. The logging package contains only lib directory from which the api docs will be generated so it needs to be untrimmed. The TrimDocsForIntelliSense does not make sense for this package. I'll revert the changes made there.
For MDS package we do not publish untrimmed documentation as a seaparate artifact but is included in the package itself.
For logging package, the untrimmed documentation xml is within the lib/ directory in the package.

paulmedynski · 2026-03-10T12:35:25Z

src/Microsoft.Data.SqlClient.Extensions/Logging/src/Logging.csproj

+    Select the correct PowerShell executable for the current OS so that the
+    TrimDocsForIntelliSense target below does not need to duplicate the command.
+  -->
+  <PropertyGroup>


We will want somewhere that all projects can share it, like src/Directory.Build.props.

paulmedynski · 2026-03-10T12:35:45Z

src/Microsoft.Data.SqlClient.Extensions/Logging/src/Logging.csproj

+    <Exec
+      Command="$(PowerShellCmd) -NonInteractive -ExecutionPolicy Unrestricted -Command &quot;$(ToolsDir)intellisense\TrimDocs.ps1 -inputFile '$(DocumentationFile)' -outputFile '$(DocumentationFile)'&quot;" />


Seems legit.

apoorvdeshmukh added 2 commits March 9, 2026 17:42

Add api documentation for logging

a1c7266

Merge remote-tracking branch 'origin/main' into dev/ad/api-docs-logging

eec8e5f

apoorvdeshmukh requested a review from a team as a code owner March 9, 2026 12:24

Copilot AI review requested due to automatic review settings March 9, 2026 12:24

github-project-automation bot added this to SqlClient Board Mar 9, 2026

github-project-automation bot moved this to To triage in SqlClient Board Mar 9, 2026

Copilot started reviewing on behalf of apoorvdeshmukh March 9, 2026 12:25 View session

Copilot AI reviewed Mar 9, 2026

View reviewed changes

paulmedynski moved this from To triage to In review in SqlClient Board Mar 9, 2026

paulmedynski added this to the 7.0.0 milestone Mar 9, 2026

paulmedynski added the Area\Documentation Use this for issues that requires changes in public documentations/samples. label Mar 9, 2026

paulmedynski self-assigned this Mar 9, 2026

paulmedynski requested changes Mar 9, 2026

View reviewed changes

github-project-automation bot moved this from In review to In progress in SqlClient Board Mar 9, 2026

Address review comments

2fa363d

apoorvdeshmukh requested a review from paulmedynski March 9, 2026 16:37

Make changes as per doc guidelines

d9b8741

Copilot AI review requested due to automatic review settings March 9, 2026 16:46

Copilot started reviewing on behalf of apoorvdeshmukh March 9, 2026 16:47 View session

Copilot AI reviewed Mar 9, 2026

View reviewed changes

mdaigle requested changes Mar 9, 2026

View reviewed changes

apoorvdeshmukh requested a review from mdaigle March 10, 2026 04:23

paulmedynski requested changes Mar 10, 2026

View reviewed changes

		// Do not change the first 4 arguments in this Event writer as OpenTelemetry and ApplicationInsight are relating to the same format,
		// unless you have checked with them and they are able to change their design. Additional items could be added at the end.

		<Exec
		Command="$(PowerShellCmd) -NonInteractive -ExecutionPolicy Unrestricted -Command "$(ToolsDir)intellisense\TrimDocs.ps1 -inputFile '$(DocumentationFile)' -outputFile '$(DocumentationFile)'"" />

Conversation

apoorvdeshmukh commented Mar 9, 2026 • edited by azure-boards bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issues

Changes

Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

paulmedynski Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Mar 9, 2026

Codecov Report

Uh oh!

mdaigle left a comment

Choose a reason for hiding this comment

Uh oh!

apoorvdeshmukh commented Mar 10, 2026

Uh oh!

paulmedynski Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

paulmedynski Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

apoorvdeshmukh commented Mar 9, 2026 •

edited by azure-boards bot

Loading