SqlClient - класс

Nemiro.Data.dll

Основной класс для работы с базами данных SQL Server.

Иерархия наследования

System Object
Nemiro.Data.Sql SqlClient

Пространство имён: Nemiro.Data.Sql
Сборка: Nemiro.Data (в Nemiro.Data.dll) Версия: 2.11.4.126 (2.11.4.126)

Синтаксис

C++

Скопировать в буфер обмена Печать

public class SqlClient : IDisposable

public class SqlClient : IDisposable

Public Class SqlClient 
	Implements IDisposable

Public Class SqlClient 
	Implements IDisposable

Тип SqlClient предоставляет следующие члены.

Конструкторы

	Имя	Описание
	SqlClient	Инициализирует новый экземпляр класса SqlClient со значениями по умолчанию.
	SqlClient(Int32)	Инициализирует новый экземпляр класса SqlClient с указанием продолжительности кэширования результатов выполнения запросов к базе данных.
	SqlClient(String)	Инициализирует новый экземпляр класса SqlClient с указанием строки соединения с базой данных.
	SqlClient(String, Int32)	Инициализирует новый экземпляр класса SqlClient с указанием строки соединения с базой данных и времени кэширования результатов выполнения запросов.
	SqlClient(String, String)	Инициализирует новый экземпляр класса SqlClient с указанием строки соединения с базой данных и пути хранения записей кэша в файловой системе.
	SqlClient(Type, Int32)	Инициализирует новый экземпляр класса SqlClient с указанием параметров пользовательской системы кэширования результатов выполнения запросов к базе данных и продолжительности кэширования данных.
	SqlClient(Type, Object )	Инициализирует новый экземпляр класса SqlClient с указанием параметров пользовательской системы кэширования результатов выполнения запросов к базе данных.
	SqlClient(String, Type, Object )	Инициализирует новый экземпляр класса SqlClient с указанием строки соединения с базой данных и параметрами пользовательской системы кэширования результатов выполнения запросов.
	SqlClient(Type, Object , Int32)	Инициализирует новый экземпляр класса SqlClient.
	SqlClient(String, Int32, String, Type, Object )	Инициализирует новый экземпляр класса SqlClient с указанием основных параметров конфигурации класса.
	SqlClient(String, Int32, String, Type, Object , Type)	Инициализирует новый экземпляр класса SqlClient с указанием основных параметров конфигурации класса.

В начало страницы

Методы

	Имя	Описание
	Connect	Открывает соединение с базой данных, если нет открытого соединения.
	CopyDataToServer	Переносит данные из таблиц DataSet в базу данных. Используется SqlBulkCopy. Это самый быстрый и экономичный способ переноса больших объемов данных в базу.
	CopyTableToServer	Переносит указанную таблицу в базу данных. Используется SqlBulkCopy. Это самый быстрый и экономичный способ переноса больших объемов данных в базу.
	Disconnect	Закрывает соединение с базой данных, если оно открыто.
	Dispose	Освобождает все ресурсы, занятые объектом. Если необходимо, закрывает все открытые объектом соединения с базой данных.
	Equals	Определяет, равен ли заданный объект Object текущему объекту Object. (Унаследован от Object.)
	ExecuteNonQuery	Выполняет запрос и возвращает количество задействованных в инструкции строк данных. Данный метод используется совместно со свойствами CommandType, CommandText и Parameters.
	ExecuteNonQuery(SqlCommand)	Выполняет запрос к базе данных с указанными в экземпляре класса SqlCommand параметрами и возвращает количество задействованных в инструкции строк.
	ExecuteNonQuery(String)	Выполняет указанный SQL-запрос и возвращает количество задействованных в инструкции строк. Не рекомендуется использовать этот метод, чтобы избежать возникновение SQL Injection при неправильном построении запроса. Лучше используйте одну из перегрузок этого метода: ExecuteNonQuery или ExecuteNonQuery(SqlCommand).
	ExecuteScalar	Выполняет запрос и возвращает первый столбец первой строки из полученного набора данных. Данный метод используется совместно со свойствами CommandType, CommandText и Parameters.
	ExecuteScalar(SqlCommand)	Выполняет запрос к базе данных с указанными в экземпляре класса SqlCommand параметрами и возвращает первый столбец первой строки из полученного набора данных.
	ExecuteScalar(String)	Выполняет указанный SQL-запрос и возвращает первый столбец первой строки из полученного набора данных. Не рекомендуется использовать этот метод, чтобы избежать возникновение SQL Injection при неправильном построении запроса. Лучше используйте одну из перегрузок этого метода: ExecuteScalar или ExecuteScalar(SqlCommand).
	Finalize	Позволяет объекту Object попытаться освободить ресурсы и выполнить другие операции очистки, перед тем как объект Object будет утилизирован в процессе сборки мусора. (Унаследован от Object.)
	GetData	Выполняет запрос и возвращает DataSet. Данный метод используется совместно со свойствами CommandType, CommandText и Parameters.
	GetData(SqlCommand)	Выполняет запрос к базе данных с указанными в экземпляре класса SqlCommand параметрами и возвращает DataSet.
	GetData(String)	Выполняет указанную SQL-инструкцию и возвращает DataSet. Не рекомендуется использовать этот метод, чтобы избежать возникновение SQL Injection при неправильном построении запроса. Лучше используйте одну из перегрузок этого метода: GetData или GetData(SqlCommand).
	GetHashCode	Играет роль хэш-функции для определенного типа. (Унаследован от Object.)
	GetRow	Выполняет запрос и возвращает строку данных. Данный метод используется совместно со свойствами CommandType, CommandText и Parameters.
	GetRow(SqlCommand)	Выполняет запрос к базе данных с указанными в экземпляре класса SqlCommand параметрами и возвращает строку данных.
	GetRow(String)	Выполняет указанный SQL-запрос и возвращает строку данных. Не рекомендуется использовать этот метод, чтобы избежать возникновение SQL Injection при неправильном построении запроса. Лучше используйте одну из перегрузок этого метода: GetRow или GetRow(SqlCommand).
	GetTable	Выполняет запрос и возвращает DataTable. Данный метод используется совместно со свойствами CommandType, CommandText и Parameters.
	GetTable(SqlCommand)	Выполняет запрос к базе данных с указанными в экземпляре класса SqlCommand параметрами и возвращает DataTable.
	GetTable(String)	Выполняет запрос и возвращает DataTable. Не рекомендуется использовать этот метод, чтобы избежать возникновение SQL Injection при неправильном построении запроса. Лучше используйте одну из перегрузок этого метода: GetTable или GetTable(SqlCommand).
	GetType	Возвращает объект Type для текущего экземпляра. (Унаследован от Object.)
	MemberwiseClone	Создает неполную копию текущего объекта Object. (Унаследован от Object.)
	ToString	Возвращает объект String, который представляет текущий объект Object. (Унаследован от Object.)

В начало страницы

Свойства

	Имя	Описание
	Cache	Предоставляет доступ к параметрам кэширования.
	CacheAccessTimeout	Максимальное время ожидания освобождения доступа к записи файлового кэша (File). По истечению указанного времени, если файл записи не станет доступен, произойдет исключение.
	CacheBinder	Тип сириализатора пользовательских объектов.
	CacheBufferAccessTimeout	Максимальное время ожидания освобождения доступа к буферу файлового кэша (File). По истечению указанного времени, если буфер не станет доступен, будет предпринята попытка осуществления доступа к буферу, что, в некоторых случаях, может привести к возникновению исключения.
	CacheBufferSize	Максимальный объем данных (в килобайтах) для дополнительного кэша в памяти (ОЗУ) компьютера. Кэш памяти используется для ускорения работы файлового кэша (File). Значение по умолчанию 2048 Кб (2 Мб).
	CacheCustom	Тип пользовательского объекта кэширования. Используется совместно со свойствами CacheType и CacheCustomArgs.
	CacheCustomArgs	Массив дополнительных параметров инициализации пользовательского кэша. Эти параметры будут переданы в конструктор пользовательского кэша. Используется совместно со свойствами CacheType и CacheCustom.
	CacheDuration	Продолжительность хранения записи в кэше, в секундах. Если это свойство имеет значение 0 или меньше, кэширование данных не выполняется. Значение по умолчанию - ноль, если иное не указано в параметре NeData:Sql:CacheDuration файла конфигурации.
	CacheName	Имя ключа элемента кэша, если нужно указать определенный ключ (по умолчанию, формируется автоматически для конкретного запроса).
	CachePath	Полный физический путь к каталогу хранения файлов кэша, используется только если свойство CacheType имеет значение File.
	CacheType	Метод кэширования данных. Значение по умолчанию Auto, если иное не указано в параметре NeData:Sql:CacheType файла конфигурации.
	CommandText	Текст SQL-запроса, либо имя хранимой процедуры, которую необходимо выполнить.
	CommandTimeout	Время ожидания выполнения команды (в секундах). По умолчанию используется значение 30 секунд.
	CommandType	Тип команды, указанной в свойстве CommandText. Значение по умолчанию Auto, если иное не указано в параметре NeData:Sql:CommandType файла конфигурации.
	ConnectionMode	Режим соединения с базой данных. Значение по умолчанию Auto, если иное не указано в параметре NeData:Sql:ConnectionMode файла конфигурации.
	ConnectionString	Строка соединения с базой данных. Либо имя строки соединения в файле конфигурации (*.config). Значение по умолчанию: LocalSqlServer.
	ConnectionTimeout	Время ожидания соединения с сервером (в секундах) до возникновения исключения. По умолчанию ноль - будет использоваться значение в зависимости от конфигурации сервера.
	LastQueryResultsFromCache	Содержит True, если при выполнении последнего запроса результат был получен из кэша. В противном случае - False.
	LastQueryTime	Время, затраченное на выполнение последнего запроса к базе данных.
	Parameters	Коллекция параметров запроса.

В начало страницы

Заметки

По умолчанию, при инициализации класса используются параметры из файла конфигурации. Для web-проектов - web.config; для windows-приложений - app.config.

Поддерживаются следующие параметры:

NeData:Sql:ConnectionMode
NeData:Sql:CommandType
NeData:Sql:CacheType
NeData:Sql:CacheDuration (не рекомендуется использовать для установки глобального времени кэширования)
NeData:Sql:CachePath
NeData:Sql:CacheBinder
NeData:Sql:CacheBufferSize
NeData:Sql:CacheBufferAccessTimeout
NeData:Sql:CacheAccessTimeout
NeData:Sql:CacheCustom
NeData:Sql:CacheCustomArgs

В приложениях Windows имена параметров нужно записывать без двоеточий, и с учетом регистра. Например:

NeDataSqlCacheTyp
NeDataSqlAutoTrimmingStrings
NeDataSqlCachePath
и т.п.

По умолчанию используется строка соединения LocalSqlServer. В качестве ConnectionString можно указывать, как саму строку соединения, так и имя параметра в файле конфигурации. В web-приложениях строка соединения с именем LocalSqlServer иметь путь к SQL Server по умолчанию. Для использования параметра LocalSqlServer в веб-приложениях со своей базой данных, которая отличается от базы по умолчанию, необходимо удалить LocalSqlServer из файла конфигурации и добавить заново (написать код удаления и добавления):

XML

Скопировать в буфер обмена Печать

<remove name="LocalSqlServer"/> 
<add 
  name="LocalSqlServer" 
  connectionString="Data Source=.\SQLEXPRESS;Initial Catalog=example;Trusted_Connection=True;" 
/>

<remove name="LocalSqlServer"/> 
<add 
  name="LocalSqlServer" 
  connectionString="Data Source=.\SQLEXPRESS;Initial Catalog=example;Trusted_Connection=True;" 
/>

При работе с классом SqlClient рекомендуется использовать оператор using .

C++

Скопировать в буфер обмена Печать

using (SqlClient client = new SqlClient())
{
  // код работы с данными
}

using (SqlClient client = new SqlClient())
{
  // код работы с данными
}

Using client As new SqlClient()
  ' код работы с данными 
End Using

Using client As new SqlClient()
  ' код работы с данными 
End Using

Примеры

Обратите внимание
Показанные ниже примеры лишь демонстрируют использование класса SqlClient и содержат строки соединения с базой данных, а также и SQL-запросы. У вас все эти данные могут отличаться. Пожалуйста, учитывайте этот факт и не забудьте поменять строки соединения и запросы на свои, если захотите проверить работу представленных фрагментов кода.

Обратите внимание

Показанные ниже примеры лишь демонстрируют использование класса SqlClient и содержат строки соединения с базой данных, а также и SQL-запросы. У вас все эти данные могут отличаться. Пожалуйста, учитывайте этот факт и не забудьте поменять строки соединения и запросы на свои, если захотите проверить работу представленных фрагментов кода.

В следующем примере создается экземпляр класса SqlClient с использованием строки соединения по умолчанию (LocalSqlServer).

При помощи метода GetRow выполняется SQL-запрос и в переменную row передается строка данных.

C++

Скопировать в буфер обмена Печать

using (SqlClient client = new SqlClient())
{
  DataRow row = client.GetRow("SELECT * FROM table WHERE id = 1000");
  if(row == null)
  {
    Console.WriteLine("Запрос не дал результатов");
  }
  else
  {
    Console.WriteLine("id = {0}", row["id"]);
  }
}

using (SqlClient client = new SqlClient())
{
  DataRow row = client.GetRow("SELECT * FROM table WHERE id = 1000");
  if(row == null)
  {
    Console.WriteLine("Запрос не дал результатов");
  }
  else
  {
    Console.WriteLine("id = {0}", row["id"]);
  }
}

Using client As New SqlClient()
  Dim row As DataRow = client.GetRow("SELECT * FROM table WHERE id = 1000")
  If row Is Nothing Then
    Console.WriteLine("Запрос не дал результатов")
  Else
    Console.WriteLine("id = {0}", row("id"))
  End If 
End Using

Using client As New SqlClient()
  Dim row As DataRow = client.GetRow("SELECT * FROM table WHERE id = 1000")
  If row Is Nothing Then
    Console.WriteLine("Запрос не дал результатов")
  Else
    Console.WriteLine("id = {0}", row("id"))
  End If 
End Using

В следующем примере создается экземпляр класса SqlClient с явным указанием строки соединения.

C++

Скопировать в буфер обмена Печать

using (SqlClient client = new SqlClient(@"Data Source=.\SQLEXPRESS;Initial Catalog=example;Trusted_Connection=True;"))
{
  DataRow row = client.GetRow("SELECT * FROM table WHERE id = 1000");
  if(row == null)
  {
    Console.WriteLine("Запрос не дал результатов");
  }
  else
  {
    Console.WriteLine("id = {0}", row["id"]);
  }
}

using (SqlClient client = new SqlClient(@"Data Source=.\SQLEXPRESS;Initial Catalog=example;Trusted_Connection=True;"))
{
  DataRow row = client.GetRow("SELECT * FROM table WHERE id = 1000");
  if(row == null)
  {
    Console.WriteLine("Запрос не дал результатов");
  }
  else
  {
    Console.WriteLine("id = {0}", row["id"]);
  }
}

Using client As New SqlClient("Data Source=.\SQLEXPRESS;Initial Catalog=example;Trusted_Connection=True;")
  Dim row As DataRow = client.GetRow("SELECT * FROM table WHERE id = 1000")
  If row Is Nothing Then
    Console.WriteLine("Запрос не дал результатов")
  Else
    Console.WriteLine("id = {0}", row("id"))
  End If 
End Using

Using client As New SqlClient("Data Source=.\SQLEXPRESS;Initial Catalog=example;Trusted_Connection=True;")
  Dim row As DataRow = client.GetRow("SELECT * FROM table WHERE id = 1000")
  If row Is Nothing Then
    Console.WriteLine("Запрос не дал результатов")
  Else
    Console.WriteLine("id = {0}", row("id"))
  End If 
End Using

В следующем примере создается экземпляр класса SqlClient с указанием имени параметра строки соединения в файле конфигурации.

C++

Скопировать в буфер обмена Печать

using (SqlClient client = new SqlClient("MyConnectionString"))
{
  DataRow row = client.GetRow("SELECT * FROM table WHERE id = 1000");
  if(row == null)
  {
    Console.WriteLine("Запрос не дал результатов");
  }
  else
  {
    Console.WriteLine("id = {0}", row["id"]);
  }
}

using (SqlClient client = new SqlClient("MyConnectionString"))
{
  DataRow row = client.GetRow("SELECT * FROM table WHERE id = 1000");
  if(row == null)
  {
    Console.WriteLine("Запрос не дал результатов");
  }
  else
  {
    Console.WriteLine("id = {0}", row["id"]);
  }
}

Using client As New SqlClient("MyConnectionString")
  Dim row As DataRow = client.GetRow("SELECT * FROM table WHERE id = 1000")
  If row Is Nothing Then
    Console.WriteLine("Запрос не дал результатов")
  Else
    Console.WriteLine("id = {0}", row("id"))
  End If 
End Using

Using client As New SqlClient("MyConnectionString")
  Dim row As DataRow = client.GetRow("SELECT * FROM table WHERE id = 1000")
  If row Is Nothing Then
    Console.WriteLine("Запрос не дал результатов")
  Else
    Console.WriteLine("id = {0}", row("id"))
  End If 
End Using

В следующем примере показано применение встроенного механизма кэширования. Данные кэшируются в файловой системе, по умолчанию в одном каталоге с программой. Продолжительность кэширования указывается в свойстве CacheDuration. После выполнения запроса, в свойстве LastQueryTime можно получить информацию о продолжительности выполнения последнего запроса. При помощи свойства LastQueryResultsFromCache можно узнать, был ли использован кэш при выполнении последнего запроса или нет.

C++

Скопировать в буфер обмена Печать

using (SqlClient client = new SqlClient())
{
  // кэширование результатов в файлом кэше на 30 секунд
  client.CacheDuration = 30;
  client.CacheType = CachingType.File;
  // формирование запроса
  client.CommandText = "SELECT * FROM table";
  // выполнение запроса
  DataTable table = client.GetTable();
  // вывод результатов
  Console.WriteLine("Получено данных: {0}", table.Rows.Count);
  Console.WriteLine("Время выполнения запроса: {0}", client.LastQueryTime);
  Console.WriteLine("Результат получен из кэша: {0}", client.LastQueryResultsFromCache);
  // повторное выполнение аналогичного запроса
  table = client.GetTable();
  Console.WriteLine("Получено данных: {0}", table.Rows.Count);
  Console.WriteLine("Время выполнения запроса: {0}", client.LastQueryTime);
  Console.WriteLine("Результат получен из кэша: {0}", client.LastQueryResultsFromCache);
}

using (SqlClient client = new SqlClient())
{
  // кэширование результатов в файлом кэше на 30 секунд
  client.CacheDuration = 30;
  client.CacheType = CachingType.File;
  // формирование запроса
  client.CommandText = "SELECT * FROM table";
  // выполнение запроса
  DataTable table = client.GetTable();
  // вывод результатов
  Console.WriteLine("Получено данных: {0}", table.Rows.Count);
  Console.WriteLine("Время выполнения запроса: {0}", client.LastQueryTime);
  Console.WriteLine("Результат получен из кэша: {0}", client.LastQueryResultsFromCache);
  // повторное выполнение аналогичного запроса
  table = client.GetTable();
  Console.WriteLine("Получено данных: {0}", table.Rows.Count);
  Console.WriteLine("Время выполнения запроса: {0}", client.LastQueryTime);
  Console.WriteLine("Результат получен из кэша: {0}", client.LastQueryResultsFromCache);
}

Using client As New SqlClient()
  ' кэширование результатов в файлом кэше на 30 секунд
  client.CacheDuration = 30
  client.CacheType = CachingType.File
  ' формирование запроса
  client.CommandText = "SELECT * FROM test" 
  ' выполнение запроса 
  Dim table As DataTable = client.GetTable()
  ' вывод результатов
  Console.WriteLine("Получено данных: {0}", table.Rows.Count)
  Console.WriteLine("Время выполнения запроса: {0}", client.LastQueryTime)
  Console.WriteLine("Результат получен из кэша: {0}", client.LastQueryResultsFromCache)
  ' повторное выполнение аналогичного запроса
  table = client.GetTable()
  Console.WriteLine("Получено данных: {0}", table.Rows.Count)
  Console.WriteLine("Время выполнения запроса: {0}", client.LastQueryTime)
  Console.WriteLine("Результат получен из кэша: {0}", client.LastQueryResultsFromCache)
End Using

Using client As New SqlClient()
  ' кэширование результатов в файлом кэше на 30 секунд
  client.CacheDuration = 30
  client.CacheType = CachingType.File
  ' формирование запроса
  client.CommandText = "SELECT * FROM test" 
  ' выполнение запроса 
  Dim table As DataTable = client.GetTable()
  ' вывод результатов
  Console.WriteLine("Получено данных: {0}", table.Rows.Count)
  Console.WriteLine("Время выполнения запроса: {0}", client.LastQueryTime)
  Console.WriteLine("Результат получен из кэша: {0}", client.LastQueryResultsFromCache)
  ' повторное выполнение аналогичного запроса
  table = client.GetTable()
  Console.WriteLine("Получено данных: {0}", table.Rows.Count)
  Console.WriteLine("Время выполнения запроса: {0}", client.LastQueryTime)
  Console.WriteLine("Результат получен из кэша: {0}", client.LastQueryResultsFromCache)
End Using

См. также

Nemiro.Data.Sql - пространство имён