Azure 中继混合连接 .NET 标准 API 概述Azure Relay Hybrid Connections .NET Standard API overview

本文汇总了一些重要的 Azure 中继混合连接 .NET 标准客户端 APIThis article summarizes some of the key Azure Relay Hybrid Connections .NET Standard client APIs.

中继连接字符串生成器类Relay Connection String Builder class

RelayConnectionStringBuilder 类对特定于中继混合连接的连接字符串进行格式设置。The RelayConnectionStringBuilder class formats connection strings that are specific to Relay Hybrid Connections. 该类可用于验证连接字符串的格式或从头开始生成连接字符串。You can use it to verify the format of a connection string, or to build a connection string from scratch. 有关示例,请参阅以下代码:See the following code for an example:

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 方法。You can also pass a connection string directly to the RelayConnectionStringBuilder method. 此操作允许验证连接字符串是否为有效格式。This operation enables you to verify that the connection string is in a valid format. 如果任何参数无效,构造函数生成 ArgumentExceptionIf any of the parameters are invalid, the constructor generates an 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
}

混合连接流Hybrid connection stream

无论使用的是 HybridConnectionClient,还是 HybridConnectionListenerHybridConnectionStream 类这一主要对象均用于从 Azure 中继终结点发送和接收数据。The HybridConnectionStream class is the primary object used to send and receive data from an Azure Relay endpoint, whether you are working with a HybridConnectionClient, or a HybridConnectionListener.

获取混合连接流Getting a Hybrid connection stream

侦听器Listener

使用 HybridConnectionListener 对象可以获取 HybridConnectionStream 对象,如下所示:Using a HybridConnectionListener object, you can obtain a HybridConnectionStream object as follows:

// 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();

客户端Client

使用 HybridConnectionClient 对象可以获取 HybridConnectionStream 对象,如下所示:Using a HybridConnectionClient object, you can obtain a HybridConnectionStream object as follows:

// 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();

接收数据Receiving data

HybridConnectionStream 类允许进行双向通信。The HybridConnectionStream class enables two-way communication. 在大多数情况下,都会持续地从流接收信息。In most cases, you continuously receive from the stream. 如果正在从流读取文本,则还需使用 StreamReader 对象,以便于分析数据。If you are reading text from the stream, you might also want to use a StreamReader object, which enables easier parsing of the data. 例如,可以将数据读取为文本,而不能读取为 byte[]For example, you can read data as text, rather than as byte[].

以下代码可从流中读取各行文本,直到请求取消为止:The following code reads individual lines of text from the stream until a cancellation is requested:

// 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;
    }
}

发送数据Sending data

建立连接后,即可将消息发送到中继终结点。Once you have a connection established, you can send a message to the Relay endpoint. 由于连接对象继承 Stream,因此以 byte[] 形式发送数据。Because the connection object inherits Stream, send your data as a byte[]. 以下示例介绍如何执行此操作:The following example shows how to do this:

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

但是,如果要直接发送文本,而无需每次都对字符串进行编码,则可以使用 StreamWriter 对象包装 hybridConnectionStream 对象。However, if you want to send text directly, without needing to encode the string each time, you can wrap the hybridConnectionStream object with a StreamWriter object.

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

后续步骤Next steps

若要了解有关 Azure 中继的详细信息,请访问以下链接:To learn more about Azure Relay, visit these links: