Npgsql：如何使用BeginTextImportAsync异步方法？

问题背景 #

在Npgsql v8的API参考中记载了NpgsqlConnection.BeginTextExportAsync方法，但找不到该异步变体的使用示例。我目前用COPY命令批量上传数据，输入数据来自StringBuilder，同步代码如下：

using var writer = connection.BeginTextImport(_sqlCopyRawData);
foreach (string sLine in sb.ToString().Split(Environment.NewLine))
{
    writer.WriteLine(sLine);
}

同时发现NpgsqlConnection的同步方法内部也是基于异步实现封装的，比如：

public TextReader BeginTextExport(string copyToCommand)
    => BeginTextExport(async: false, copyToCommand, CancellationToken.None).GetAwaiter().GetResult();

想了解这类异步方法该如何正确使用。

异步方法使用示例 #

1. 批量导入数据（对应BeginTextImportAsync） #

如果你的场景是向PostgreSQL批量写入数据（COPY FROM STDIN），对应异步方法为BeginTextImportAsync，使用方式如下：

// 方法需标记为async以支持await关键字
public async Task BulkImportDataAsync(NpgsqlConnection connection, string copyCommand, StringBuilder sb, CancellationToken cancellationToken = default)
{
    // 异步获取用于写入的TextWriter
    using var writer = await connection.BeginTextImportAsync(copyCommand, cancellationToken);
    
    foreach (string sLine in sb.ToString().Split(Environment.NewLine))
    {
        // 使用异步写入方法替代同步方法，避免阻塞线程
        await writer.WriteLineAsync(sLine, cancellationToken);
    }
    
    // 异步刷新缓冲区，确保所有数据发送到数据库
    await writer.FlushAsync(cancellationToken);
}

2. 批量导出数据（对应BeginTextExportAsync） #

如果是从PostgreSQL导出数据（COPY TO STDOUT），则使用BeginTextExportAsync，示例如下：

public async Task BulkExportDataAsync(NpgsqlConnection connection, string copyCommand, Stream outputStream, CancellationToken cancellationToken = default)
{
    // 异步获取用于读取的TextReader
    using var reader = await connection.BeginTextExportAsync(copyCommand, cancellationToken);
    
    // 异步将导出数据复制到目标流（如文件流、网络流）
    await reader.CopyToAsync(new StreamWriter(outputStream), cancellationToken);
}

关键注意事项 #

• 异步方法必须在标记为async的方法中调用，并用await关键字等待执行结果
• 优先使用配套的异步IO方法（如WriteLineAsync、CopyToAsync），避免在异步上下文调用同步方法造成线程阻塞
• 始终传递CancellationToken，以便在需要时取消操作，提升系统响应性
• 使用using语句确保TextWriter/TextReader正确释放资源，避免数据库连接泄漏

内容的提问来源于stack exchange，提问作者Mike969