diff --git a/ydb/docs/en/core/integrations/orm/dapper.md b/ydb/docs/en/core/integrations/orm/dapper.md
index 763720c320c5..ac0e9e4e6f98 100644
--- a/ydb/docs/en/core/integrations/orm/dapper.md
+++ b/ydb/docs/en/core/integrations/orm/dapper.md
@@ -1,295 +1,8 @@
# Using Dapper
-[Dapper](https://www.learndapper.com/) is a micro ORM (Object-Relational Mapping) tool that provides a simple and flexible way to interact with databases. It operates on top of the [ADO.NET](https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/) standard and offers various features that simplify database operations.
+[Dapper](https://www.learndapper.com/) is a micro ORM (Object-Relational Mapping) tool that provides a simple and flexible way to interact with databases. It operates on top of the [ADO.NET](../../reference/languages-and-apis/ado-net/index.md) standard and offers various features that simplify database operations.
-## ADO.NET
-
-ADO.NET is a set of classes that provide developers with data access using the [.NET Framework](https://dotnet.microsoft.com/en-us/download/dotnet-framework) platform.
-
-The [{{ ydb-short-name }} SDK for C#](https://github.com/ydb-platform/ydb-dotnet-sdk) offers a set of classes that implement the ADO.NET standard.
-
-### Installation {#install}
-
-The ADO.NET implementation for {{ ydb-short-name }} is available via [NuGet](https://www.nuget.org/packages/Ydb.Sdk/).
-
-```dotnet
-dotnet add package Ydb.Sdk
-```
-
-### Creating a connection
-
-A connection to {{ ydb-short-name }} is established using `YdbConnection`.
-
-1. **Using the parameterless constructor**:
-
- The following code creates a connection with the default settings:
-
- ```c#
- await using var ydbConnection = new YdbConnection();
- await ydbConnection.OpenAsync();
- ```
-
- This option creates a connection to the database at the URL `grpc://localhost:2136/local` with anonymous authentication.
-
-2. **Using the constructor with a connection string**:
-
- In the following example, a connection is created using a [connection string in ADO.NET](https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/connection-strings):
-
- ```c#
- await using var ydbConnection = new YdbConnection(
- "Host=database-sample-grpc;Port=2135;Database=/root/database-sample");
- await ydbConnection.OpenAsync();
- ```
-
- In this case, the connection is established at the URL `grpc://database-sample-grpc:2135/root/database-sample`. When using the connection string method, parameters are specified as key-value pairs, separated by semicolons (`key1=value1;key2=value2`). The supported set of keys is explained [below](#connection-parameters).
-
-3. **Using the constructor with a `YdbConnectionStringBuilder` argument**:
-
- The example using `YdbConnectionStringBuilder` is demonstrated in the code below:
-
- ```c#
- var ydbConnectionBuilder = new YdbConnectionStringBuilder
- {
- Host = "server",
- Port = 2135,
- Database = "/ru-prestable/my-table",
- UseTls = true
- };
- await using var ydbConnection = new YdbConnection(ydbConnectionBuilder);
- await ydbConnection.OpenAsync();
- ```
-
-### Connection parameters {#connection-parameters}
-
-All available connection parameters are defined as properties in the `YdbConnectionStringBuilder`.
-
-Here is a list of parameters that can be specified in the connection string:
-
-| Parameter | Description | Default value |
-|-------------------|-------------------------------------------------------------------------------------------------------------|---------------|
-| `Host` | Specifies the {{ ydb-short-name }} server host | `localhost` |
-| `Port` | Specifies the {{ ydb-short-name }} server port | `2136` |
-| `Database` | Specifies the database name | `/local` |
-| `User` | Specifies the username | Not defined |
-| `Password` | Specifies the user password | Not defined |
-| `UseTls` | Indicates whether to use the TLS protocol (`grpcs` or `grpc`) | `false` |
-| `MaxSessionPool` | Specifies the maximum session pool size | `100` |
-| `RootCertificate` | Specifies the path to the trusted server TLS certificate. If this parameter is set, `UseTls` will be `true` | Not defined |
-
-There are also additional parameters that do not participate in forming the connection string. These can only be specified using `YdbConnectionStringBuilder`:
-
-| Parameter | Description | Default value |
-|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|
-| `LoggerFactory` | This parameter accepts an instance that implements the [ILoggerFactory](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.iloggerfactory) interface. The `ILoggerFactory` is a standard interface for logging factories in .NET. It is possible to use popular logging frameworks such as [NLog](https://github.com/NLog/NLog), [serilog](https://github.com/serilog/serilog), [log4net](https://github.com/apache/logging-log4net) | `NullLoggerFactory.Instance` |
-| `CredentialsProvider` | An authentication provider that implements the `Ydb.Sdk.Auth.ICredentialsProvider`. [YDB SDK](#install) provides several standard ways for authentication:
1) `Ydb.Sdk.Auth.AnonymousProvider`. Anonymous YDB access, mainly for tests purposes.
2) `Ydb.Sdk.Auth.TokenProvider`. Token authentication for OAuth-like tokens.
3) `Ydb.Sdk.Auth.StaticCredentialsProvider`. Username and password based authentication.
For Yandex.Cloud specific authentication methods, consider using **[ydb-dotnet-yc](https://github.com/ydb-platform/ydb-dotnet-yc)** | `AnonymousProvider` |
-
-### Usage
-
-The `YdbCommand` object is used to execute queries:
-
-```c#
-await using var ydbConnection = new YdbConnection();
-await ydbConnection.OpenAsync();
-
-var ydbCommand = ydbConnection.CreateCommand();
-ydbCommand.CommandText = "SELECT 'Hello, World!'u";
-Console.WriteLine(await ydbCommand.ExecuteScalarAsync());
-```
-
-This example demonstrates how to run the `Hello, World!` query and output its result to the console.
-
-### Transactions
-
-To create a client transaction, use the `ydbConnection.BeginTransaction()` method.
-
-There are two signatures of this method with a single isolation level parameter:
-
-- `BeginTransaction(TxMode txMode)`
- The `Ydb.Sdk.Services.Query.TxMode` is a {{ ydb-short-name }} specific isolation level, you can read more about it [here](../../concepts/transactions.md).
-
-- `BeginTransaction(IsolationLevel isolationLevel)`
- The `System.Data.IsolationLevel` parameter from the standard ADO.NET. The following isolation levels are supported: `Serializable` and `Unspecified`. Both are equivalent to the `TxMode.SerializableRW`.
-
-Calling `BeginTransaction()` without parameters opens a transaction with level the `TxMode.SerializableRW`.
-
-Consider the following example of using a transaction:
-
-```c#
-await using var ydbConnection = new YdbConnection();
-await ydbConnection.OpenAsync();
-
-var ydbCommand = ydbConnection.CreateCommand();
-
-ydbCommand.Transaction = ydbConnection.BeginTransaction();
-ydbCommand.CommandText = """
- UPSERT INTO episodes (series_id, season_id, episode_id, title, air_date)
- VALUES (2, 5, 13, "Test Episode", Date("2018-08-27"))
- """;
-await ydbCommand.ExecuteNonQueryAsync();
-
-ydbCommand.CommandText = """
- INSERT INTO episodes(series_id, season_id, episode_id, title, air_date)
- VALUES
- (2, 5, 21, "Test 21", Date("2018-08-27")),
- (2, 5, 22, "Test 22", Date("2018-08-27"))
- """;
-await ydbCommand.ExecuteNonQueryAsync();
-await ydbCommand.Transaction.CommitAsync();
-```
-
-Here, a transaction with the `Serializable` isolation level is opened, and two inserts into the `episodes` table are executed.
-
-### Using parameters
-
-SQL query parameters can be set using the `YdbParameter` class.
-
-In this example, the parameters `$series_id`, `$season_id`, and `$limit_size` are declared within the SQL query and then added to the command using `YdbParameter` objects.
-
-```c#
-await using var connection = new YdbConnection(_cmdOptions.SimpleConnectionString);
-await connection.OpenAsync();
-
-var ydbCommand = connection.CreateCommand();
-ydbCommand.CommandText = """
- DECLARE $series_id AS Uint64;
- DECLARE $season_id AS Uint64;
- DECLARE $limit_size AS Uint64;
-
- SELECT series_id, season_id, episode_id, air_date, title
- FROM episodes WHERE series_id = $series_id AND season_id > $season_id
- ORDER BY $series_id, $season_id, $episode_id
- LIMIT $limit_size;
- """;
-ydbCommand.Parameters.Add(new YdbParameter("$series_id", DbType.UInt64, 1U));
-ydbCommand.Parameters.Add(new YdbParameter("$season_id", DbType.UInt64, 1U));
-ydbCommand.Parameters.Add(new YdbParameter("$limit_size", DbType.UInt64, 3U));
-
-var ydbDataReader = await ydbCommand.ExecuteReaderAsync();
-
-_logger.LogInformation("Selected rows:");
-while (await ydbDataReader.ReadAsync())
-{
- _logger.LogInformation(
- "series_id: {series_id}, season_id: {season_id}, episode_id: {episode_id}, air_date: {air_date}, title: {title}",
- ydbDataReader.GetUint64(0), ydbDataReader.GetUint64(1), ydbDataReader.GetUint64(2),
- ydbDataReader.GetDateTime(3), ydbDataReader.GetString(4));
-}
-```
-
-In this example, the parameters `series_id`, `season_id`, and `limit_size` are declared within the SQL query and then added to the command using `YdbParameter` objects.
-
-### Alternative style with `@` prefix
-
-Parameters can also be specified using the `@` prefix. In this case, there is no need to declare variables within the query itself. The query will look like this:
-
-```c#
-ydbCommand.CommandText = """
- SELECT series_id, season_id, episode_id, air_date, title
- FROM episodes
- WHERE series_id = @series_id AND season_id > @season_id
- ORDER BY series_id, season_id, episode_id
- LIMIT @limit_size;
- """;
-ydbCommand.Parameters.Add(new YdbParameter("series_id", DbType.UInt64, 1U));
-ydbCommand.Parameters.Add(new YdbParameter("season_id", DbType.UInt64, 1U));
-ydbCommand.Parameters.Add(new YdbParameter("limit_size", DbType.UInt64, 3U));
-```
-
-ADO.NET the query will be prepared for you so that the variables match [YQL](../../yql/reference/index.md). The type will be determined according to the [DbType](https://learn.microsoft.com/en-us/dotnet/api/system.data.dbtype) or the .NET type of the value itself.
-
-### Type mapping table for reading
-
-The following shows the mappings used when reading values.
-
-The return type when using `YdbCommand.ExecuteScalarAsync()`, `YdbDataReader.GetValue()` and similar methods.
-
-| {{ ydb-short-name }} type | .NET type |
-|----------------------------|------------|
-| `Bool` | `bool` |
-| `Text` (synonym `Utf8`) | `string` |
-| `Bytes` (synonym `String`) | `byte[]` |
-| `Uint8` | `byte` |
-| `Uint16` | `ushort` |
-| `Uint32` | `uint` |
-| `Uint64` | `ulong` |
-| `Int8` | `sbyte` |
-| `Int16` | `short` |
-| `Int32` | `int` |
-| `Int64` | `long` |
-| `Float` | `float` |
-| `Double` | `double` |
-| `Date` | `DateTime` |
-| `Datetime` | `DateTime` |
-| `Timestamp` | `DateTime` |
-| `Decimal(22,9)` | `Decimal` |
-| `Json` | `string` |
-| `JsonDocument` | `string` |
-| `Yson` | `byte[]` |
-
-### Type mapping table for writing
-
-| {{ ydb-short-name }} type | DbType | .NET type |
-|----------------------------|-------------------------------------------------------------------------------------------|------------------------------|
-| `Bool` | `Boolean` | `bool` |
-| `Text` (synonym `Utf8`) | `String`, `AnsiString`, `AnsiStringFixedLength`, `StringFixedLength` | `string` |
-| `Bytes` (synonym `String`) | `Binary` | `byte[]` |
-| `Uint8` | `Byte` | `byte` |
-| `Uint16` | `UInt16` | `ushort` |
-| `Uint32` | `UInt32` | `uint` |
-| `Uint64` | `UInt64` | `ulong` |
-| `Int8` | `SByte` | `sbyte` |
-| `Int16` | `Int16` | `short` |
-| `Int32` | `Int32` | `int` |
-| `Int64` | `Int64` | `long` |
-| `Float` | `Single` | `float` |
-| `Double` | `Double` | `double` |
-| `Date` | `Date` | `DateTime` |
-| `Datetime` | `DateTime` | `DateTime` |
-| `Timestamp` | `DateTime2` (for .NET type `DateTime`), `DateTimeOffset` (for .NET type `DateTimeOffset`) | `DateTime`, `DateTimeOffset` |
-| `Decimal(22,9)` | `Decimal`, `Currency` | `decimal` |
-
-It's important to understand that if the `DbType` is not specified, the parameter will be inferred from the `System.Type`.
-
-You can also specify any {{ ydb-short-name }} type using the constructors from `Ydb.Sdk.Value.YdbValue`. For example:
-
-```с#
-var parameter = new YdbParameter("$parameter", YdbValue.MakeJsonDocument("{\"type\": \"jsondoc\"}"));
-```
-
-### Error handling
-
-All exceptions related to database operations are subclasses of `YdbException`.
-
-To safely handle errors that might occur during command execution, you can use a `try-catch` block. Here is an example:
-
-```c#
-try
-{
- await command.ExecuteNonQueryAsync();
-}
-catch (YdbException e)
-{
- Console.WriteLine($"Error executing command: {e}");
-}
-```
-
-### Properties of `YdbException`
-
-The `YdbException` exception has the following properties, which can help you handle errors properly:
-
-- `IsTransient` returns `true` if the error is temporary and can be resolved by retrying. For example, this might occur in cases of a transaction lock violation when the transaction fails to complete its commit.
-
-- `IsTransientWhenIdempotent` returns `true` if the error is temporary and can be resolved by retrying the operation, provided that the database operation is idempotent.
-
-- `StatusCode` contains the database error code, which is helpful for logging and detailed analysis of the issue.
-
-{% note warning %}
-
-Please note that ADO.NET does not automatically retry failed operations, and you must implement retry logic in your code.
-
-{% endnote %}
-
-## Integration of {{ ydb-short-name }} and Dapper
+## Getting started
To get started, you need an additional dependency [Dapper](https://www.nuget.org/packages/Dapper/).
diff --git a/ydb/docs/en/core/reference/languages-and-apis/ado-net/basic-usage.md b/ydb/docs/en/core/reference/languages-and-apis/ado-net/basic-usage.md
new file mode 100644
index 000000000000..46ddbfec0a0f
--- /dev/null
+++ b/ydb/docs/en/core/reference/languages-and-apis/ado-net/basic-usage.md
@@ -0,0 +1,251 @@
+# Basic Usage with ADO.NET
+
+This article covers core [ADO.NET](https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/) usage scenarios for {{ ydb-short-name }}, including database connections, query execution, and result processing. See the main [documentation](index.md) for additional details.
+
+## Connections
+
+A connection to {{ ydb-short-name }} is established using `YdbConnection`.
+
+1. **Using an empty connection**:
+
+ The following code creates a connection with the default settings:
+
+ ```c#
+ await using var ydbConnection = new YdbConnection("");
+ await ydbConnection.OpenAsync();
+ ```
+
+ This option creates a connection to the database at the URL `grpc://localhost:2136/local` with anonymous authentication.
+
+2. **Using the constructor with a connection string**:
+
+ In the following example, a connection is created using a [connection string in ADO.NET](https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/connection-strings):
+
+ ```c#
+ await using var ydbConnection = new YdbConnection(
+ "Host=database-sample-grpc;Port=2135;Database=/root/database-sample");
+ await ydbConnection.OpenAsync();
+ ```
+
+ In this case, the connection is established at the URL `grpc://database-sample-grpc:2135/root/database-sample`. The supported set of settings is explained on the [connection parameters page](connection-parameters.md).
+
+3. **Using the constructor with a `YdbConnectionStringBuilder` argument**:
+
+ The example using `YdbConnectionStringBuilder` is demonstrated in the code below:
+
+ ```c#
+ var ydbConnectionBuilder = new YdbConnectionStringBuilder
+ {
+ Host = "server",
+ Port = 2135,
+ Database = "/ru-prestable/my-table",
+ UseTls = true
+ };
+ await using var ydbConnection = new YdbConnection(ydbConnectionBuilder);
+ await ydbConnection.OpenAsync();
+ ```
+
+ `YdbConnectionStringBuilder` supports additional [configuration](connection-parameters.md#connection-builder-parameters) beyond the connection string, such as logging, advanced authentication options.
+
+## Pooling
+
+Opening and closing a logical connection to {{ ydb-short-name }} is an expensive and time-consuming process. Therefore, connections to {{ ydb-short-name }} are pooled. Closing or disposing of a connection does not close the underlying logical connection; rather, it returns it to a pool managed by `Ydb.Sdk.Ado`. When a connection is needed again, a pooled connection is returned. This makes opening and closing operations extremely fast. Do not hesitate to open and close connections often if necessary, rather than keeping a connection open unnecessarily for a long period of time.
+
+#### ClearPool
+
+Closes idle connections immediately. Active connections close when returned.
+
+```c#
+YdbConnection.ClearPool(ydbConnection)
+```
+
+#### ClearAllPools
+
+Closes all idle connections across all pools. Active connections close on return.
+
+```c#
+YdbConnection.ClearAllPools()
+```
+
+## Data Source
+
+Starting with .NET 7.0, the starting point for any database operation is [DbDataSource](https://learn.microsoft.com/en-us/dotnet/api/system.data.common.dbdatasource).
+
+The simplest way to create a data source is the following:
+
+```c#
+await using var dataSource = new YdbDataSource("Host=localhost;Port=2136;Database=/local");
+```
+
+Or
+
+```c#
+var ydbConnectionBuilder = new YdbConnectionStringBuilder
+{
+ Host = "localhost",
+ Port = 2136,
+ Database = "/local",
+ UseTls = false
+};
+
+await using var dataSource = new YdbDataSource(ydbConnectionBuilder);
+```
+
+## Basic SQL Execution
+
+Once you have a `YdbConnection`, an `YdbCommand` can be used to execute SQL against it:
+
+```c#
+await using var command = dataSource.CreateCommand("SELECT some_field FROM some_table")
+await using var reader = await command.ExecuteReaderAsync();
+
+while (await reader.ReadAsync())
+{
+ Console.WriteLine(reader.GetString(0));
+}
+```
+
+## Other Execution Methods
+
+Above, SQL is executed via [ExecuteReaderAsync](https://learn.microsoft.com/en-us/dotnet/api/system.data.common.dbcommand.executereaderasync). There are various ways to execute a command, depending on the results you expect from it:
+
+1. [ExecuteNonQueryAsync](https://learn.microsoft.com/en-us/dotnet/api/system.data.common.dbcommand.executenonqueryasync): executes SQL that doesn't return any results, typically `INSERT`, `UPDATE`, or `DELETE` statements.
+
+ {% note warning %}
+
+ {{ ydb-short-name }} does not return the number of rows affected.
+
+ {% endnote %}
+
+2. [ExecuteScalarAsync](https://learn.microsoft.com/en-us/dotnet/api/system.data.common.dbcommand.executescalarasync): executes SQL that returns a single scalar value.
+3. [ExecuteReaderAsync](https://learn.microsoft.com/en-us/dotnet/api/system.data.common.dbcommand.executereaderasync): executes SQL that returns a full result set. Returns a `YdbDataReader`, which can be used to access the result set (as in the example above).
+
+For example, to execute a simple SQL `INSERT` that does not return anything, you can use `ExecuteNonQueryAsync` as follows:
+
+```c#
+await using var command = dataSource.CreateCommand("INSERT INTO some_table (some_field) VALUES ('Hello YDB!'u)");
+await command.ExecuteNonQueryAsync();
+```
+
+## Parameters
+
+When sending data values to the database, always consider using parameters rather than including the values in the SQL, as shown in the following example:
+
+```c#
+await using var connection = new YdbConnection(_cmdOptions.SimpleConnectionString);
+await connection.OpenAsync();
+
+var ydbCommand = connection.CreateCommand();
+ydbCommand.CommandText = """
+ DECLARE $series_id AS Uint64;
+ DECLARE $season_id AS Uint64;
+ DECLARE $limit_size AS Uint64;
+
+ SELECT series_id, season_id, episode_id, air_date, title
+ FROM episodes WHERE series_id = $series_id AND season_id > $season_id
+ ORDER BY series_id, season_id, episode_id
+ LIMIT $limit_size;
+ """;
+ydbCommand.Parameters.Add(new YdbParameter("$series_id", DbType.UInt64, 1U));
+ydbCommand.Parameters.Add(new YdbParameter("$season_id", DbType.UInt64, 1U));
+ydbCommand.Parameters.Add(new YdbParameter("$limit_size", DbType.UInt64, 3U));
+
+var ydbDataReader = await ydbCommand.ExecuteReaderAsync();
+```
+
+SQL query parameters can be set using the `YdbParameter` class.
+
+In this example, the parameters `$series_id`, `$season_id`, and `$limit_size` are declared within the SQL query and then added to the command using `YdbParameter` objects.
+
+## Alternative Parameter Style with `@` Prefix
+
+Parameters can also be specified using the `@` prefix. In this case, there is no need to declare variables within the query itself. The query will look like this:
+
+```c#
+ydbCommand.CommandText = """
+ SELECT series_id, season_id, episode_id, air_date, title
+ FROM episodes
+ WHERE series_id = @series_id AND season_id > @season_id
+ ORDER BY series_id, season_id, episode_id
+ LIMIT @limit_size;
+ """;
+ydbCommand.Parameters.Add(new YdbParameter("series_id", DbType.UInt64, 1U));
+ydbCommand.Parameters.Add(new YdbParameter("season_id", DbType.UInt64, 1U));
+ydbCommand.Parameters.Add(new YdbParameter("limit_size", DbType.UInt64, 3U));
+```
+
+With ADO.NET, the query will be prepared for you so that the variables match [YQL](../../yql/reference/index.md). The type will be determined according to the [DbType](https://learn.microsoft.com/en-us/dotnet/api/system.data.dbtype) or the .NET type of the value itself.
+
+## Parameter Types
+
+{{ ydb-short-name }} has a strongly-typed type system: columns and parameters have a type, and types are usually not implicitly converted to other types. This means you have to think about which type you will be sending: trying to insert a string into an integer column (or vice versa) will fail.
+
+For more information on supported types and their mappings, see this [page](type-mapping.md).
+
+## Transactions
+
+To create a client transaction, use the standard ADO.NET `ydbConnection.BeginTransaction()` method.
+
+There are two signatures of this method with a single isolation level parameter:
+
+- `BeginTransaction(TxMode txMode)`
+ The `Ydb.Sdk.Services.Query.TxMode` is a {{ ydb-short-name }} specific isolation level, you can read more about it [here](../../../concepts/transactions.md).
+
+- `BeginTransaction(IsolationLevel isolationLevel)`
+ The `System.Data.IsolationLevel` parameter from the standard ADO.NET. The following isolation levels are supported: `Serializable` and `Unspecified`. Both are equivalent to the `TxMode.SerializableRW`.
+
+Calling `BeginTransaction()` without parameters opens a transaction with level the `TxMode.SerializableRW`.
+
+Consider the following example of using a transaction:
+
+```c#
+await using var connection = await dataSource.OpenConnectionAsync();
+await using var transaction = await connection.BeginTransactionAsync();
+
+await using var command1 = new YdbCommand(connection) { CommandText = "...", Transaction = transaction };
+await command1.ExecuteNonQueryAsync();
+
+await using var command2 = new YdbCommand(connection) { CommandText = "...", Transaction = transaction };
+await command2.ExecuteNonQueryAsync();
+
+await transaction.CommitAsync();
+```
+
+{{ ydb-short-name }} does not support nested or concurrent transactions. At any given moment, only one transaction per connection can be in progress, and starting a new transaction while another is already running throws an exception. Therefore, there is no need to pass the `YdbTransaction` object returned by `BeginTransaction()` to commands you execute. When a transaction is started, all subsequent commands are automatically included until a commit or rollback is made. To ensure maximum portability, however, it is best to set the transaction scope for your commands explicitly.
+
+## Error Handling
+
+All exceptions related to database operations are subclasses of `YdbException`.
+
+To safely handle errors that might occur during command execution, you can use a `try-catch` block. Here is an example:
+
+```c#
+try
+{
+ await command.ExecuteNonQueryAsync();
+}
+catch (YdbException e)
+{
+ Console.WriteLine($"Error executing command: {e}");
+}
+```
+
+### Properties of `YdbException`
+
+The `YdbException` exception has the following properties, which can help you handle errors properly:
+
+- `IsTransient` returns `true` if the error is temporary and can be resolved by retrying. For example, this might occur in cases of a transaction lock violation when the transaction fails to complete its commit.
+
+- `IsTransientWhenIdempotent` returns `true` if the error is temporary and can be resolved by retrying the operation, provided that the database operation is idempotent.
+
+- `StatusCode` contains the database error code, which is helpful for logging and detailed analysis of the issue.
+
+{% note warning %}
+
+Please note that ADO.NET does not automatically retry failed operations, and you must implement retry logic in your code.
+
+{% endnote %}
+
+## Examples
+
+Examples are provided on GitHub at [link](https://github.com/ydb-platform/ydb-dotnet-sdk/tree/main/examples/src/AdoNet).
diff --git a/ydb/docs/en/core/reference/languages-and-apis/ado-net/connection-parameters.md b/ydb/docs/en/core/reference/languages-and-apis/ado-net/connection-parameters.md
new file mode 100644
index 000000000000..7af3f2720801
--- /dev/null
+++ b/ydb/docs/en/core/reference/languages-and-apis/ado-net/connection-parameters.md
@@ -0,0 +1,49 @@
+# ADO.NET Connection Parameters {#connection-parameters}
+
+To connect to a database, the application provides a connection string that specifies parameters such as the host, user, password, and so on. Connection strings have the form `keyword1=value; keyword2=value;`. For more information, [see the official doc page on connection strings](https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/connection-strings).
+
+All available connection parameters are defined as properties in the `YdbConnectionStringBuilder`.
+
+Below are the connection string parameters that `Ydb.Sdk.Ado` supports.
+
+## Basic Connection
+
+| Parameter | Description | Default value |
+|-------------------|------------------------------------------------------------------------------------------------------------|---------------|
+| `Host` | Specifies the {{ ydb-short-name }} server host | `localhost` |
+| `Port` | Specifies the {{ ydb-short-name }} server port | `2136` |
+| `Database` | Specifies the database name | `/local` |
+| `User` | Specifies the username | Not defined |
+| `Password` | Specifies the user password | Not defined |
+
+## Security and Encryption
+
+| Parameter | Description | Default value |
+|-------------------|----------------------------------------------------------------------------------------------------------------------------------------|---------------|
+| `UseTls` | Indicates whether to use the TLS protocol (`grpcs` or `grpc`) | `false` |
+| `RootCertificate` | Specifies the path to the trusted server TLS certificate. If this parameter is set, the `UseTls` parameter will be forced to be `true` | Not defined |
+
+
+## Pooling
+
+| Parameter | Description | Default value |
+|-------------------|-------------------------------------------------------------------------------------------------------------|---------------|
+| `MaxSessionPool` | Specifies the maximum session pool size | `100` |
+
+
+## Keepalive
+
+| Parameter | Description | Default value |
+|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
+| `KeepAlivePingDelay` | The client sends a keep-alive ping to the server if it doesn't receive any frames on a connection for this period of time. This property is used together with `KeepAlivePingTimeout` to check whether the connection is broken. The delay value must be greater than or equal to `1` second. Set to `0` to disable the keep-alive ping | `10` seconds |
+| `KeepAlivePingTimeout` | Keep-alive pings are sent when a period of inactivity exceeds the configured `KeepAlivePingDelay` value. The client closes the connection if it doesn't receive any frames within the timeout. The timeout must be greater than or equal to `1` second. Set to `0` to disable the keep-alive ping timeout | `10` seconds |
+
+## Connection Builder Parameters {#connection-builder-parameters}
+
+There are also additional parameters that do not participate in forming the connection string. These can only be specified using `YdbConnectionStringBuilder`:
+
+| Parameter | Description | Default value |
+|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|
+| `LoggerFactory` | This parameter accepts an instance that implements the [ILoggerFactory](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.iloggerfactory) interface. The `ILoggerFactory` is a standard interface for logging factories in .NET. It is possible to use popular logging frameworks such as [NLog](https://github.com/NLog/NLog), [serilog](https://github.com/serilog/serilog), [log4net](https://github.com/apache/logging-log4net) | `NullLoggerFactory.Instance` |
+| `CredentialsProvider` | An authentication provider that implements the `Ydb.Sdk.Auth.ICredentialsProvider`. Standard ways for authentication:
1) `Ydb.Sdk.Auth.TokenProvider`. Token authentication for OAuth-like tokens.
2) For Yandex Cloud specific authentication methods, consider using **[ydb-dotnet-yc](https://github.com/ydb-platform/ydb-dotnet-yc)** | `Anonymous` |
+| `ServerCertificates` | Specifies custom server certificates used for TLS/SSL validation. This is useful when working with cloud providers (e.g., Yandex Cloud) that use custom root or intermediate certificates not trusted by default | Not defined |
diff --git a/ydb/docs/en/core/reference/languages-and-apis/ado-net/getting-started.md b/ydb/docs/en/core/reference/languages-and-apis/ado-net/getting-started.md
new file mode 100644
index 000000000000..eee6a4cf555d
--- /dev/null
+++ b/ydb/docs/en/core/reference/languages-and-apis/ado-net/getting-started.md
@@ -0,0 +1,37 @@
+# Getting Started with ADO.NET
+
+The best way to use `Ydb.Sdk` is to install its [NuGet package](https://www.nuget.org/packages/Ydb.Sdk).
+
+`Ydb.Sdk.Ado` aims to be fully ADO.NET-compatible; its API should feel almost identical to other .NET database drivers.
+
+Here's a basic code snippet to get you started:
+
+```c#
+await using var connection = new YdbConnection("Host=localhost;Port=2136;Database=/local;MaxSessionPool=50");
+await connection.OpenAsync();
+
+var ydbCommand = connection.CreateCommand();
+ydbCommand.CommandText = """
+ SELECT series_id, season_id, episode_id, air_date, title
+ FROM episodes
+ WHERE series_id = @series_id AND season_id > @season_id
+ ORDER BY series_id, season_id, episode_id
+ LIMIT @limit_size;
+ """;
+ydbCommand.Parameters.Add(new YdbParameter("series_id", DbType.UInt64, 1U));
+ydbCommand.Parameters.Add(new YdbParameter("season_id", DbType.UInt64, 1U));
+ydbCommand.Parameters.Add(new YdbParameter("limit_size", DbType.UInt64, 3U));
+
+var ydbDataReader = await ydbCommand.ExecuteReaderAsync();
+
+_logger.LogInformation("Selected rows:");
+while (await ydbDataReader.ReadAsync())
+{
+ _logger.LogInformation(
+ "series_id: {series_id}, season_id: {season_id}, episode_id: {episode_id}, air_date: {air_date}, title: {title}",
+ ydbDataReader.GetUint64(0), ydbDataReader.GetUint64(1), ydbDataReader.GetUint64(2),
+ ydbDataReader.GetDateTime(3), ydbDataReader.GetString(4));
+}
+```
+
+You can find more info about the ADO.NET API in the [MSDN](https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/ado-net-overview?redirectedfrom=MSDN) docs or in many tutorials on the Internet.
diff --git a/ydb/docs/en/core/reference/languages-and-apis/ado-net/index.md b/ydb/docs/en/core/reference/languages-and-apis/ado-net/index.md
new file mode 100644
index 000000000000..3b4d500d90c2
--- /dev/null
+++ b/ydb/docs/en/core/reference/languages-and-apis/ado-net/index.md
@@ -0,0 +1,13 @@
+# ADO.NET - .NET Access to {{ ydb-short-name }}
+
+`Ydb.Sdk` is an [ADO.NET](https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/) Data Provider for {{ ydb-short-name }}. It allows programs written in C#, Visual Basic, and F# to access the {{ ydb-short-name }} database server. It is implemented in 100% C# code, is free, and is [open source](https://github.com/ydb-platform/ydb-dotnet-sdk).
+
+## Documentation
+
+- [{#T}](getting-started.md)
+- [{#T}](installation.md)
+- [{#T}](basic-usage.md)
+- [{#T}](connection-parameters.md)
+- [{#T}](type-mapping.md)
+- [{#T}](yandex-cloud.md)
+- [{#T}](./../../../integrations/orm/dapper.md)
diff --git a/ydb/docs/en/core/reference/languages-and-apis/ado-net/installation.md b/ydb/docs/en/core/reference/languages-and-apis/ado-net/installation.md
new file mode 100644
index 000000000000..bd24025164d6
--- /dev/null
+++ b/ydb/docs/en/core/reference/languages-and-apis/ado-net/installation.md
@@ -0,0 +1,7 @@
+# Installation ADO.NET
+
+Official releases of `Ydb.Sdk` are always available on [nuget.org](https://www.nuget.org/packages/Ydb.Sdk/). This is the recommended way to use `Ydb.Sdk`.
+
+```bash
+dotnet add package Ydb.Sdk
+```
diff --git a/ydb/docs/en/core/reference/languages-and-apis/ado-net/toc_p.yaml b/ydb/docs/en/core/reference/languages-and-apis/ado-net/toc_p.yaml
new file mode 100644
index 000000000000..892e77dc8383
--- /dev/null
+++ b/ydb/docs/en/core/reference/languages-and-apis/ado-net/toc_p.yaml
@@ -0,0 +1,13 @@
+items:
+- name: Getting Started
+ href: getting-started.md
+- name: Installation
+ href: installation.md
+- name: Basic Usage
+ href: basic-usage.md
+- name: Connection Parameters
+ href: connection-parameters.md
+- name: Type Mapping
+ href: type-mapping.md
+- name: Connect to Yandex Cloud
+ href: yandex-cloud.md
diff --git a/ydb/docs/en/core/reference/languages-and-apis/ado-net/type-mapping.md b/ydb/docs/en/core/reference/languages-and-apis/ado-net/type-mapping.md
new file mode 100644
index 000000000000..df04f9ed6dbb
--- /dev/null
+++ b/ydb/docs/en/core/reference/languages-and-apis/ado-net/type-mapping.md
@@ -0,0 +1,66 @@
+# ADO.NET Supported Types and Their Mappings
+
+The following lists the built-in mappings for reading and writing CLR types to YDB types.
+
+## Type Mapping Table for Reading
+
+The following shows the mappings used when reading values.
+
+These are the return types when using `YdbCommand.ExecuteScalarAsync()`, `YdbDataReader.GetValue()`, and similar methods.
+
+| {{ ydb-short-name }} type | .NET type |
+|-------------------------------|------------|
+| `Bool` | `bool` |
+| `Text` (synonym of `Utf8`) | `string` |
+| `Bytes` (synonym of `String`) | `byte[]` |
+| `Uint8` | `byte` |
+| `Uint16` | `ushort` |
+| `Uint32` | `uint` |
+| `Uint64` | `ulong` |
+| `Int8` | `sbyte` |
+| `Int16` | `short` |
+| `Int32` | `int` |
+| `Int64` | `long` |
+| `Float` | `float` |
+| `Double` | `double` |
+| `Date` | `DateTime` |
+| `Datetime` | `DateTime` |
+| `Timestamp` | `DateTime` |
+| `Decimal(22,9)` | `Decimal` |
+| `Json` | `string` |
+| `JsonDocument` | `string` |
+| `Yson` | `byte[]` |
+
+## Type Mapping Table for Writing
+
+| {{ ydb-short-name }} type | DbType | .NET type |
+|-------------------------------|-------------------------------------------------------------------------------------------|------------------------------|
+| `Bool` | `Boolean` | `bool` |
+| `Text` (synonym of `Utf8`) | `String`, `AnsiString`, `AnsiStringFixedLength`, `StringFixedLength` | `string` |
+| `Bytes` (synonym of `String`) | `Binary` | `byte[]` |
+| `Uint8` | `Byte` | `byte` |
+| `Uint16` | `UInt16` | `ushort` |
+| `Uint32` | `UInt32` | `uint` |
+| `Uint64` | `UInt64` | `ulong` |
+| `Int8` | `SByte` | `sbyte` |
+| `Int16` | `Int16` | `short` |
+| `Int32` | `Int32` | `int` |
+| `Int64` | `Int64` | `long` |
+| `Float` | `Single` | `float` |
+| `Double` | `Double` | `double` |
+| `Date` | `Date` | `DateTime` |
+| `Datetime` | `DateTime` | `DateTime` |
+| `Timestamp` | `DateTime2` (for .NET type `DateTime`), `DateTimeOffset` (for .NET type `DateTimeOffset`) | `DateTime`, `DateTimeOffset` |
+| `Decimal(22,9)` | `Decimal`, `Currency` | `decimal` |
+
+{% note info %}
+
+It's important to understand that if the `DbType` is not specified, the parameter will be inferred from the `System.Type`.
+
+{% endnote %}
+
+You can also specify any {{ ydb-short-name }} type using the constructors from `Ydb.Sdk.Value.YdbValue`. For example:
+
+```с#
+var parameter = new YdbParameter("$parameter", YdbValue.MakeJsonDocument("{\"type\": \"jsondoc\"}"));
+```
diff --git a/ydb/docs/en/core/reference/languages-and-apis/ado-net/yandex-cloud.md b/ydb/docs/en/core/reference/languages-and-apis/ado-net/yandex-cloud.md
new file mode 100644
index 000000000000..0a13ea9f42de
--- /dev/null
+++ b/ydb/docs/en/core/reference/languages-and-apis/ado-net/yandex-cloud.md
@@ -0,0 +1,57 @@
+# Connection ADO.NET to Yandex Cloud
+
+## Installation
+
+To use [Yandex Cloud](https://yandex.cloud/en) authentication in your .NET application, install the `Ydb.Sdk.Yc.Auth` [NuGet package](https://www.nuget.org/packages/Ydb.Sdk.Yc.Auth/):
+
+```bash
+dotnet add package Ydb.Sdk.Yc.Auth
+```
+
+This package provides the necessary tools for authenticating with Yandex Cloud services.
+
+## Authentication
+
+Supported Yandex.Cloud authentication methods:
+
+- `Ydb.Sdk.Yc.ServiceAccountProvider`. [Service account](https://yandex.cloud/en/docs/iam/concepts/users/service-account) authentication, sample usage:
+
+ ```c#
+ var saProvider = new ServiceAccountProvider(
+ saFilePath: file, // Path to file with service account JSON info
+ loggerFactory: loggerFactory
+ );
+ ```
+
+- `Ydb.Sdk.Yc.MetadataProvider`. [Metadata service](https://yandex.cloud/en/docs/compute/operations/vm-connect/auth-inside-vm) authentication, works inside Yandex Cloud VMs and Cloud Functions. Sample usage:
+
+ ```c#
+ var metadataProvider = new MetadataProvider(loggerFactory: loggerFactory);
+ ```
+
+## Certificates
+
+The library includes default Yandex Cloud server certificates, which are required for connectivity with dedicated {{ ydb-short-name }} databases:
+
+```c#
+var certs = Ydb.Sdk.Yc.YcCerts.GetYcServerCertificates();
+```
+
+## How to Connect with ADO.NET
+
+To establish a secure connection to {{ ydb-short-name }} using ADO.NET, configure `YdbConnectionStringBuilder` with the required authentication and TLS settings. Below is a detailed example:
+
+```c#
+var builder = new YdbConnectionStringBuilder
+{
+ // More settings ...
+ UseTls = true,
+ Port = 2135,
+ CredentialsProvider = saProvider, // For service account
+ ServerCertificates = YcCerts.GetYcServerCertificates() // custom certificates Yandex Cloud
+};
+```
+
+## Example
+
+[ADO.NET connect to Yandex Cloud](https://github.com/ydb-platform/ydb-dotnet-sdk/tree/main/examples/src/YC)
diff --git a/ydb/docs/en/core/reference/languages-and-apis/index.md b/ydb/docs/en/core/reference/languages-and-apis/index.md
index c23d79d50395..854ba019af11 100644
--- a/ydb/docs/en/core/reference/languages-and-apis/index.md
+++ b/ydb/docs/en/core/reference/languages-and-apis/index.md
@@ -1,3 +1,4 @@
# Languages and APIs
-- [{#T}](jdbc-driver/index.md)
\ No newline at end of file
+- [{#T}](jdbc-driver/index.md)
+- [{#T}](ado-net/index.md)
\ No newline at end of file
diff --git a/ydb/docs/en/core/reference/languages-and-apis/toc_p.yaml b/ydb/docs/en/core/reference/languages-and-apis/toc_p.yaml
index b8085867dbb4..7e5bb805d689 100644
--- a/ydb/docs/en/core/reference/languages-and-apis/toc_p.yaml
+++ b/ydb/docs/en/core/reference/languages-and-apis/toc_p.yaml
@@ -4,4 +4,8 @@ items:
include:
mode: link
path: jdbc-driver/toc_p.yaml
-
+- name: ADO.NET
+ href: ado-net/index.md
+ include:
+ mode: link
+ path: ado-net/toc_p.yaml
diff --git a/ydb/docs/ru/core/integrations/orm/dapper.md b/ydb/docs/ru/core/integrations/orm/dapper.md
index 4773c283e961..eba7d579f0b9 100644
--- a/ydb/docs/ru/core/integrations/orm/dapper.md
+++ b/ydb/docs/ru/core/integrations/orm/dapper.md
@@ -1,293 +1,6 @@
# Использование Dapper
-[Dapper](https://www.learndapper.com/) - это микро ORM (Object Relational Mapping), который предоставляет простой и гибкий способ для взаимодействия с базами данных. Он работает на основе стандарта ADO.NET и предлагает множество функций, которые облегчают работу с базой данных.
-
-## ADO.NET
-
-ADO.NET — это набор классов, предоставляющих доступ к данным для разработчиков, использующих платформу .NET Framework.
-
-YDB SDK C# поставляет набор классов реализующих стандарт ADO.NET.
-
-### Установка {#install}
-
-Реализация ADO.NET для YDB доступен через [NuGet](https://www.nuget.org/packages/Ydb.Sdk/).
-
-```dotnet
-dotnet add package Ydb.Sdk
-```
-
-### Создание подключения
-
-Подключение к YDB устанавливается через YdbConnection.
-
-1. **Использование конструктора без параметров**:
-
- Следующий код создаёт подключение с настройками по умолчанию:
-
- ```c#
- await using var ydbConnection = new YdbConnection();
- await ydbConnection.OpenAsync();
- ```
-
- Этот вариант создаёт подключение к базе данных по URL: `grpc://localhost:2136/local`, с анонимной аутентификацией.
-
-2. **Использование конструктора со строкой подключения**:
-
- В следующем примере происходит создание подключения при помощи [строки подключения в ADO.NET](https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/connection-strings):
-
- ```C#
- await using var ydbConnection = new YdbConnection(
- "Host=database-sample-grpc;Port=2135;Database=/root/database-sample");
- await ydbConnection.OpenAsync();
- ```
-
- В данном случае подключение будет установлено по URL: `grpc://database-sample-grpc:2135/root/database-sample`. При использовании метода со строкой подключения параметры задаются в виде пар ключ=значение, разделённые точкой с запятой (`key1=value1;key2=value2`). Набор ключей имеет фиксированные значения, которые будут детально рассмотрены в следующих разделах.
-
-3. **Использование конструктора с аргументом `YdbConnectionStringBuilder`**:
-
- Вариант с использованием `YdbConnectionStringBuilder` демонстрируется в коде ниже:
-
- ```c#
- var ydbConnectionBuilder = new YdbConnectionStringBuilder
- {
- Host = "server",
- Port = 2135,
- Database = "/ru-prestable/my-table",
- UseTls = true
- };
- await using var ydbConnection = new YdbConnection(ydbConnectionBuilder);
- await ydbConnection.OpenAsync();
- ```
-
-### Параметры подключения
-
-Все доступные параметры подключения определены как `property` в классе `YdbConnectionStringBuilder`.
-
-Вот список параметров, которые можно задать в строке подключения `ConnectionString`:
-
-| Параметр | Описание | Значение по умолчанию |
-|-------------------|------------------------------------------------------------------------------------------------------|-----------------------|
-| `Host` | Указывает хост сервера | `localhost` |
-| `Port` | Определяет порт сервера | `2136` |
-| `Database` | Задаёт путь к базе данных | `/local` |
-| `User` | Значение задаёт имя пользователя | Не определено |
-| `Password` | Данный параметр задаёт пароль пользователя | Не определено |
-| `UseTls` | Определяет, следует ли использовать протокол TLS (`grpc` или `grpcs`) | `false` |
-| `MaxSessionPool` | Максимальное количество размер пула сессий | `100` |
-| `RootCertificate` | Задаёт путь к доверенному сертификату сервера. Если этот параметр установлен, то UseTls будет `true` | Не определено |
-
-Существуют также и дополнительные параметры, которые не участвуют при формировании строки `ConnectionString`, их можно указать только используя `YdbConnectionStringBuilder`:
-
-| Параметр | Описание | Значение по умолчанию |
-|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|
-| `LoggerFactory` | Этот параметр принимает экземпляр, который реализует интерфейс [ILoggerFactory](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.iloggerfactory). `ILoggerFactory` - это стандартный интерфейс для фабрик логирования в .NET. Возможно использование популярных фреймворков, таких как [NLog](https://github.com/NLog/NLog), [serilog](https://github.com/serilog/serilog), [log4net](https://github.com/apache/logging-log4net) | `NullLoggerFactory.Instance` |
-| `CredentialsProvider` | Провайдер аутентификации, который реализует интерфейс `Ydb.Sdk.Auth.ICredentialsProvider`. [YDB SDK](#install) представляет несколько стандартных способов аутентификации:
1) `Ydb.Sdk.Auth.AnonymousProvider`. Анонимный доступ к YDB, в основном для целей тестирования.
2) `Ydb.Sdk.Auth.TokenProvider`. Аутентификация по токену, подобных OAuth.
3) `Ydb.Sdk.Auth.StaticCredentialsProvider`. Аутентификация на основе имени пользователя и пароля.
Для Yandex.Cloud используете **[ydb-dotnet-yc](https://github.com/ydb-platform/ydb-dotnet-yc)** | `AnonymousProvider` |
-
-### Использование
-
-Выполнение запросов осуществляется через объект `YdbCommand`:
-
-```c#
-await using var ydbConnection = new YdbConnection();
-await ydbConnection.OpenAsync();
-
-var ydbCommand = ydbConnection.CreateCommand();
-ydbCommand.CommandText = "SELECT 'Hello world!'u";
-Console.WriteLine(await ydbCommand.ExecuteScalarAsync());
-```
-
-Этот пример демонстрирует вывод в консоль `Hello world!`.
-
-### Пользовательские транзакции
-
-Для создания клиентской транзакции используйте метод `ydbConnection.BeginTransaction()`.
-
-Есть две сигнатуры этого метода с единственным параметром уровня изоляции:
-
-- `BeginTransaction(TxMode txMode)`
- Параметр `Ydb.Sdk.Services.Query.TxMode` - это {{ ydb-short-name }} специфичный уровень изоляции, ознакомиться поподробнее можно [здесь](../../concepts/transactions.md).
-
-- `BeginTransaction(IsolationLevel isolationLevel)`
- Параметр `System.Data.IsolationLevel` из стандарта ADO.NET. Поддерживаются следующие уровни изоляции: `Serializable` и `Unspecified`. Оба эквивалентны параметру `TxMode.SerializableRW`.
-
-Вызов `BeginTransaction()` без параметров открывает транзакцию с уровнем `TxMode.SerializableRW`.
-
-Рассмотрим пример использования транзакции:
-
-```c#
-await using var ydbConnection = new YdbConnection();
-await ydbConnection.OpenAsync();
-
-var ydbCommand = ydbConnection.CreateCommand();
-
-ydbCommand.Transaction = ydbConnection.BeginTransaction();
-ydbCommand.CommandText = """
- UPSERT INTO episodes (series_id, season_id, episode_id, title, air_date)
- VALUES (2, 5, 13, "Test Episode", Date("2018-08-27"))
- """;
-await ydbCommand.ExecuteNonQueryAsync();
-
-ydbCommand.CommandText = """
- INSERT INTO episodes(series_id, season_id, episode_id, title, air_date)
- VALUES
- (2, 5, 21, "Test 21", Date("2018-08-27")),
- (2, 5, 22, "Test 22", Date("2018-08-27"))
- """;
-await ydbCommand.ExecuteNonQueryAsync();
-await ydbCommand.Transaction.CommitAsync();
-```
-
-Здесь открывается транзакция уровня `Serializable` и происходит две ставки в таблицу `episodes`.
-
-### Использование параметров
-
-Параметры YQL-запроса можно задать с помощью класса `YdbParameter`:
-
-```c#
-await using var connection = new YdbConnection(_cmdOptions.SimpleConnectionString);
-await connection.OpenAsync();
-
-var ydbCommand = connection.CreateCommand();
-ydbCommand.CommandText = """
- DECLARE $series_id AS Uint64;
- DECLARE $season_id AS Uint64;
- DECLARE $limit_size AS Uint64;
-
- SELECT series_id, season_id, episode_id, air_date, title
- FROM episodes WHERE series_id = $series_id AND season_id > $season_id
- ORDER BY $series_id, $season_id, $episode_id
- LIMIT $limit_size;
- """;
-ydbCommand.Parameters.Add(new YdbParameter("$series_id", DbType.UInt64, 1U));
-ydbCommand.Parameters.Add(new YdbParameter("$season_id", DbType.UInt64, 1U));
-ydbCommand.Parameters.Add(new YdbParameter("$limit_size", DbType.UInt64, 3U));
-
-var ydbDataReader = await ydbCommand.ExecuteReaderAsync();
-
-_logger.LogInformation("Selected rows:");
-while (await ydbDataReader.ReadAsync())
-{
- _logger.LogInformation(
- "series_id: {series_id}, season_id: {season_id}, episode_id: {episode_id}, air_date: {air_date}, title: {title}",
- ydbDataReader.GetUint64(0), ydbDataReader.GetUint64(1), ydbDataReader.GetUint64(2),
- ydbDataReader.GetDateTime(3), ydbDataReader.GetString(4));
-}
-```
-
-В этом примере мы объявляем параметры `series_id`, `season_id` и `limit_size` внутри YQL-запроса и затем добавляем их в команду с помощью `YdbParameter` объектов.
-
-### Альтернативный стиль с префиксом @
-
-Параметры также можно указывать с использованием префикса `@`. В этом случае не требуется предварительное объявление переменных в самом запросе. Запрос будет выглядеть следующим образом:
-
-```c#
-ydbCommand.CommandText = """
- SELECT series_id, season_id, episode_id, air_date, title
- FROM episodes
- WHERE series_id = @series_id AND season_id > @season_id
- ORDER BY series_id, season_id, episode_id
- LIMIT @limit_size;
- """;
-ydbCommand.Parameters.Add(new YdbParameter("$series_id", DbType.UInt64, 1U));
-ydbCommand.Parameters.Add(new YdbParameter("$season_id", DbType.UInt64, 1U));
-ydbCommand.Parameters.Add(new YdbParameter("$limit_size", DbType.UInt64, 3U));
-```
-
-ADO.NET за вас подготовит запрос, чтобы переменные соответствовали [YQL](../../yql/reference/index.md). А тип будет определен согласно [DbType](https://learn.microsoft.com/en-us/dotnet/api/system.data.dbtype) или .NET тип самого значения.
-
-### Таблица сопоставления типов на чтение
-
-Ниже показаны сопоставления, используемые при чтении значений.
-
-Возвращаемый тип при использовании `YdbCommand.ExecuteScalarAsync()`, `YdbDataReader.GetValue()` и подобные методы.
-
-| {{ ydb-short-name }} type | .NET type |
-|----------------------------|------------|
-| `Bool` | `bool` |
-| `Text` (synonym `Utf8`) | `string` |
-| `Bytes` (synonym `String`) | `byte[]` |
-| `Uint8` | `byte` |
-| `Uint16` | `ushort` |
-| `Uint32` | `uint` |
-| `Uint64` | `ulong` |
-| `Int8` | `sbyte` |
-| `Int16` | `short` |
-| `Int32` | `int` |
-| `Int64` | `long` |
-| `Float` | `float` |
-| `Double` | `double` |
-| `Date` | `DateTime` |
-| `Datetime` | `DateTime` |
-| `Timestamp` | `DateTime` |
-| `Decimal(22,9)` | `Decimal` |
-| `Json` | `string` |
-| `JsonDocument` | `string` |
-| `Yson` | `byte[]` |
-
-### Таблица сопоставления типов на запись
-
-| {{ ydb-short-name }} | DbType | .Net types |
-|----------------------------|-------------------------------------------------------------------------------------------|------------------------------|
-| `Bool` | `Boolean` | `bool` |
-| `Text` (синоним `Utf8`) | `String`, `AnsiString`, `AnsiStringFixedLength`, `StringFixedLength` | `string` |
-| `Bytes` (синоним `String`) | `Binary` | `byte[]` |
-| `Uint8` | `Byte` | `byte` |
-| `Uint16` | `UInt16` | `ushort` |
-| `Uint32` | `UInt32` | `uint` |
-| `Uint64` | `UInt64` | `ulong` |
-| `Int8` | `SByte` | `sbyte` |
-| `Int16` | `Int16` | `short` |
-| `Int32` | `Int32` | `int` |
-| `Int64` | `Int64` | `long` |
-| `Float` | `Single` | `float` |
-| `Double` | `Double` | `double` |
-| `Date` | `Date` | `DateTime` |
-| `Datetime` | `DateTime` | `DateTime` |
-| `Timestamp` | `DateTime2` (для .NET типа `DateTime`), `DateTimeOffset` (для .NET типа `DateTimeOffset`) | `DateTime`, `DateTimeOffset` |
-| `Decimal(22,9)` | `Decimal`, `Currency` | `decimal` |
-
-Важно понимать, что если `DbType` не указан, параметр будет вычислен из `System.Type`.
-
-Также вы можете указывать любой {{ ydb-short-name }} тип, используя конструкторы из `Ydb.Sdk.Value.YdbValue`. Например:
-
-```с#
-var parameter = new YdbParameter("$parameter", YdbValue.MakeJsonDocument("{\"type\": \"jsondoc\"}"));
-```
-
-### Обработка ошибок
-
-Все исключения, связанные с операциями в базе данных, являются подклассами `YdbException`.
-
-Для безопасной обработки ошибок, которые могут возникнуть при выполнении команд, вы можете использовать блок `try-catch`. Пример:
-
-```c#
-try
-{
- await command.ExecuteNonQueryAsync();
-}
-catch (YdbException e)
-{
- Console.WriteLine($"Error executing command: {e}");
-}
-```
-
-### Свойства исключения `YdbException`
-
-Исключение `YdbException` содержит следующие свойства, которые помогут вам более точно обработать ошибку:
-
-- `IsTransient`: Возвращает true, если ошибка временная и может быть устранена повторной попыткой. Например, такая ошибка может возникнуть в случае нарушения блокировки транзакции, когда транзакция не успела завершить коммит.
-
-- `IsTransientWhenIdempotent`: Возвращает true, если ошибка временная и может быть устранена в случае повтора операции, при условии, что операция с базой данных является идемпотентной.
-
-- `StatusCode`: Содержит код ошибки базы данных, который может быть полезен для логирования и детального анализа проблемы.
-
-{% note warning %}
-
-Обратите внимание, что ADO.NET не выполняет автоматических попыток повторения, и вам нужно реализовать повтор попытки в своем коде.
-
-{% endnote %}
-
-## Интеграция YDB и Dapper
+[Dapper](https://www.learndapper.com/) - это микро ORM (Object Relational Mapping), который предоставляет простой и гибкий способ для взаимодействия с базами данных. Он работает на основе стандарта [ADO.NET](../../reference/languages-and-apis/ado-net/index.md) и предлагает множество функций, которые облегчают работу с базой данных.
Чтобы начать работу требуется дополнительная зависимость [Dapper](https://www.nuget.org/packages/Dapper/).
diff --git a/ydb/docs/ru/core/reference/languages-and-apis/ado-net/basic-usage.md b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/basic-usage.md
new file mode 100644
index 000000000000..eba9957b40ea
--- /dev/null
+++ b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/basic-usage.md
@@ -0,0 +1,251 @@
+# Основное использование ADO.NET
+
+В этой статье рассматриваются основные сценарии использования ADO.NET c YDB, включая подключение к базе данных, выполнение запросов и обработку результатов. Дополнительные сведения см. в основной [документации](index.md).
+
+## Подключения
+
+Подключение к {{ ydb-short-name }} устанавливается через `YdbConnection`.
+
+1. **Использование пустой строки подключения**:
+
+ Следующий код создаёт подключение с настройками по умолчанию:
+
+ ```c#
+ await using var ydbConnection = new YdbConnection("");
+ await ydbConnection.OpenAsync();
+ ```
+
+ Этот вариант создаёт подключение к базе данных по URL: `grpc://localhost:2136/local`, с анонимной аутентификацией.
+
+2. **Использование конструктора со строкой подключения**:
+
+ В следующем примере происходит создание подключения при помощи [строки подключения в ADO.NET](https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/connection-strings):
+
+ ```c#
+ await using var ydbConnection = new YdbConnection(
+ "Host=database-sample-grpc;Port=2135;Database=/root/database-sample");
+ await ydbConnection.OpenAsync();
+ ```
+
+ В данном случае подключение будет установлено по URL: `grpc://database-sample-grpc:2135/root/database-sample`. Поддерживаемый набор настроек описан на [странице параметров подключения](connection-parameters.md).
+
+3. **Использование конструктора с аргументом `YdbConnectionStringBuilder`**:
+
+ Вариант с использованием `YdbConnectionStringBuilder` демонстрируется в коде ниже:
+
+ ```c#
+ var ydbConnectionBuilder = new YdbConnectionStringBuilder
+ {
+ Host = "server",
+ Port = 2135,
+ Database = "/ru-prestable/my-table",
+ UseTls = true
+ };
+ await using var ydbConnection = new YdbConnection(ydbConnectionBuilder);
+ await ydbConnection.OpenAsync();
+ ```
+
+ `YdbConnectionStringBuilder` поддерживает дополнительные [настройки](connection-parameters.md#connection-builder-parameters), помимо строки подключения, такие как логирование, расширенные параметры аутентификации.
+
+## Pooling
+
+Открытие и закрытие логического соединения с {{ ydb-short-name }} является дорогостоящим и трудоемким процессом. Поэтому соединения с {{ ydb-short-name }} объединяются в пул. Закрытие или удаление соединения не проводит к закрытию основного логического соединения; скорее, она возвращается в пул, управляемый `Ydb.Sdk.Ado`. Когда соединение снова понадобится, будет возвращено соединение из пула. Это делает операции открытия и закрытия быстрыми. Не стесняйтесь часто открывать и закрывать соединения, если это необходимо, вместо того, чтобы без необходимости поддерживать соединение открытым в течении длительного периода времени.
+
+#### ClearPool
+
+Немедленно закрывает незанятые соединения. Активные соединения закрываются при возврате.
+
+```c#
+YdbConnection.ClearPool(ydbConnection)
+```
+
+#### ClearAllPools
+
+Закрывает все незанятые соединения во всех пулах. Активные соединения закрываются при возврате.
+
+```c#
+YdbConnection.ClearAllPools()
+```
+
+## Data Source
+
+Начиная с .NET 7.0, отправной точкой для любой операции с базой данных является [DbDataSource](https://learn.microsoft.com/en-us/dotnet/api/system.data.common.dbdatasource).
+
+Самый простой способ создать источник данных заключается в следующем:
+
+```c#
+await using var dataSource = new YdbDataSource("Host=localhost;Port=2136;Database=/local");
+```
+
+Или
+
+```c#
+var ydbConnectionBuilder = new YdbConnectionStringBuilder
+{
+ Host = "localhost",
+ Port = 2136,
+ Database = "/local",
+ UseTls = false
+};
+
+await using var dataSource = new YdbDataSource(ydbConnectionBuilder);
+```
+
+## Базовое выполнение SQL
+
+Как только у вас есть `YdbConnection`, для выполнения SQL-запроса можно использовать `YdbCommand`:
+
+```c#
+await using var command = dataSource.CreateCommand("SELECT some_field FROM some_table")
+await using var reader = await command.ExecuteReaderAsync();
+
+while (await reader.ReadAsync())
+{
+ Console.WriteLine(reader.GetString(0));
+}
+```
+
+## Другие методы выполнения
+
+Выше мы выполнили SQL с помощью [ExecuteReaderAsync](https://learn.microsoft.com/ru-ru/dotnet/api/system.data.common.dbcommand.executereaderasync). Существуют различные способы выполнения команды, в зависимости от того, каких результатов вы от нее ожидаете:
+
+1. [ExecuteNonQueryAsync](https://learn.microsoft.com/ru-ru/dotnet/api/system.data.common.dbcommand.executenonqueryasync): выполняет SQL, который не возвращает никаких результатов, обычно это инструкции `INSERT`, `UPDATE` или `DELETE`.
+
+ {% note warning %}
+
+ {{ ydb-short-name }} не возвращает количество затронутых строк.
+
+ {% endnote %}
+
+2. [ExecuteScalarAsync](https://learn.microsoft.com/ru-ru/dotnet/api/system.data.common.dbcommand.executescalarasync): выполняет SQL, который возвращает единственное скалярное значение.
+3. [ExecuteReaderAsync](https://learn.microsoft.com/ru-ru/dotnet/api/system.data.common.dbcommand.executereaderasync): выполняет SQL, который вернет полный результирующий набор. Возвращает `YdbDataReader`, который можно использовать для доступа к результирующему набору (как в приведенном выше примере).
+
+Например, чтобы выполнить простой SQL `INSERT`, который ничего не возвращает, вы можете использовать ExecuteNonQueryAsync следующим образом:
+
+```c#
+await using var command = dataSource.CreateCommand("INSERT INTO some_table (some_field) VALUES ('Hello YDB!'u)");
+await command.ExecuteNonQueryAsync();
+```
+
+## Параметры
+
+При отправке пользовательских данных в базу данных всегда рекомендуется использовать параметры, а не включать значения в SQL следующим образом:
+
+```c#
+await using var connection = new YdbConnection(_cmdOptions.SimpleConnectionString);
+await connection.OpenAsync();
+
+var ydbCommand = connection.CreateCommand();
+ydbCommand.CommandText = """
+ DECLARE $series_id AS Uint64;
+ DECLARE $season_id AS Uint64;
+ DECLARE $limit_size AS Uint64;
+
+ SELECT series_id, season_id, episode_id, air_date, title
+ FROM episodes WHERE series_id = $series_id AND season_id > $season_id
+ ORDER BY series_id, season_id, episode_id
+ LIMIT $limit_size;
+ """;
+ydbCommand.Parameters.Add(new YdbParameter("$series_id", DbType.UInt64, 1U));
+ydbCommand.Parameters.Add(new YdbParameter("$season_id", DbType.UInt64, 1U));
+ydbCommand.Parameters.Add(new YdbParameter("$limit_size", DbType.UInt64, 3U));
+
+var ydbDataReader = await ydbCommand.ExecuteReaderAsync();
+```
+
+Параметры SQL-запроса можно задать с помощью класса `YdbParameter`.
+
+В этом примере параметры `$series_id`, `$season_id` и `$limit_size` объявляются в SQL-запросе и затем добавляются в команду с помощью объектов `YdbParameter`.
+
+## Альтернативный стиль параметра с префиксом `@`
+
+Параметры также можно указывать с использованием префикса `@`. В этом случае не требуется предварительное объявление переменных в самом запросе. Запрос будет выглядеть следующим образом:
+
+```c#
+ydbCommand.CommandText = """
+ SELECT series_id, season_id, episode_id, air_date, title
+ FROM episodes
+ WHERE series_id = @series_id AND season_id > @season_id
+ ORDER BY series_id, season_id, episode_id
+ LIMIT @limit_size;
+ """;
+ydbCommand.Parameters.Add(new YdbParameter("series_id", DbType.UInt64, 1U));
+ydbCommand.Parameters.Add(new YdbParameter("season_id", DbType.UInt64, 1U));
+ydbCommand.Parameters.Add(new YdbParameter("limit_size", DbType.UInt64, 3U));
+```
+
+ADO.NET за вас подготовит запрос, чтобы переменные соответствовали [YQL](../../../yql/reference/index.md). А тип будет определен согласно [DbType](https://learn.microsoft.com/en-us/dotnet/api/system.data.dbtype) или .NET тип самого значения.
+
+## Parameter types
+
+{{ ydb-short-name }} имеет строго типизированную систему типов: столбцы и параметры имеют тип, а типы обычно не преобразуются неявным образом в другие типы. Это означает, что вам нужно подумать о том, какой тип вы будете отправлять: попытка вставить строку в целочисленный столбец (или наоборот) приведет к сбою.
+
+Для получения дополнительной информации о поддерживаемых типах и их сопоставления смотрите эту [страницу](type-mapping.md).
+
+## Транзакции
+
+Чтобы создать клиентскую транзакцию, используйте стандартный метод ADO.NET `ydbConnection.BeginTransaction()`.
+
+Есть две сигнатуры этого метода с единственным параметром уровня изоляции:
+
+- `BeginTransaction(TxMode txMode)`
+ Параметр `Ydb.Sdk.Services.Query.TxMode` - это {{ ydb-short-name }} специфичный уровень изоляции, ознакомиться поподробнее можно [здесь](../../../concepts/transactions.md).
+
+- `BeginTransaction(IsolationLevel isolationLevel)`
+ Параметр `System.Data.IsolationLevel` из стандарта ADO.NET. Поддерживаются следующие уровни изоляции: `Serializable` и `Unspecified`. Оба эквивалентны параметру `TxMode.SerializableRW`.
+
+Вызов `BeginTransaction()` без параметров открывает транзакцию с уровнем `TxMode.SerializableRW`.
+
+Рассмотрим пример использования транзакции:
+
+```c#
+await using var connection = await dataSource.OpenConnectionAsync();
+await using var transaction = await connection.BeginTransactionAsync();
+
+await using var command1 = new YdbCommand(connection) { CommandText = "...", Transaction = transaction };
+await command1.ExecuteNonQueryAsync();
+
+await using var command2 = new YdbCommand(connection) { CommandText = "...", Transaction = transaction };
+await command2.ExecuteNonQueryAsync();
+
+await transaction.CommitAsync();
+```
+
+{{ ydb-short-name }} не поддерживает вложенные или параллельные транзакции. В любой момент времени может выполняться только одна транзакция, и при запуске новой транзакции, в то время как другая уже выполняется, возникает исключение. Следовательно, нет необходимости передавать объект `YdbTransaction`, возвращаемый функцией `BeginTransaction()` в команды, которые вы выполняете. При запуске транзакции все последующие команды автоматически включаются до тех пор, пока не будет выполнена фиксация или откат. Однако для обеспечения максимальной переносимости лучше всего явно задать область транзакции для ваших команд.
+
+## Обработка ошибок
+
+Все исключения, связанные с операциями в базе данных, являются подклассами `YdbException`.
+
+Для безопасной обработки ошибок, которые могут возникнуть при выполнении команд, вы можете использовать блок `try-catch`. Пример:
+
+```c#
+try
+{
+ await command.ExecuteNonQueryAsync();
+}
+catch (YdbException e)
+{
+ Console.WriteLine($"Error executing command: {e}");
+}
+```
+
+### Свойства исключения `YdbException`
+
+Исключение `YdbException` содержит следующие свойства, которые помогут вам более точно обработать ошибку:
+
+- `IsTransient`: Возвращает true, если ошибка временная и может быть устранена повторной попыткой. Например, такая ошибка может возникнуть в случае нарушения блокировки транзакции, когда транзакция не успела завершить коммит.
+
+- `IsTransientWhenIdempotent`: Возвращает true, если ошибка временная и может быть устранена в случае повтора операции, при условии, что операция с базой данных является идемпотентной.
+
+- `StatusCode`: Содержит код ошибки базы данных, который может быть полезен для логирования и детального анализа проблемы.
+
+{% note warning %}
+
+Обратите внимание, что ADO.NET не выполняет автоматических попыток повторения, и вам нужно реализовать повтор попытки в своем коде.
+
+{% endnote %}
+
+## Примеры
+
+Примеры приведены на GitHub по [ссылке](https://github.com/ydb-platform/ydb-dotnet-sdk/tree/main/examples/src/AdoNet).
diff --git a/ydb/docs/ru/core/reference/languages-and-apis/ado-net/connection-parameters.md b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/connection-parameters.md
new file mode 100644
index 000000000000..cb15f0d9eaac
--- /dev/null
+++ b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/connection-parameters.md
@@ -0,0 +1,49 @@
+# Параметры подключения ADO.NET {#connection-parameters}
+
+Для подключения к базе данных приложение предоставляет строку подключения, в которой указываются такие параметры, как хост, пользователь, пароль и т.д. Строки подключения имеют вид `keyword1=value; keyword2=value;`. Для получения дополнительной информации [смотрите официальную страницу документации о строках подключения](https://learn.microsoft.com/ru-ru/dotnet/framework/data/adonet/connection-strings).
+
+Все доступные параметры подключения определены как свойства в `YdbConnectionStringBuilder`.
+
+Ниже приведены параметры строки подключения, которые ожидает `Ydb.Sdk.Ado`.
+
+## Базовые параметры подключения
+
+| Параметр | Описание | Значение по умолчанию |
+|------------|----------------------------------------------|-----------------------|
+| `Host` | Указывает хост {{ ydb-short-name }} сервера | `localhost` |
+| `Port` | Определяет порт {{ ydb-short-name }} сервера | `2136` |
+| `Database` | Задаёт путь к базе данных | `/local` |
+| `User` | Значение задаёт имя пользователя | Не определено |
+| `Password` | Данный параметр задаёт пароль пользователя | Не определено |
+
+## Безопасность и шифрование
+
+| Параметр | Описание | Значение по умолчанию |
+|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|
+| `UseTls` | Определяет, следует ли использовать протокол TLS (`grpc` или `grpcs`) | `false` |
+| `RootCertificate` | Задаёт путь к доверенному сертификату сервера. Если этот параметр установлен, параметру `UseTls` принудительно присваивается значение `true`. | Не определено |
+
+
+## Pooling
+
+| Параметр | Описание | Значение по умолчанию |
+|------------------|-------------------------------------------|-----------------------|
+| `MaxSessionPool` | Указывает максимальный размер пула сессий | `100` |
+
+
+## Keepalive
+
+| Параметр | Описание | Значение по умолчанию |
+|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|
+| `KeepAlivePingDelay` | Клиент отправляет на сервер запрос о поддержании связи, если в течение этого периода времени не получает никаких сообщений по конкретному соединению. Это свойство используется вместе с параметром `KeepAlivePingTimeout`, чтобы проверить, не разорвано ли соединение. Значение должно быть больше или равно `1` секунде. Установите значение `0`, чтобы отключить проверку связи keep alive. | `10` секунд |
+| `KeepAlivePingTimeout` | Сообщения о поддержании связи отправляются, когда период бездействия превышает заданное значение `KeepAlivePingDelay`. Клиент завершает соединение, если в течение времени ожидания не получает ни одного сообщения. Время ожидания должно быть больше или равно `1` секунде. Установите значение `0`, чтобы отключить тайм-аут для поддержания соединения в режиме ожидания. | `10` секунд |
+
+## Параметры конструктора соединений {#connection-builder-parameters}
+
+Существуют также дополнительные параметры, которые не участвуют в формировании строки `ConnectionString`. Их можно указать только с использованием `YdbConnectionStringBuilder`:
+
+| Параметр | Описание | Значение по умолчанию |
+|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|
+| `LoggerFactory` | Этот параметр принимает экземпляр, реализующий интерфейс [ILoggerFactory](https://learn.microsoft.com/ru-ru/dotnet/api/microsoft.extensions.logging.iloggerfactory). `ILoggerFactory` — это стандартный интерфейс для фабрик логирования в .NET. Допускается использование популярных фреймворков, таких как [NLog](https://github.com/NLog/NLog), [Serilog](https://github.com/serilog/serilog), [log4net](https://github.com/apache/logging-log4net). | `NullLoggerFactory.Instance` |
+| `CredentialsProvider` | Поставщик аутентификации, реализующий `Ydb.Sdk.Auth.ICredentialsProvider`. Стандартные способы аутентификации:
1) `Ydb.Sdk.Auth.TokenProvider` — аутентификация токеном для OAuth-подобных токенов.
2) Для Yandex Cloud рассмотрите возможность использования **[ydb-dotnet-yc](https://github.com/ydb-platform/ydb-dotnet-yc)**. | Анонимное подключение |
+| `ServerCertificates` | Указывает пользовательские серверные сертификаты, используемые для проверки TLS/SSL. Это полезно при работе с облачными провайдерами (например, Yandex Cloud), которые используют пользовательские корневые или промежуточные сертификаты, которым по умолчанию не доверяют. | Не определено |
diff --git a/ydb/docs/ru/core/reference/languages-and-apis/ado-net/getting-started.md b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/getting-started.md
new file mode 100644
index 000000000000..da37fddb5561
--- /dev/null
+++ b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/getting-started.md
@@ -0,0 +1,37 @@
+# Начало работы с ADO.NET
+
+Лучший способ использовать `Ydb.Sdk` — установить его [NuGet-пакет](https://www.nuget.org/packages/Ydb.Sdk).
+
+`Ydb.Sdk.Ado` стремится быть полностью совместимым с ADO.NET; его API должен быть практически идентичен другим драйверам баз данных .NET.
+
+Вот базовый фрагмент кода, который поможет вам начать:
+
+```c#
+await using var connection = new YdbConnection("Host=localhost;Port=2136;Database=/local;MaxSessionPool=50");
+await connection.OpenAsync();
+
+var ydbCommand = connection.CreateCommand();
+ydbCommand.CommandText = """
+ SELECT series_id, season_id, episode_id, air_date, title
+ FROM episodes
+ WHERE series_id = @series_id AND season_id > @season_id
+ ORDER BY series_id, season_id, episode_id
+ LIMIT @limit_size;
+ """;
+ydbCommand.Parameters.Add(new YdbParameter("series_id", DbType.UInt64, 1U));
+ydbCommand.Parameters.Add(new YdbParameter("season_id", DbType.UInt64, 1U));
+ydbCommand.Parameters.Add(new YdbParameter("limit_size", DbType.UInt64, 3U));
+
+var ydbDataReader = await ydbCommand.ExecuteReaderAsync();
+
+_logger.LogInformation("Selected rows:");
+while (await ydbDataReader.ReadAsync())
+{
+ _logger.LogInformation(
+ "series_id: {series_id}, season_id: {season_id}, episode_id: {episode_id}, air_date: {air_date}, title: {title}",
+ ydbDataReader.GetUint64(0), ydbDataReader.GetUint64(1), ydbDataReader.GetUint64(2),
+ ydbDataReader.GetDateTime(3), ydbDataReader.GetString(4));
+}
+```
+
+Вы можете найти более подробную информацию о ADO.NET API в документации [MSDN](https://learn.microsoft.com/ru-ru/dotnet/framework/data/adonet/ado-net-overview?redirectedfrom=MSDN) или во многих других руководствах в интернете.
diff --git a/ydb/docs/ru/core/reference/languages-and-apis/ado-net/index.md b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/index.md
new file mode 100644
index 000000000000..115d5be21c38
--- /dev/null
+++ b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/index.md
@@ -0,0 +1,13 @@
+# ADO.NET — доступ к {{ ydb-short-name }} из .NET
+
+`Ydb.Sdk` — [ADO.NET](https://learn.microsoft.com/ru-ru/dotnet/framework/data/adonet/) Data Provider для {{ ydb-short-name }}, позволяющий программам, написанным на C#, Visual Basic или F#, получить доступ к {{ ydb-short-name }}. Провайдер полностью реализован на C#, является бесплатным и с [открытым исходным кодом](https://github.com/ydb-platform/ydb-dotnet-sdk).
+
+## Документация
+
+- [{#T}](getting-started.md)
+- [{#T}](installation.md)
+- [{#T}](basic-usage.md)
+- [{#T}](connection-parameters.md)
+- [{#T}](type-mapping.md)
+- [{#T}](yandex-cloud.md)
+- [{#T}](./../../../integrations/orm/dapper.md)
diff --git a/ydb/docs/ru/core/reference/languages-and-apis/ado-net/installation.md b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/installation.md
new file mode 100644
index 000000000000..bc6c841cb07c
--- /dev/null
+++ b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/installation.md
@@ -0,0 +1,7 @@
+# Установка ADO.NET
+
+Официальные версии `Ydb.Sdk` всегда доступны на [nuget.org](https://www.nuget.org/packages/Ydb.Sdk/). Это рекомендуемый способ использования `Ydb.Sdk`.
+
+```bash
+dotnet add package Ydb.Sdk
+```
diff --git a/ydb/docs/ru/core/reference/languages-and-apis/ado-net/toc_p.yaml b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/toc_p.yaml
new file mode 100644
index 000000000000..1c30cbd06933
--- /dev/null
+++ b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/toc_p.yaml
@@ -0,0 +1,13 @@
+items:
+- name: Hачало работы
+ href: getting-started.md
+- name: Установка
+ href: installation.md
+- name: Основное использование
+ href: basic-usage.md
+- name: Параметры подключения
+ href: connection-parameters.md
+- name: Соответствие типов
+ href: type-mapping.md
+- name: Подключение к Yandex Cloud
+ href: yandex-cloud.md
diff --git a/ydb/docs/ru/core/reference/languages-and-apis/ado-net/type-mapping.md b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/type-mapping.md
new file mode 100644
index 000000000000..cef30108f5cf
--- /dev/null
+++ b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/type-mapping.md
@@ -0,0 +1,66 @@
+# Поддерживаемые типы данных в интеграции с ADO.NET и их соответствие
+
+Ниже перечислены встроенные сопоставления при чтении и записи типов CLR в типы {{ ydb-short-name }}.
+
+## Таблица сопоставления типов на чтение
+
+Ниже показаны сопоставления, используемые при чтении значений.
+
+Возвращаемый тип при использовании `YdbCommand.ExecuteScalarAsync()`, `YdbDataReader.GetValue()` и подобных методов.
+
+| {{ ydb-short-name }} тип | .NET тип |
+|----------------------------|------------|
+| `Bool` | `bool` |
+| `Text` (синоним `Utf8`) | `string` |
+| `Bytes` (синоним `String`) | `byte[]` |
+| `Uint8` | `byte` |
+| `Uint16` | `ushort` |
+| `Uint32` | `uint` |
+| `Uint64` | `ulong` |
+| `Int8` | `sbyte` |
+| `Int16` | `short` |
+| `Int32` | `int` |
+| `Int64` | `long` |
+| `Float` | `float` |
+| `Double` | `double` |
+| `Date` | `DateTime` |
+| `Datetime` | `DateTime` |
+| `Timestamp` | `DateTime` |
+| `Decimal(22,9)` | `Decimal` |
+| `Json` | `string` |
+| `JsonDocument` | `string` |
+| `Yson` | `byte[]` |
+
+## Таблица сопоставления типов на запись
+
+| {{ ydb-short-name }} тип | DbType | .NET тип |
+|----------------------------|-------------------------------------------------------------------------------------------|------------------------------|
+| `Bool` | `Boolean` | `bool` |
+| `Text` (синоним `Utf8`) | `String`, `AnsiString`, `AnsiStringFixedLength`, `StringFixedLength` | `string` |
+| `Bytes` (синоним `String`) | `Binary` | `byte[]` |
+| `Uint8` | `Byte` | `byte` |
+| `Uint16` | `UInt16` | `ushort` |
+| `Uint32` | `UInt32` | `uint` |
+| `Uint64` | `UInt64` | `ulong` |
+| `Int8` | `SByte` | `sbyte` |
+| `Int16` | `Int16` | `short` |
+| `Int32` | `Int32` | `int` |
+| `Int64` | `Int64` | `long` |
+| `Float` | `Single` | `float` |
+| `Double` | `Double` | `double` |
+| `Date` | `Date` | `DateTime` |
+| `Datetime` | `DateTime` | `DateTime` |
+| `Timestamp` | `DateTime2` (для .NET типа `DateTime`), `DateTimeOffset` (для .NET типа `DateTimeOffset`) | `DateTime`, `DateTimeOffset` |
+| `Decimal(22,9)` | `Decimal`, `Currency` | `decimal` |
+
+{% note info %}
+
+Важно понимать, что если `DbType` не указан, параметр будет вычислен из `System.Type`.
+
+{% endnote %}
+
+Также вы можете указывать любой {{ ydb-short-name }} тип, используя конструкторы из `Ydb.Sdk.Value.YdbValue`. Например:
+
+```с#
+var parameter = new YdbParameter("$parameter", YdbValue.MakeJsonDocument("{\"type\": \"jsondoc\"}"));
+```
diff --git a/ydb/docs/ru/core/reference/languages-and-apis/ado-net/yandex-cloud.md b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/yandex-cloud.md
new file mode 100644
index 000000000000..82f0e47df854
--- /dev/null
+++ b/ydb/docs/ru/core/reference/languages-and-apis/ado-net/yandex-cloud.md
@@ -0,0 +1,57 @@
+# Подключение ADO.NET к Yandex Cloud
+
+## Установка
+
+Чтобы использовать аутентификацию [Yandex Cloud](https://yandex.cloud/ru) в вашем .NET-приложении, установите `Ydb.Sdk.Yc.Auth` [NuGet-пакет](https://www.nuget.org/packages/Ydb.Sdk.Yc.Auth/):
+
+```bash
+dotnet add package Ydb.Sdk.Yc.Auth
+```
+
+Этот пакет предоставляет необходимые инструменты для аутентификации в сервисах Yandex Cloud.
+
+## Аутентификация
+
+Поддерживаемые Yandex Cloud методы аутентификации:
+
+- `Ydb.Sdk.Yc.ServiceAccountProvider` — аутентификация через [сервисный аккаунт](https://yandex.cloud/ru/docs/iam/concepts/users/service-accounts). Пример использования:
+
+ ```c#
+ var saProvider = new ServiceAccountProvider(
+ saFilePath: file, // Path to file with service account JSON info
+ loggerFactory: loggerFactory
+ );
+ ```
+
+- `Ydb.Sdk.Yc.MetadataProvider` — аутентификация через [сервис метаданных](https://yandex.cloud/ru/docs/compute/operations/vm-connect/auth-inside-vm); используется внутри облачных виртуальных машин Яндекса и облачных функций. Пример использования:
+
+ ```c#
+ var metadataProvider = new MetadataProvider(loggerFactory: loggerFactory);
+ ```
+
+## Сертификаты
+
+Библиотека включает в себя сертификаты Yandex Cloud, которые необходимы для подключения к Dedicated {{ ydb-short-name }}:
+
+```c#
+var certs = Ydb.Sdk.Yc.YcCerts.GetYcServerCertificates();
+```
+
+## Как подключиться с ADO.NET
+
+Чтобы установить безопасное соединение с {{ ydb-short-name }} с помощью ADO.NET с требуемыми параметрами аутентификации и TLS, используйте следующий пример:
+
+```c#
+var builder = new YdbConnectionStringBuilder
+{
+ // More settings ...
+ UseTls = true,
+ Port = 2135,
+ CredentialsProvider = saProvider, // For service account
+ ServerCertificates = YcCerts.GetYcServerCertificates() // custom certificates Yandex Cloud
+};
+```
+
+## Пример
+
+[ADO.NET подключение к Yandex Cloud](https://github.com/ydb-platform/ydb-dotnet-sdk/tree/main/examples/src/YC)
diff --git a/ydb/docs/ru/core/reference/languages-and-apis/index.md b/ydb/docs/ru/core/reference/languages-and-apis/index.md
index 059651eb6003..02d25e633b91 100644
--- a/ydb/docs/ru/core/reference/languages-and-apis/index.md
+++ b/ydb/docs/ru/core/reference/languages-and-apis/index.md
@@ -1,3 +1,4 @@
# Языки и API
-- [{#T}](jdbc-driver/index.md)
\ No newline at end of file
+- [{#T}](jdbc-driver/index.md)
+- [{#T}](ado-net/index.md)
\ No newline at end of file
diff --git a/ydb/docs/ru/core/reference/languages-and-apis/toc_p.yaml b/ydb/docs/ru/core/reference/languages-and-apis/toc_p.yaml
index dc557044a5ca..492c047317d8 100644
--- a/ydb/docs/ru/core/reference/languages-and-apis/toc_p.yaml
+++ b/ydb/docs/ru/core/reference/languages-and-apis/toc_p.yaml
@@ -4,4 +4,8 @@ items:
include:
mode: link
path: jdbc-driver/toc_p.yaml
-
+- name: ADO.NET
+ href: ado-net/index.md
+ include:
+ mode: link
+ path: ado-net/toc_p.yaml
\ No newline at end of file