Skip to content

Commit

Permalink
XML Documentation Fixes - Batch 8 (#2871)
Browse files Browse the repository at this point in the history 
* Batch 8.1

* Batch 8.2

* Batch 8.3

* Batch 8.4?

* Checking things over
  • Loading branch information
@benrr101
benrr101 authored Sep 23, 2024
1 parent cb11317 commit 3d9c1e4
Show file tree
Hide file tree
Showing 23 changed files with 6,374 additions and 3,389 deletions.
244 changes: 183 additions & 61 deletions doc/snippets/Microsoft.Data.Sql/SqlDataSourceEnumerator.xml
View file
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

0 comments on commit 3d9c1e4

Please sign in to comment.