Introdução aos Websockets das Ligações Híbridas do Azure Relay em .NET

Artigo
08/16/2024

NET
Node.js

Neste início rápido, você cria aplicativos de remetente e recetor .NET que enviam e recebem mensagens usando WebSockets de Conexões Híbridas no Azure Relay. Para saber mais sobre o Azure Relay em geral, consulte Azure Relay.

Neste guia de início rápido, você executa as seguintes etapas:

Crie um espaço de nomes de Reencaminhamento com o Portal do Azure.
Crie uma ligação híbrida nesse espaço de nomes, com o portal do Azure.
Escrever uma aplicação de consola (serviço de escuta) de servidor para receber mensagens.
Escrever uma aplicação de consola (remetente) de cliente para enviar mensagens.
Execute aplicativos.

Pré-requisitos

Para concluir este tutorial, precisa dos seguintes pré-requisitos:

Visual Studio 2015 ou posterior. Os exemplos neste tutorial utilizam o Visual Studio 2017.
Uma subscrição do Azure. Se não tiver uma, crie uma conta gratuita antes de começar.

Criar um espaço de nomes

Inicie sessão no portal do Azure.
Selecione Todos os serviços no menu à esquerda. Selecione Integração, procure Relés, mova o rato sobre Relés e, em seguida, selecione Criar.
Na página Criar namespace, siga estas etapas:
1. Escolha uma assinatura do Azure na qual criar o namespace.
2. Para Grupo de recursos, escolha um grupo de recursos existente no qual colocar o namespace ou crie um novo.
3. Insira um nome para o namespace Relay.
4. Selecione a região na qual seu namespace deve ser hospedado.
5. Selecione Rever + criar na parte inferior da página.
6. Na página Rever + criar, selecione Criar.
7. Depois de alguns minutos, você verá a página Retransmissão para o namespace.

Obter credenciais de gestão

Na página Retransmissão, selecione Políticas de acesso compartilhado no menu à esquerda. `
Na página Políticas de acesso compartilhado, selecione RootManageSharedAccessKey.
Em Política SAS: RootManageSharedAccessKey, selecione o botão Copiar ao lado de Cadeia de Conexão Primária. Esta ação copia a cadeia de conexão para a área de transferência para uso posterior. Cole este valor no Bloco de Notas ou noutra localização temporária.
Repita o passo anterior para copiar e colar o valor da Chave primária para uma localização temporária para utilizar mais tarde.

Criar uma ligação híbrida

Na página Retransmissão para seu namespace, siga estas etapas para criar uma conexão híbrida.

No menu à esquerda, em Entidades, selecione Conexões híbridas e, em seguida, selecione + Conexão híbrida.
Na página Criar Conexão Híbrida, insira um nome para a conexão híbrida e selecione Criar.

Criar uma aplicação de servidor (serviço de escuta)

No Visual Studio, crie uma aplicação de consola C# para ouvir e receber mensagens do reencaminhamento.

Criar uma aplicação de consola

No Visual Studio, crie um novo projeto de Aplicação de Consola (.NET Framework).

Adicionar o pacote NuGet de Reencaminhamento

Clique com o botão direito do rato no projeto recém-criado e, em seguida, selecione Gerir Pacotes NuGet.
Selecione Procurar e, em seguida, procure Microsoft.Azure.Relay. Nos resultados da pesquisa, selecione Reencaminhamento do Microsoft Azure.
Selecione Instalar para concluir a instalação. Feche a caixa de diálogo.

Escrever código para receber mensagens

Na parte superior do ficheiro Program.cs, substitua as instruções using existentes pelas seguintes instruções using:

using System;
using System.IO;
using System.Threading;
using System.Threading.Tasks;
using System.Net;
using Microsoft.Azure.Relay;

Adicione constantes à classe Program, para obter os detalhes da ligação híbrida. Substitua os espaços reservados pelos valores obtidos quando você criou a conexão híbrida. Certifique-se de que utiliza o nome de espaço de nomes totalmente qualificado.

// replace {RelayNamespace} with the name of your namespace
private const string RelayNamespace = "YOUR-RELAY-NAMESPACE-NAME.servicebus.windows.net";

// replace {HybridConnectionName} with the name of your hybrid connection
private const string ConnectionName = "HYBRID-CONNECTION-NAME";

// replace {SAKKeyName} with the name of your Shared Access Policies key, which is RootManageSharedAccessKey by default
private const string KeyName = "SAS-KEY-NAME";

// replace {SASKey} with the primary key of the namespace you saved earlier
private const string Key = "SAS-KEY-VALUE";

Adicione o método ProcessMessagesOnConnection à classe Program:

// The method initiates the connection.
private static async void ProcessMessagesOnConnection(HybridConnectionStream relayConnection, CancellationTokenSource cts)
{
    Console.WriteLine("New session");

    // The connection is a fully bidrectional stream. 
    // Put a stream reader and a stream writer over it.  
    // This allows you to read UTF-8 text that comes from 
    // the sender, and to write text replies back.
    var reader = new StreamReader(relayConnection);
    var writer = new StreamWriter(relayConnection) { AutoFlush = true };
    while (!cts.IsCancellationRequested)
    {
        try
        {
            // Read a line of input until a newline is encountered.
            var line = await reader.ReadLineAsync();

            if (string.IsNullOrEmpty(line))
            {
                // If there's no input data, signal that 
                // you will no longer send data on this connection,
                // and then break out of the processing loop.
                await relayConnection.ShutdownAsync(cts.Token);
                break;
            }

            // Write the line on the console.
            Console.WriteLine(line);

            // Write the line back to the client, prepended with "Echo:"
            await writer.WriteLineAsync($"Echo: {line}");
        }
        catch (IOException)
        {
            // Catch an I/O exception. This likely occurred when
            // the client disconnected.
            Console.WriteLine("Client closed connection");
            break;
        }
    }

    Console.WriteLine("End session");

    // Close the connection.
    await relayConnection.CloseAsync(cts.Token);
}

Adicione o método RunAsync à classe Program:

private static async Task RunAsync()
{
    var cts = new CancellationTokenSource();

    var tokenProvider = TokenProvider.CreateSharedAccessSignatureTokenProvider(KeyName, Key);
    var listener = new HybridConnectionListener(new Uri(string.Format("sb://{0}/{1}", RelayNamespace, ConnectionName)), tokenProvider);

    // Subscribe to the status events.
    listener.Connecting += (o, e) => { Console.WriteLine("Connecting"); };
    listener.Offline += (o, e) => { Console.WriteLine("Offline"); };
    listener.Online += (o, e) => { Console.WriteLine("Online"); };

    // Opening the listener establishes the control channel to
    // the Azure Relay service. The control channel is continuously 
    // maintained, and is reestablished when connectivity is disrupted.
    await listener.OpenAsync(cts.Token);
    Console.WriteLine("Server listening");

    // Provide callback for the cancellation token that will close the listener.
    cts.Token.Register(() => listener.CloseAsync(CancellationToken.None));

    // Start a new thread that will continuously read the console.
    new Task(() => Console.In.ReadLineAsync().ContinueWith((s) => { cts.Cancel(); })).Start();

    // Accept the next available, pending connection request. 
    // Shutting down the listener allows a clean exit. 
    // This method returns null.
    while (true)
    {
        var relayConnection = await listener.AcceptConnectionAsync();
        if (relayConnection == null)
        {
            break;
        }

        ProcessMessagesOnConnection(relayConnection, cts);
    }

    // Close the listener after you exit the processing loop.
    await listener.CloseAsync(cts.Token);
}

Adicione a seguinte linha de código ao método Main na classe Program:

RunAsync().GetAwaiter().GetResult();

O ficheiro Program.cs completo deve ter o seguinte aspeto:

namespace Server
{
    using System;
    using System.IO;
    using System.Threading;
    using System.Threading.Tasks;
    using Microsoft.Azure.Relay;

    public class Program
    {
        private const string RelayNamespace = "{RelayNamespace}.servicebus.windows.net";
        private const string ConnectionName = "{HybridConnectionName}";
        private const string KeyName = "{SASKeyName}";
        private const string Key = "{SASKey}";

        public static void Main(string[] args)
        {
            RunAsync().GetAwaiter().GetResult();
        }

        private static async Task RunAsync()
        {
            var cts = new CancellationTokenSource();

            var tokenProvider = TokenProvider.CreateSharedAccessSignatureTokenProvider(KeyName, Key);
            var listener = new HybridConnectionListener(new Uri(string.Format("sb://{0}/{1}", RelayNamespace, ConnectionName)), tokenProvider);

            // Subscribe to the status events.
            listener.Connecting += (o, e) => { Console.WriteLine("Connecting"); };
            listener.Offline += (o, e) => { Console.WriteLine("Offline"); };
            listener.Online += (o, e) => { Console.WriteLine("Online"); };

            // Opening the listener establishes the control channel to
            // the Azure Relay service. The control channel is continuously 
            // maintained, and is reestablished when connectivity is disrupted.
            await listener.OpenAsync(cts.Token);
            Console.WriteLine("Server listening");

            // Provide callback for a cancellation token that will close the listener.
            cts.Token.Register(() => listener.CloseAsync(CancellationToken.None));

            // Start a new thread that will continuously read the console.
            new Task(() => Console.In.ReadLineAsync().ContinueWith((s) => { cts.Cancel(); })).Start();

            // Accept the next available, pending connection request. 
            // Shutting down the listener allows a clean exit. 
            // This method returns null.
            while (true)
            {
                var relayConnection = await listener.AcceptConnectionAsync();
                if (relayConnection == null)
                {
                    break;
                }

                ProcessMessagesOnConnection(relayConnection, cts);
            }

            // Close the listener after you exit the processing loop.
            await listener.CloseAsync(cts.Token);
        }

        private static async void ProcessMessagesOnConnection(HybridConnectionStream relayConnection, CancellationTokenSource cts)
        {
            Console.WriteLine("New session");

            // The connection is a fully bidrectional stream. 
            // Put a stream reader and a stream writer over it.  
            // This allows you to read UTF-8 text that comes from 
            // the sender, and to write text replies back.
            var reader = new StreamReader(relayConnection);
            var writer = new StreamWriter(relayConnection) { AutoFlush = true };
            while (!cts.IsCancellationRequested)
            {
                try
                {
                    // Read a line of input until a newline is encountered.
                    var line = await reader.ReadLineAsync();

                    if (string.IsNullOrEmpty(line))
                    {
                        // If there's no input data, signal that 
                        // you will no longer send data on this connection.
                        // Then, break out of the processing loop.
                        await relayConnection.ShutdownAsync(cts.Token);
                        break;
                    }

                    // Write the line on the console.
                    Console.WriteLine(line);

                    // Write the line back to the client, prepended with "Echo:"
                    await writer.WriteLineAsync($"Echo: {line}");
                }
                catch (IOException)
                {
                    // Catch an I/O exception. This likely occurred when
                    // the client disconnected.
                    Console.WriteLine("Client closed connection");
                    break;
                }
            }

            Console.WriteLine("End session");

            // Close the connection.
            await relayConnection.CloseAsync(cts.Token);
        }
    }
}

Criar uma aplicação cliente (remetente)

No Visual Studio, crie uma aplicação de consola C# para enviar mensagens para o reencaminhamento.

Criar uma aplicação de consola

No Visual Studio, crie um novo projeto de Aplicação de Consola (.NET Framework).

Adicionar o pacote NuGet de Reencaminhamento

Clique com o botão direito do rato no projeto recém-criado e, em seguida, selecione Gerir Pacotes NuGet.
Selecione Procurar e, em seguida, procure Microsoft.Azure.Relay. Nos resultados da pesquisa, selecione Reencaminhamento do Microsoft Azure.
Selecione Instalar para concluir a instalação. Feche a caixa de diálogo.

Escrever código para enviar mensagens

Na parte superior do ficheiro Program.cs, substitua as instruções using existentes pelas seguintes instruções using:
```
using System;
using System.IO;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Azure.Relay;
```

// replace {RelayNamespace} with the name of your namespace
private const string RelayNamespace = "YOUR-RELAY-NAMESPACE-NAME.servicebus.windows.net";

// replace {HybridConnectionName} with the name of your hybrid connection
private const string ConnectionName = "HYBRID-CONNECTION-NAME";

// replace {SAKKeyName} with the name of your Shared Access Policies key, which is RootManageSharedAccessKey by default
private const string KeyName = "SAS-KEY-NAME";

// replace {SASKey} with the primary key of the namespace you saved earlier
private const string Key = "SAS-KEY-VALUE";

Adicione o seguinte método à classe Program:

private static async Task RunAsync()
{
    Console.WriteLine("Enter lines of text to send to the server with ENTER");

    // Create a new hybrid connection client.
    var tokenProvider = TokenProvider.CreateSharedAccessSignatureTokenProvider(KeyName, Key);
    var client = new HybridConnectionClient(new Uri(String.Format("sb://{0}/{1}", RelayNamespace, ConnectionName)), tokenProvider);

    // Initiate the connection.
    var relayConnection = await client.CreateConnectionAsync();

    // Run two concurrent loops on the connection. One 
    // reads input from the console and writes it to the connection 
    // with a stream writer. The other reads lines of input from the 
    // connection with a stream reader and writes them to the console. 
    // Entering a blank line shuts down the write task after 
    // sending it to the server. The server then cleanly shuts down
    // the connection, which terminates the read task.

    var reads = Task.Run(async () => {
        // Initialize the stream reader over the connection.
        var reader = new StreamReader(relayConnection);
        var writer = Console.Out;
        do
        {
            // Read a full line of UTF-8 text up to newline.
            string line = await reader.ReadLineAsync();
            // If the string is empty or null, you are done.
            if (String.IsNullOrEmpty(line))
                break;
            // Write to the console.
            await writer.WriteLineAsync(line);
        }
        while (true);
    });

    // Read from the console and write to the hybrid connection.
    var writes = Task.Run(async () => {
        var reader = Console.In;
        var writer = new StreamWriter(relayConnection) { AutoFlush = true };
        do
        {
            // Read a line from the console.
            string line = await reader.ReadLineAsync();
            // Write the line out, also when it's empty.
            await writer.WriteLineAsync(line);
            // Quit when the line is empty,
            if (String.IsNullOrEmpty(line))
                break;
        }
        while (true);
    });

    // Wait for both tasks to finish.
    await Task.WhenAll(reads, writes);
    await relayConnection.CloseAsync(CancellationToken.None);
}

Adicione a seguinte linha de código ao método Main na classe Program.

RunAsync().GetAwaiter().GetResult();

O ficheiro Program.cs deve ter o seguinte aspeto:

using System;
using System.IO;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Azure.Relay;

namespace Client
{
    class Program
    {
        private const string RelayNamespace = "{RelayNamespace}.servicebus.windows.net";
        private const string ConnectionName = "{HybridConnectionName}";
        private const string KeyName = "{SASKeyName}";
        private const string Key = "{SASKey}";

        static void Main(string[] args)
        {
            RunAsync().GetAwaiter().GetResult();
        }

        private static async Task RunAsync()
        {
            Console.WriteLine("Enter lines of text to send to the server with ENTER");

            // Create a new hybrid connection client.
            var tokenProvider = TokenProvider.CreateSharedAccessSignatureTokenProvider(KeyName, Key);
            var client = new HybridConnectionClient(new Uri(String.Format("sb://{0}/{1}", RelayNamespace, ConnectionName)), tokenProvider);

            // Initiate the connection.
            var relayConnection = await client.CreateConnectionAsync();

            // Run two concurrent loops on the connection. One 
            // reads input from the console and then writes it to the connection 
            // with a stream writer. The other reads lines of input from the 
            // connection with a stream reader and then writes them to the console. 
            // Entering a blank line shuts down the write task after 
            // sending it to the server. The server then cleanly shuts down
            // the connection, which terminates the read task.

            var reads = Task.Run(async () => {
                // Initialize the stream reader over the connection.
                var reader = new StreamReader(relayConnection);
                var writer = Console.Out;
                do
                {
                    // Read a full line of UTF-8 text up to newline.
                    string line = await reader.ReadLineAsync();
                    // If the string is empty or null, you are done.
                    if (String.IsNullOrEmpty(line))
                        break;
                    // Write to the console.
                    await writer.WriteLineAsync(line);
                }
                while (true);
            });

            // Read from the console and write to the hybrid connection.
            var writes = Task.Run(async () => {
                var reader = Console.In;
                var writer = new StreamWriter(relayConnection) { AutoFlush = true };
                do
                {
                    // Read a line from the console.
                    string line = await reader.ReadLineAsync();
                    // Write the line out, also when it's empty.
                    await writer.WriteLineAsync(line);
                    // Quit when the line is empty.
                    if (String.IsNullOrEmpty(line))
                        break;
                }
                while (true);
            });

            // Wait for both tasks to finish.
            await Task.WhenAll(reads, writes);
            await relayConnection.CloseAsync(CancellationToken.None);
        }
    }
}

Nota

O código de exemplo neste artigo usa uma cadeia de conexão para autenticar em um namespace do Azure Relay para manter o tutorial simples. Recomendamos que você use a autenticação do Microsoft Entra ID em ambientes de produção, em vez de usar cadeias de conexão ou assinaturas de acesso compartilhado, que podem ser mais facilmente comprometidas. Para obter informações detalhadas e código de exemplo para usar a autenticação do Microsoft Entra ID, consulte Autenticar e autorizar um aplicativo com o Microsoft Entra ID para acessar entidades do Azure Relay e Autenticar uma identidade gerenciada com o Microsoft Entra ID para acessar os recursos do Azure Relay.

Executar as aplicações

Execute a aplicação de servidor.
Execute a aplicação cliente e introduza algum texto.
Certifique-se de que a consola da aplicação de servidor mostra o texto que foi introduzido na aplicação cliente.

Parabéns, você criou um aplicativo Hybrid Connections completo!

Próximos passos

Neste início rápido, você criou aplicativos de cliente e servidor .NET que usavam WebSockets para enviar e receber mensagens. O recurso Conexões Híbridas do Azure Relay também dá suporte ao uso de HTTP para enviar e receber mensagens. Para saber como usar HTTP com Conexões Híbridas de Retransmissão do Azure, consulte o Guia de início rápido HTTP.

Neste início rápido, você usou o .NET Framework para criar aplicativos cliente e servidor. Para saber como escrever aplicativos cliente e servidor usando o Node.js, consulte o início rápido Node.js WebSockets ou o início rápido HTTP Node.js.

Partilhar via

Introdução aos Websockets das Ligações Híbridas do Azure Relay em .NET

Pré-requisitos

Criar um espaço de nomes

Obter credenciais de gestão

Criar uma ligação híbrida

Criar uma aplicação de servidor (serviço de escuta)

Criar uma aplicação de consola

Adicionar o pacote NuGet de Reencaminhamento

Escrever código para receber mensagens

Criar uma aplicação cliente (remetente)

Criar uma aplicação de consola

Adicionar o pacote NuGet de Reencaminhamento

Escrever código para enviar mensagens

Executar as aplicações

Próximos passos

Comentários

Recursos adicionais