Skip to content
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

XML Documentation Fixes - Batch 8 #2871

Merged
merged 5 commits into from
Sep 23, 2024
Merged

XML Documentation Fixes - Batch 8 #2871

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f9b0678
Batch 8.1
benrr101 Sep 18, 2024
b6471d6
Batch 8.2
benrr101 Sep 18, 2024
1bb8a6a
Batch 8.3
benrr101 Sep 18, 2024
e60c14d
Batch 8.4?
benrr101 Sep 18, 2024
146c711
Checking things over
benrr101 Sep 19, 2024
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
244 changes: 183 additions & 61 deletions doc/snippets/Microsoft.Data.Sql/SqlDataSourceEnumerator.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,65 +1,187 @@
<?xml version="1.0"?>
<docs>
<members name="SqlDataSourceEnumerator">
<docs>
<members name="SqlDataSourceEnumerator">
<SqlDataSourceEnumerator>
<summary>Provides a mechanism for enumerating all available instances of SQL Server within the local network.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
SQL Server makes it possible for applications to determine the existence of its instances within the current network. The <xref:Microsoft.Data.Sql.SqlDataSourceEnumerator> class exposes this information to the application developer, providing a <xref:System.Data.DataTable> containing information about all the available servers. This returned table contains a list of server instances that matches the list provided when a user attempts to create a new connection, and on the `Connection Properties` dialog box, expands the drop-down list containing all the available servers.

]]></format>
</remarks>
<related type="Article" href="/dotnet/framework/data/adonet/sql/enumerating-instances-of-sql-server">Enumerating Instances of SQL Server</related>
</SqlDataSourceEnumerator>
<GetDataSources>
<summary>Retrieves a <see cref="T:System.Data.DataTable" /> containing information about all visible SQL Server instances.</summary>
<returns>A <see cref="T:System.Data.DataTable" /> containing information about the visible SQL Server instances.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
The table returned by this method contains the following columns, all of which contain strings:

|Column|Description|
|------------|-----------------|
|**ServerName**|Name of the server.|
|**InstanceName**|Name of the server instance. Blank if the server is running as the default instance.|
|**IsClustered**|Indicates whether the server is part of a cluster.|
|**Version**|Version of the server:<br /><br />10.0.xx for SQL Server 2008<br />10.50.x for SQL Server 2008 R2<br />11.0.xx for SQL Server 2012<br />12.0.xx for SQL Server 2014<br />13.0.xx for SQL Server 2016<br />14.0.xx for SQL Server 2017|

> [!NOTE]
> Due to the nature of the mechanism used by <xref:Microsoft.Data.Sql.SqlDataSourceEnumerator> to locate data sources on a network, the method will not always return a complete list of the available servers, and the list might not be the same on every call. If you plan to use this function to let users select a server from a list, make sure that you always also supply an option to type in a name that is not in the list, in case the server enumeration does not return all the available servers. In addition, this method may take a significant amount of time to execute, so be careful about calling it when performance is critical.

## Examples
The following console application retrieves information about all the visible SQL Server instances and displays the information in the console window.

[!code-csharp[SqlDataSourceEnumerator.Example#1](~/../sqlclient/doc/samples/SqlDataSourceEnumeratorExample.cs#1)]

]]></format>
</remarks>
<related type="Article" href="/dotnet/framework/data/adonet/sql/enumerating-instances-of-sql-server">Enumerating Instances of SQL Server</related>
</GetDataSources>
<summary>
Provides a mechanism for enumerating all available instances of SQL Server within the local network.
</summary>
<remarks>
SQL Server makes it possible for applications to determine the existence of its instances within the current network. The <see cref="T:Microsoft.Data.Sql.SqlDataSourceEnumerator" /> class exposes this information to the application developer, providing a <see cref="T:System.Data.DataTable" /> containing information about all the available servers. This returned table contains a list of server instances that matches the list provided when a user attempts to create a new connection, and on the <c>Connection Properties</c> dialog box, expands the drop-down list containing all the available servers.
</remarks>
<seealso href="/dotnet/framework/data/adonet/sql/enumerating-instances-of-sql-server">
Enumerating Instances of SQL Server
</seealso>
</SqlDataSourceEnumerator>
<GetDataSources>
<summary>
Retrieves a <see cref="T:System.Data.DataTable" /> containing information about all visible SQL Server instances.
</summary>
<returns>
A <see cref="T:System.Data.DataTable" /> containing information about the visible SQL Server instances.
</returns>
<remarks>
<para>
The table returned by this method contains the following columns, all of which contain strings:
</para>
<para>
<list type="table">
<listheader>
<term>Column</term>
<description>Description</description>
</listheader>
<item>
<term><b>ServerName</b></term>
<description>Name of the server.</description>
</item>
<item>
<term><b>InstanceName</b></term>
<description>Name of the server instance. Blank if the server is running as the default instance.</description>
</item>
<item>
<term><b>IsClustered</b></term>
<description>Indicates whether the server is part of a cluster.</description>
</item>
<item>
<term><b>Version</b></term>
<description>
Version of the server:
<list type="bullet">
<item>10.0.xx for SQL Server 2008</item>
<item>10.50.x for SQL Server 2008 R2</item>
<item>11.0.xx for SQL Server 2012 </item>
<item>12.0.xx for SQL Server 2014</item>
<item>13.0.xx for SQL Server 2016</item>
<item>14.0.xx for SQL Server 2017</item>
</list>
</description>
</item>
</list>
<note type="note">
Due to the nature of the mechanism used by <see cref="T:Microsoft.Data.Sql.SqlDataSourceEnumerator" /> to locate data sources on a network, the method will not always return a complete list of the available servers, and the list might not be the same on every call. If you plan to use this function to let users select a server from a list, make sure that you always also supply an option to type in a name that is not in the list, in case the server enumeration does not return all the available servers. In addition, this method may take a significant amount of time to execute, so be careful about calling it when performance is critical.
</note>
</para>
</remarks>
<example>
<para>
The following console application retrieves information about all the visible SQL Server instances and displays the information in the console window.
</para>
<!-- SqlDataSourceEnumeratorExample -->
<code language="c#">
using System;
using Microsoft.Data.Sql;

class Program
{
static void Main()
{
// Retrieve the enumerator instance and then the data.
SqlDataSourceEnumerator instance = SqlDataSourceEnumerator.Instance;
System.Data.DataTable table = instance.GetDataSources();

// Display the contents of the table.
DisplayData(table);

Console.WriteLine("Press any key to continue.");
Console.ReadKey();
}

private static void DisplayData(System.Data.DataTable table)
{
foreach (System.Data.DataRow row in table.Rows)
{
foreach (System.Data.DataColumn col in table.Columns)
{
Console.WriteLine("{0} = {1}", col.ColumnName, row[col]);
}
Console.WriteLine("============================");
}
}
}
</code>
</example>
<seealso href="/dotnet/framework/data/adonet/sql/enumerating-instances-of-sql-server">
Enumerating Instances of SQL Server
</seealso>
</GetDataSources>
<Instance>
<summary>Gets an instance of the <see cref="T:Microsoft.Data.Sql.SqlDataSourceEnumerator"/>, which can be used to retrieve information about available SQL Server instances.</summary>
<value>An instance of the <see cref="T:Microsoft.Data.Sql.SqlDataSourceEnumerator"/> used to retrieve information about available SQL Server instances.</value>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
The <xref:Microsoft.Data.Sql.SqlDataSourceEnumerator> class does not provide a constructor. Use the <xref:Microsoft.Data.Sql.SqlDataSourceEnumerator.Instance%2A> property to retrieve an instance of the class instead.

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

## Examples
The following console application displays a list of all the available SQL Server 2005 instances within the local network. This code uses the <xref:System.Data.DataTable.Select%2A> method to filter the rows in the table returned by the <xref:Microsoft.Data.Sql.SqlDataSourceEnumerator.GetDataSources%2A> method.
[!code-csharp[SqlDataSourceEnumeratorVersionExample#1](~/../sqlclient/doc/samples/SqlDataSourceEnumeratorVersionExample.cs#1)]

]]></format>
</remarks>
<related type="Article" href="/dotnet/framework/data/adonet/sql/enumerating-instances-of-sql-server">Enumerating Instances of SQL Server</related>

<summary>
Gets an instance of the <see cref="T:Microsoft.Data.Sql.SqlDataSourceEnumerator" /> , which can be used to retrieve information about available SQL Server instances.
</summary>
<value>
An instance of the <see cref="T:Microsoft.Data.Sql.SqlDataSourceEnumerator" /> used to retrieve information about available SQL Server instances.
</value>
<remarks>
<para>
The <see cref="T:Microsoft.Data.Sql.SqlDataSourceEnumerator" /> class does not provide a constructor. Use the <see cref="P:Microsoft.Data.Sql.SqlDataSourceEnumerator.Instance" /> property to retrieve an instance of the class instead.
</para>
<!-- SqlDataSourceEnumeratorExample -->
<code language="c#">
using System;
using Microsoft.Data.Sql;

class Program
{
static void Main()
{
// Retrieve the enumerator instance and then the data.
SqlDataSourceEnumerator instance =
SqlDataSourceEnumerator.Instance;
System.Data.DataTable table = instance.GetDataSources();

// Display the contents of the table.
DisplayData(table);

Console.WriteLine("Press any key to continue.");
Console.ReadKey();
}

private static void DisplayData(System.Data.DataTable table)
{
foreach (System.Data.DataRow row in table.Rows)
{
foreach (System.Data.DataColumn col in table.Columns)
{
Console.WriteLine("{0} = {1}", col.ColumnName, row[col]);
}
Console.WriteLine("============================");
}
}
}
</code>
</remarks>
<example>
<para>
The following console application displays a list of all the available SQL Server 2005 instances within the local network. This code uses the <see cref="M:System.Data.DataTable.Select" /> method to filter the rows in the table returned by the <see cref="M:Microsoft.Data.Sql.SqlDataSourceEnumerator.GetDataSources" /> method.
</para>
<!-- SqlDataSourceEnumeratorVersionExample -->
<code language="c#">
using System;
using Microsoft.Data.Sql;

class Program
{
static void Main()
{
// Retrieve the enumerator instance, and
// then retrieve the data sources.
SqlDataSourceEnumerator instance = SqlDataSourceEnumerator.Instance;
System.Data.DataTable table = instance.GetDataSources();

// Filter the sources to just show SQL Server 2012 instances.
System.Data.DataRow[] rows = table.Select("Version LIKE '11%'");
foreach (System.Data.DataRow row in rows)
{
Console.WriteLine(row["ServerName"]);
}

Console.WriteLine("Press any key to continue.");
Console.ReadKey();
}
}
</code>
</example>
<seealso href="/dotnet/framework/data/adonet/sql/enumerating-instances-of-sql-server">
Enumerating Instances of SQL Server
</seealso>
</Instance>
</members>
</members>
</docs>
Loading