Azure 中继混合连接 .NET 标准 API 概述

本文汇总了一些重要的 Azure 中继混合连接 .NET 标准客户端 API。

中继连接字符串生成器类

RelayConnectionStringBuilder 类对特定于中继混合连接的连接字符串进行格式设置。 该类可用于验证连接字符串的格式或从头开始生成连接字符串。 有关示例，请参阅以下代码：

var endpoint = "[Relay namespace]";
var entityPath = "[Name of the Hybrid Connection]";
var sharedAccessKeyName = "[SAS key name]";
var sharedAccessKey = "[SAS key value]";

var connectionStringBuilder = new RelayConnectionStringBuilder()
{
    Endpoint = endpoint,
    EntityPath = entityPath,
    SharedAccessKeyName = sasKeyName,
    SharedAccessKey = sasKeyValue
};

还可以将连接字符串直接传递给 RelayConnectionStringBuilder 方法。 此操作允许验证连接字符串是否为有效格式。 如果任何参数无效，构造函数生成 ArgumentException。

var myConnectionString = "[RelayConnectionString]";
// Declare the connectionStringBuilder so that it can be used outside of the loop if needed
RelayConnectionStringBuilder connectionStringBuilder;
try
{
    // Create the connectionStringBuilder using the supplied connection string
    connectionStringBuilder = new RelayConnectionStringBuilder(myConnectionString);
}
catch (ArgumentException ae)
{
    // Perform some error handling
}

混合连接流

无论使用的是 HybridConnectionClient 还是 HybridConnectionListener，HybridConnectionStream 类都是用于从 Azure 中继终结点发送和接收数据的主要对象。

获取混合连接流

侦听器

使用 HybridConnectionListener 对象可以获取 HybridConnectionStream 对象，如下所示：

// Use the RelayConnectionStringBuilder to get a valid connection string
var listener = new HybridConnectionListener(csb.ToString());
// Open a connection to the Relay endpoint
await listener.OpenAsync();
// Get a `HybridConnectionStream`
var hybridConnectionStream = await listener.AcceptConnectionAsync();

客户端

使用 HybridConnectionClient 对象可以获取 HybridConnectionStream 对象，如下所示：

// Use the RelayConnectionStringBuilder to get a valid connection string
var client = new HybridConnectionClient(csb.ToString());
// Open a connection to the Relay endpoint and get a `HybridConnectionStream`
var hybridConnectionStream = await client.CreateConnectionAsync();

接收数据

HybridConnectionStream 类允许进行双向通信。 在大多数情况下，都会持续地从流接收信息。 如果正在从流读取文本，则还需使用 StreamReader 对象，以便于分析数据。 例如，可以将数据读取为文本，而不能读取为 byte[]。

以下代码可从流中读取各行文本，直到请求取消为止：

// Create a CancellationToken, so that we can cancel the while loop
var cancellationToken = new CancellationToken();
// Create a StreamReader from the hybridConnectionStream
var streamReader = new StreamReader(hybridConnectionStream);

while (!cancellationToken.IsCancellationRequested)
{
    // Read a line of input until a newline is encountered
    var line = await streamReader.ReadLineAsync();
    if (string.IsNullOrEmpty(line))
    {
        // If there's no input data, we will signal that 
        // we will no longer send data on this connection
        // and then break out of the processing loop.
        await hybridConnectionStream.ShutdownAsync(cancellationToken);
        break;
    }
}

发送数据

建立连接后，即可将消息发送到中继终结点。 由于连接对象继承 Stream，因此以 byte[] 形式发送数据。 以下示例介绍如何执行此操作：

var data = Encoding.UTF8.GetBytes("hello");
await clientConnection.WriteAsync(data, 0, data.Length);

但是，如果要直接发送文本，而无需每次都对字符串进行编码，则可以使用 StreamWriter 对象包装 hybridConnectionStream 对象。

// The StreamWriter object only needs to be created once
var textWriter = new StreamWriter(hybridConnectionStream);
await textWriter.WriteLineAsync("hello");

后续步骤

若要了解有关 Azure 中继的详细信息，请访问以下链接：

• Microsoft.Azure.Relay reference
• 什么是 Azure 中继？
• 可用的中继 API