Skip to content

Documentation | Correct SqlDataRecord, SqlMetaData documentation #4440

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

Open
edwardneal wants to merge 2 commits into
base: main
Choose a base branch
from
+71 −63
Open

Documentation | Correct SqlDataRecord, SqlMetaData documentation #4440

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d16e628
Correct SqlMetaData documentation
edwardneal Jul 12, 2026
bf38544
Correct SqlDataRecord documentation
edwardneal Jul 12, 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
56 changes: 25 additions & 31 deletions doc/samples/SqlDataRecord.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,52 +2,50 @@
namespace SqlDataRecordCS;

using System;
using System.Collections.Generic;
using System.Data;
using System.Data.Sql;
using System.Data.SqlTypes;
using Microsoft.SqlServer.Server;
using Microsoft.Data.SqlClient.Server;

public sealed partial class SqlDataRecordTester
{
private SqlDataRecordTester()
{
}

[SqlProcedure]
public static void CallTestMethods()
{
CreateNewRecord();
CreateNewRecord1();

}

//<Snippet1>
//using System;
//using System.Collections.Generic;
//using System.Data;
//using Microsoft.Data.SqlClient.Server;

[SqlProcedure]
public static void CreateNewRecord()
// Stream rows to SQL Server as a table-valued parameter.
public static IEnumerable<SqlDataRecord> GetRecords()
{

// Variables.
SqlDataRecord record;
// Re-use a single SqlDataRecord instance rather than allocating a new one for each row.
// Each row's values are read before SqlCommand advances to the next one.
SqlDataRecord record;

// Create a new record with the column metadata. The constructor is
// able to accept a variable number of parameters.
record = new SqlDataRecord(new SqlMetaData[] { new SqlMetaData("Column1", SqlDbType.NVarChar, 12),
// Create a new record with the column metadata. The constructor is
// able to accept a variable number of parameters.
record = new SqlDataRecord(new SqlMetaData[] { new SqlMetaData("Column1", SqlDbType.NVarChar, 12),
new SqlMetaData("Column2", SqlDbType.Int),
new SqlMetaData("Column3", SqlDbType.DateTime) });

// Set the record fields.
record.SetString(0, "Hello World!");
record.SetInt32(1, 42);
record.SetDateTime(2, DateTime.Now);
// Set the record fields.
record.SetString(0, "Hello World!");
record.SetInt32(1, 42);
record.SetDateTime(2, DateTime.Now);

// Send the record to the calling program.
SqlContext.Pipe.Send(record);
// Set the fields of the first record and stream it to SQL Server.
yield return record;

// Set the fields of the second record and stream it to SQL Server.
record.SetInt32(1, 0);
yield return record;
}
//</Snippet1>

public static void CreateNewRecord1()
public static void CreateNewRecord()
{

//<Snippet2>
Expand All @@ -65,15 +63,11 @@ public static void CreateNewRecord1()
// Create a new record with the column metadata.
record = new SqlDataRecord(new SqlMetaData[] { column1Info,
column2Info });
//</Snippet2>

// Set the record fields.
record.SetString(0, "Hello World!");
record.SetInt32(1, 42);

// Send the record to the calling program.
SqlContext.Pipe.Send(record);

//</Snippet2>
}
}
#endif
19 changes: 11 additions & 8 deletions doc/samples/SqlMetaData.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,9 @@
namespace SqlMetaDataCS;

using System;
using System.Collections.Generic;
using System.Data;
using System.Data.Sql;
using System.Data.SqlTypes;
using Microsoft.SqlServer.Server;
using Microsoft.Data.SqlClient.Server;

public sealed partial class SqlMetaDataTester
{
Expand All @@ -14,10 +13,12 @@ private SqlMetaDataTester()
}

//<Snippet1>
// using System;
// using System.Collections.Generic;
// using System.Data;
// using Microsoft.Data.SqlClient.Server;

[SqlProcedure]
public static void CreateNewRecord()
public static IEnumerable<SqlDataRecord> ReturnNewRecords()
{
// Variables.
SqlMetaData column1Info;
Expand All @@ -35,13 +36,15 @@ public static void CreateNewRecord()
column2Info,
column3Info });

// Set the record fields.
// Set the fields of the first record and stream it to SQL Server.
record.SetString(0, "Hello World!");
record.SetInt32(1, 42);
record.SetDateTime(2, DateTime.Now);
yield return record;

// Send the record to the calling program.
SqlContext.Pipe.Send(record);
// Set the fields of the second record and stream it to SQL Server.
record.SetInt32(1, 0);
yield return record;
}
//</Snippet1>

Expand Down
32 changes: 18 additions & 14 deletions doc/snippets/Microsoft.Data.SqlClient.Server/SqlDataRecord.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,33 @@
<docs>
<docs>
<members name="SqlDataRecord">
<SqlDataRecord>
<summary>
Represents a single row of data and its metadata.
</summary>
<remarks>
<para>
This class is used together with <see cref="T:Microsoft.SqlServer.Server.SqlPipe" /> to send result sets to the client from managed code stored-procedures.
This class describes a single row of a table-valued parameter. Construct one from an array of <see cref="T:Microsoft.Data.SqlClient.Server.SqlMetaData" /> objects which describe the column metadata of the record, populate it with the <b>Set&lt;Type&gt;</b> methods and assign it (or an <see cref="T:System.Collections.Generic.IEnumerable{Microsoft.Data.SqlClient.Server.SqlDataRecord}" /> for multiple rows) to <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" />.
</para>
<para>
When writing common language runtime (CLR) applications, you should re-use existing <b>SqlDataRecord</b> objects instead of creating new ones every time. Creating many new <b>SqlDataRecord</b> objects could severely deplete memory and adversely affect performance.
For best performance when sending multiple rows, re-use a single <see cref="T:Microsoft.Data.SqlClient.Server.SqlDataRecord" /> instance across an <see cref="T:System.Collections.Generic.IEnumerable{Microsoft.Data.SqlClient.Server.SqlDataRecord}" /> iterator: set new column values and <see langword="yield return" /> the same instance for each row. <see cref="T:Microsoft.Data.SqlClient.SqlCommand" /> will read each record before advancing to the next.
</para>
</remarks>
<example>
<para>
The following example shows how to create several <see cref="T:Microsoft.Data.SqlClient.Server.SqlMetaData" /> objects, which describe the column metadata of a record, and creating a <see cref="T:Microsoft.Data.SqlClient.Server.SqlDataRecord" />. The column values of the <see cref="T:Microsoft.Data.SqlClient.Server.SqlDataRecord" /> are set and the <see cref="T:Microsoft.Data.SqlClient.Server.SqlDataRecord" /> is sent to the calling program by using the <see cref="T:Microsoft.SqlServer.Server.SqlContext" /> class.
The following example shows how to create several <see cref="T:Microsoft.Data.SqlClient.Server.SqlMetaData" /> objects describing the column metadata of a record, then to create a re-usable <see cref="T:Microsoft.Data.SqlClient.Server.SqlDataRecord" /> instance. The column values of the <see cref="T:Microsoft.Data.SqlClient.Server.SqlDataRecord" /> are set and the same <see cref="T:Microsoft.Data.SqlClient.Server.SqlDataRecord" /> can be used to stream multiple rows to SQL Server as a table-valued parameter.
</para>
<!-- SqlDataRecord #1 -->
<code language="c#">
using System;
using System.Collections.Generic;
using System.Data;
using Microsoft.Data.SqlClient.Server;
[Microsoft.Data.SqlClient.Server.SqlProcedure]
public static void CreateNewRecord()

// Stream rows to SQL Server as a table-valued parameter.
public static IEnumerable&lt;SqlDataRecord&gt; CreateNewRecord()
{

// Variables.
// Re-use a single SqlDataRecord instance rather than allocating a new one for each row.
// Each row's values are read before SqlCommand advances to the next one.
SqlDataRecord record;

// Create a new record with the column metadata. The constructor is
Expand All @@ -38,8 +41,12 @@
record.SetInt32(1, 42);
record.SetDateTime(2, DateTime.Now);

// Send the record to the calling program.
SqlContext.Pipe.Send(record);
// Set the fields of the first record and stream it to SQL Server.
yield return record;

// Set the fields of the second record and stream it to SQL Server.
record.SetInt32(1, 0);
yield return record;
}
</code>
</example>
Expand Down Expand Up @@ -75,9 +82,6 @@
// Set the record fields.
record.SetString(0, "Hello World!");
record.SetInt32(1, 42);

// Send the record to the calling program.
SqlContext.Pipe.Send(record);
</code>
</example>
<exception cref="T:System.ArgumentNullException">
Expand Down
27 changes: 17 additions & 10 deletions doc/snippets/Microsoft.Data.SqlClient.Server/SqlMetaData.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,21 @@
<docs>
<docs>
<members name="SqlMetaData">
<SqlMetaData>
<summary>
Specifies and retrieves metadata information from parameters and columns of <see cref="T:Microsoft.Data.SqlClient.Server.SqlDataRecord" /> objects. This class cannot be inherited.
Specifies the metadata information of a columns used by a <see cref="T:Microsoft.Data.SqlClient.Server.SqlDataRecord" /> objects. This class cannot be inherited.
</summary>
<example>
<para>
The following example shows the creation of several <see cref="T:Microsoft.Data.SqlClient.Server.SqlMetaData" /> objects, which describe the column metadata of a record, and the creation of a <see cref="T:Microsoft.Data.SqlClient.Server.SqlDataRecord" />. The column values of the <see cref="T:Microsoft.Data.SqlClient.Server.SqlDataRecord" /> are set and the <see cref="T:Microsoft.Data.SqlClient.Server.SqlDataRecord" /> is sent to the calling program using the <see cref="T:Microsoft.SqlServer.Server.SqlContext" /> class.
The following example shows the creation of several <see cref="T:Microsoft.Data.SqlClient.Server.SqlMetaData" /> objects, which describe the column metadata of a record, and the generation of a stream of <see cref="T:Microsoft.Data.SqlClient.Server.SqlDataRecord" /> records. These <see cref="T:Microsoft.Data.SqlClient.Server.SqlDataRecord" /> records can be streamed to SQL Server as a table-valued parameter by assigning the return value of the method to the <see cref="P:Microsoft.Data.SqlClient.SqlParameter.Value" /> property.
</para>
<!-- SqlMetaData #1 -->
<code language="c#">
using System;
using System.Collections.Generic;
using System.Data;
using Microsoft.Data.SqlClient.Server;

[Microsoft.Data.SqlClient.Server.SqlProcedure]
public static void CreateNewRecord()

public static IEnumerable&lt;SqlDataRecord&gt; ReturnNewRecords()
{
// Variables.
SqlMetaData column1Info;
Expand All @@ -32,16 +34,21 @@
column2Info,
column3Info });

// Set the record fields.
// Set the fields of the first record and stream it to SQL Server.
record.SetString(0, "Hello World!");
record.SetInt32(1, 42);
record.SetDateTime(2, DateTime.Now);
yield return record;

// Send the record to the calling program.
SqlContext.Pipe.Send(record);
// Set the fields of the second record and stream it to SQL Server.
record.SetInt32(1, 0);
yield return record;
}
</code>
</example>
<remarks>
<see cref="T:Microsoft.Data.SqlClient.Server.SqlMetaData" /> instances are typically built once and reused to construct many <see cref="T:Microsoft.Data.SqlClient.Server.SqlDataRecord" /> objects which are streamed to SQL Server as a table-valued parameter. For more information, see <see href="https://learn.microsoft.com/sql/connect/ado-net/sql/table-valued-parameters">Table-Valued Parameters</see>.
</remarks>
</SqlMetaData>
<ctor>
<summary>
Expand Down Expand Up @@ -456,7 +463,7 @@
The SQL Server type name for <paramref name="userDefinedType" />.
</param>
<summary>
Initializes a new instance of the <see cref="T:Microsoft.Data.SqlClient.Server.SqlMetaData" /> class with the specified column name, user-defined type (UDT), and SQLServer type.
Initializes a new instance of the <see cref="T:Microsoft.Data.SqlClient.Server.SqlMetaData" /> class with the specified column name, user-defined type (UDT), and SQL Server type.
</summary>
</ctorNameDbTypeUserDefinedTypeServerTypeName>
<ctorNameDbTypeMaxLengthLocaleCompareOptions>
Expand Down
Loading