Skip to content

Fix API docs #4065

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
mdaigle wants to merge 3 commits into from
Closed

Fix API docs #4065

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7ff7a16
Fix API docs
mdaigle Mar 18, 2026
7d83aff
Fix nesting and generate docs.
mdaigle Mar 18, 2026
6f36cbb
Revert generate setting.
mdaigle Mar 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/prompts/ado-work-item-clarification.prompt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ The user has identified a Work Item that currently lacks adequate detail. Your j

1. **Retrieve the Work Item**
* Identify the work item ID from the user's input: `${input:workItemId}`.
* **Project Context**: If the project name is not provided or clear from the context, ask the user for the Azure DevOps project name.
* **Project Context**: Always use the `ADO.Net` project when querying Azure DevOps.
* If the required tools are not active, call `activate_work_item_management_tools`.
* Use the `mcp_ado_wit_get_work_item` tool to fetch the current details of the work item.
* Use the `mcp_ado_wit_get_work_item` tool with `project` set to `ADO.Net` to fetch the current details of the work item.
* Examine the current **Title**, **Description**, and **Acceptance Criteria**.

2. **Analyze and Gap Analysis**
Expand Down
6 changes: 3 additions & 3 deletions doc/snippets/Microsoft.Data.SqlClient/SqlCommand.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3474,9 +3474,9 @@ The blocking connection simulates a situation like a command still running in th

### How to use with legacy asynchronous commands
Besides assigning the provider to the command and executing the command, it's possible to run it directly using the following <xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider> methods:
- <xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.Execute%60%601(System.Object,System.Func{%60%600})>
- <xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.Execute``1(System.Object,System.Func{``0})>
- <xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.ExecuteAsync(System.Object,System.Func{System.Threading.Tasks.Task},System.Threading.CancellationToken)>
- <xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.ExecuteAsync%60%601(System.Object,System.Func{System.Threading.Tasks.Task{%60%600}},System.Threading.CancellationToken)>
- <xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.ExecuteAsync``1(System.Object,System.Func{System.Threading.Tasks.Task{``0}},System.Threading.CancellationToken)>

[!code-csharp[SqlConfigurableRetryLogic_SqlCommand#4](~/../sqlclient/doc/samples/SqlConfigurableRetryLogic_SqlCommand.cs#4)]

Expand Down Expand Up @@ -3606,7 +3606,7 @@ If you call an `Execute` method after calling <xref:Microsoft.Data.SqlClient.Sql

Output parameters (whether prepared or not) must have a user-specified data type. If you specify a variable length data type except vector, you must also specify the maximum <xref:Microsoft.Data.SqlClient.SqlParameter.Size%2A>.

For vector data types, the <xref:Microsoft.Data.SqlClient.SqlParameter.Size%2A> property is ignored. The size of the vector is inferred from the <xref:Microsoft.Data.SqlClient.SqlParameter.Value%2A> of type <xref:Microsoft.Data.SqlTypes.SqlVector%2A>.
For vector data types, the <xref:Microsoft.Data.SqlClient.SqlParameter.Size%2A> property is ignored. The size of the vector is inferred from the <xref:Microsoft.Data.SqlClient.SqlParameter.Value%2A> of type <xref:Microsoft.Data.SqlTypes.SqlVector%601>.
Copy link
Copy Markdown
Contributor

@paulmedynski paulmedynski Mar 19, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why did this change from %2A to %601, but not the one on line 3607 above? I'm guessing it's actually %60 (backtick) followed by 1, but that's pretty nasty if so. Can we not use backtick characters in XML?


Prior to Visual Studio 2010, <xref:Microsoft.Data.SqlClient.SqlCommand.Prepare%2A> threw an exception. Beginning in Visual Studio 2010, this method does not throw an exception.

Expand Down
20 changes: 10 additions & 10 deletions doc/snippets/Microsoft.Data.SqlClient/SqlDataAdapter.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -825,19 +825,19 @@ The following example uses the <xref:Microsoft.Data.SqlClient.SqlCommand>, <xref
</OnRowUpdating>
<RowUpdated>
<summary>
Occurs during <see cref="M:System.Data.Common.DbDataAdapter.Update(System.Data.DataSet)" /> after a command is executed against the data source. The attempt to update is made, so the event fires.
Occurs during <see cref="M:System.Data.Common.DbDataAdapter.Update(System.Data.DataSet)" /> after a command is executed against the data source for each updated row. Use this event to inspect the result, check for errors, or control how <see cref="M:System.Data.DataRow.AcceptChanges" /> is applied.
</summary>
<remarks>
<para>
When using <see cref="M:System.Data.Common.DbDataAdapter.Update(System.Data.DataSet)" />, there are two events that occur per data row updated. The order of execution is as follows:
</para>
<list type="number">
<item><description>The values in the <see cref="T:System.Data.DataRow" /> are moved to the parameter values.</description></item>
<item><description>The <see cref="M:Microsoft.Data.SqlClient.SqlDataAdapter.OnRowUpdating(System.Data.Common.RowUpdatingEventArgs)" /> event is raised.</description></item>
<item><description>The <see cref="E:Microsoft.Data.SqlClient.SqlDataAdapter.RowUpdating" /> event is raised.</description></item>
<item><description>The command executes.</description></item>
<item><description>If the command is set to <c>FirstReturnedRecord</c>, the first returned result is placed in the <see cref="T:System.Data.DataRow" />.</description></item>
<item><description>If the command's <see cref="P:System.Data.IDbCommand.UpdatedRowSource" /> property is set to <see cref="F:System.Data.UpdateRowSource.FirstReturnedRecord" />, the first returned result is placed in the <see cref="T:System.Data.DataRow" />.</description></item>
<item><description>If there are output parameters, they are placed in the <see cref="T:System.Data.DataRow" />.</description></item>
<item><description>The <see cref="M:Microsoft.Data.SqlClient.SqlDataAdapter.OnRowUpdated(System.Data.Common.RowUpdatedEventArgs)" /> event is raised.</description></item>
<item><description>The <see cref="E:Microsoft.Data.SqlClient.SqlDataAdapter.RowUpdated" /> event is raised.</description></item>
<item><description><see cref="M:System.Data.DataRow.AcceptChanges" /> is called.</description></item>
</list>
</remarks>
Expand Down Expand Up @@ -874,7 +874,7 @@ The following example uses the <xref:Microsoft.Data.SqlClient.SqlCommand>, <xref
public static int Main()
{
const string connectionString = "Integrated Security=SSPI;database=Northwind;server=MSSQL1";
const string queryString = "SELECT * FROMProducts";
const string queryString = "SELECT * FROM Products";

// create DataAdapter
SqlDataAdapter adapter = new SqlDataAdapter(queryString, connectionString);
Expand Down Expand Up @@ -938,19 +938,19 @@ The following example uses the <xref:Microsoft.Data.SqlClient.SqlCommand>, <xref
</RowUpdated>
<RowUpdating>
<summary>
Occurs during <see cref="M:System.Data.Common.DbDataAdapter.Update(System.Data.DataSet)" /> before a command is executed against the data source. The attempt to update is made, so the event fires.
Occurs during <see cref="M:System.Data.Common.DbDataAdapter.Update(System.Data.DataSet)" /> before a command is executed against the data source for each updated row. Use this event to inspect or modify the command, skip the row, or cancel the update.
</summary>
<remarks>
<para>
When using <see cref="M:System.Data.Common.DbDataAdapter.Update(System.Data.DataSet)" />, there are two events that occur per data row updated. The order of execution is as follows:
</para>
<list type="number">
<item><description>The values in the <see cref="T:System.Data.DataRow" /> are moved to the parameter values.</description></item>
<item><description>The <see cref="M:Microsoft.Data.SqlClient.SqlDataAdapter.OnRowUpdating(System.Data.Common.RowUpdatingEventArgs)" /> event is raised.</description></item>
<item><description>The <see cref="E:Microsoft.Data.SqlClient.SqlDataAdapter.RowUpdating" /> event is raised.</description></item>
<item><description>The command executes.</description></item>
<item><description>If the command is set to <c>FirstReturnedRecord</c>, the first returned result is placed in the <see cref="T:System.Data.DataRow" />.</description></item>
<item><description>If the command's <see cref="P:System.Data.IDbCommand.UpdatedRowSource" /> property is set to <see cref="F:System.Data.UpdateRowSource.FirstReturnedRecord" />, the first returned result is placed in the <see cref="T:System.Data.DataRow" />.</description></item>
<item><description>If there are output parameters, they are placed in the <see cref="T:System.Data.DataRow" />.</description></item>
<item><description>The <see cref="M:Microsoft.Data.SqlClient.SqlDataAdapter.OnRowUpdated(System.Data.Common.RowUpdatedEventArgs)" /> event is raised.</description></item>
<item><description>The <see cref="E:Microsoft.Data.SqlClient.SqlDataAdapter.RowUpdated" /> event is raised.</description></item>
<item><description><see cref="M:System.Data.DataRow.AcceptChanges" /> is called.</description></item>
</list>
</remarks>
Expand Down Expand Up @@ -987,7 +987,7 @@ The following example uses the <xref:Microsoft.Data.SqlClient.SqlCommand>, <xref
public static int Main()
{
const string connectionString = "Integrated Security=SSPI;database=Northwind;server=MSSQL1";
const string queryString = "SELECT * FROMProducts";
const string queryString = "SELECT * FROM Products";

// create DataAdapter
SqlDataAdapter adapter = new SqlDataAdapter(queryString, connectionString);
Expand Down
6 changes: 3 additions & 3 deletions doc/snippets/Microsoft.Data.SqlClient/SqlDataReader.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -967,10 +967,10 @@ The <xref:Microsoft.Data.SqlClient.SqlDataReader.GetSchemaTable%2A> method retur
<GetSqlVector>
<param name="i"></param>
<summary>
Gets the value of the specified column as a <see cref="T:Microsoft.Data.SqlTypes.SqlVector"/>.
Gets the value of the specified column as a <see cref="T:Microsoft.Data.SqlTypes.SqlVector`1"/>.
</summary>
<returns>
A <see cref="T:Microsoft.Data.SqlTypes.SqlVector"/> object representing the column at the given ordinal.
A <see cref="T:Microsoft.Data.SqlTypes.SqlVector`1"/> object representing the column at the given ordinal.
</returns>
<exception cref="T:System.ArgumentOutOfRangeException">
The index passed was outside the range of 0 to <see cref="P:System.Data.DataTableReader.FieldCount" /> - 1
Expand All @@ -979,7 +979,7 @@ The <xref:Microsoft.Data.SqlClient.SqlDataReader.GetSchemaTable%2A> method retur
An attempt was made to read or access columns in a closed <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />.
</exception>
<exception cref="T:System.InvalidCastException">
The retrieved data is not compatible with the <see cref="T:Microsoft.Data.SqlTypes.SqlVector" /> type.
The retrieved data is not compatible with the <see cref="T:Microsoft.Data.SqlTypes.SqlVector`1" /> type.
</exception>
<remarks>
No conversions are performed; therefore, the data retrieved must already be a vector value, or an exception is generated.
Expand Down
4 changes: 2 additions & 2 deletions src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlDataReader.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2598,15 +2598,15 @@ virtual public SqlXml GetSqlXml(int i)
return sx;
}

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlDataReader.xml' path='docs/members[@name="SqlDataReader"]/GetSqlJson/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlClient/SqlDataReader.xml' path='docs/members[@name="SqlDataReader"]/GetSqlJson/*' />
virtual public SqlJson GetSqlJson(int i)
{
ReadColumn(i);
SqlJson json = _data[i].IsNull ? SqlJson.Null : _data[i].SqlJson;
return json;
}

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlDataReader.xml' path='docs/members[@name="SqlDataReader"]/GetSqlVector/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlClient/SqlDataReader.xml' path='docs/members[@name="SqlDataReader"]/GetSqlVector/*' />
virtual public SqlVector<T> GetSqlVector<T>(int i) where T : unmanaged
{
if (typeof(T) != typeof(float))
Expand Down
6 changes: 3 additions & 3 deletions src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlDbTypeExtensions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,16 @@

namespace Microsoft.Data
{
/// <include file='../../../../doc/snippets/Microsoft.Data/SqlDbTypeExtensions.xml' path='docs/members[@name="SqlDbTypeExtensions"]/SqlDbTypeExtensions/*' />
/// <include file='../../../../../doc/snippets/Microsoft.Data/SqlDbTypeExtensions.xml' path='docs/members[@name="SqlDbTypeExtensions"]/SqlDbTypeExtensions/*' />
public static class SqlDbTypeExtensions
{
/// <include file='../../../../doc/snippets/Microsoft.Data/SqlDbTypeExtensions.xml' path='docs/members[@name="SqlDbTypeExtensions"]/SqlJson[@name="default"]' />
/// <include file='../../../../../doc/snippets/Microsoft.Data/SqlDbTypeExtensions.xml' path='docs/members[@name="SqlDbTypeExtensions"]/SqlJson[@name="default"]' />
#if NET9_0_OR_GREATER
public const SqlDbType Json = SqlDbType.Json;
#else
public const SqlDbType Json = (SqlDbType)35;
#endif
/// <include file='../../../../doc/snippets/Microsoft.Data/SqlDbTypeExtensions.xml' path='docs/members[@name="SqlDbTypeExtensions"]/SqlVector[@name="default"]' />
/// <include file='../../../../../doc/snippets/Microsoft.Data/SqlDbTypeExtensions.xml' path='docs/members[@name="SqlDbTypeExtensions"]/SqlVector[@name="default"]' />
#if NET10_0_OR_GREATER
public const SqlDbType Vector = SqlDbType.Vector;
#else
Expand Down
16 changes: 8 additions & 8 deletions src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlTypes/SqlJson.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,18 +12,18 @@

namespace Microsoft.Data.SqlTypes
{
/// <include file='../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/SqlJson/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/SqlJson/*' />
public class SqlJson : INullable
{
// Our serialized JSON string, or null.
private readonly string? _jsonString = null;

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/ctor1/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/ctor1/*' />
public SqlJson()
{
}

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/ctor2/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/ctor2/*' />
#if NET
public SqlJson([StringSyntax(StringSyntaxAttribute.Json)] string? jsonString)
#else
Expand All @@ -45,7 +45,7 @@ public SqlJson(string? jsonString)
_jsonString = jsonString;
}

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/ctor3/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/ctor3/*' />
public SqlJson(JsonDocument? jsonDoc)
{
if (jsonDoc == null)
Expand All @@ -57,13 +57,13 @@ public SqlJson(JsonDocument? jsonDoc)
_jsonString = jsonDoc.RootElement.GetRawText();
}

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/IsNull/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/IsNull/*' />
public bool IsNull => _jsonString is null;

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/Null/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/Null/*' />
public static SqlJson Null => new();

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/Value/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/Value/*' />
public string Value
{
get
Expand All @@ -77,7 +77,7 @@ public string Value
}
}

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/ToString/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlJson.xml' path='docs/members[@name="SqlJson"]/ToString/*' />
public override string? ToString()
{
return _jsonString;
Expand Down
16 changes: 8 additions & 8 deletions src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlTypes/SqlVector.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Licensed to the .NET Foundation under one or more agreements.
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.

Expand All @@ -15,7 +15,7 @@

namespace Microsoft.Data.SqlTypes;

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlVector.xml' path='docs/members[@name="SqlVector"]/SqlVector/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlVector.xml' path='docs/members[@name="SqlVector"]/SqlVector/*' />
public readonly struct SqlVector<T> : INullable, ISqlVector
where T : unmanaged
{
Expand Down Expand Up @@ -55,10 +55,10 @@ private SqlVector(int length)
Memory = new();
}

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlVector.xml' path='docs/members[@name="SqlVector"]/CreateNull/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlVector.xml' path='docs/members[@name="SqlVector"]/CreateNull/*' />
public static SqlVector<T> CreateNull(int length) => new(length);

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlVector.xml' path='docs/members[@name="SqlVector"]/ctor1/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlVector.xml' path='docs/members[@name="SqlVector"]/ctor1/*' />
public SqlVector(ReadOnlyMemory<T> memory)
{
(_elementType, _elementSize) = GetTypeFieldsOrThrow();
Expand Down Expand Up @@ -101,16 +101,16 @@ internal string GetString()

#region Properties

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlVector.xml' path='docs/members[@name="SqlVector"]/IsNull/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlVector.xml' path='docs/members[@name="SqlVector"]/IsNull/*' />
public bool IsNull { get; }

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlVector.xml' path='docs/members[@name="SqlVector"]/Null/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlVector.xml' path='docs/members[@name="SqlVector"]/Null/*' />
public static SqlVector<T>? Null => null;

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlVector.xml' path='docs/members[@name="SqlVector"]/Length/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlVector.xml' path='docs/members[@name="SqlVector"]/Length/*' />
public int Length { get; }

/// <include file='../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlVector.xml' path='docs/members[@name="SqlVector"]/Memory/*' />
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlTypes/SqlVector.xml' path='docs/members[@name="SqlVector"]/Memory/*' />
public ReadOnlyMemory<T> Memory { get; }

#endregion
Expand Down
Loading