Compartilhar via

Tutorial: introdução às WebSockets de Conexões Híbridas de Retransmissão no .NET

  • Artigo

Neste Início Rápido, você cria aplicativos de remetente e destinatário de .NET que enviam e recebem mensagens por meio de WebSockets de Conexões Híbridas na Retransmissão do Azure. Para saber mais sobre a Retransmissão do Azure em geral, confira Retransmissão do Azure.

Neste início rápido, você segue os seguintes passos:

  1. Criar um namespace de Retransmissão usando o Portal do Azure.
  2. Crie uma conexão híbrida nesse namespace usando o Portal do Azure.
  3. Escreva um aplicativo de console do servidor (ouvinte) para receber mensagens.
  4. Escreva um aplicativo de console de cliente (remetente) para enviar mensagens.
  5. Execute aplicativos.

Pré-requisitos

Para concluir este tutorial, você precisará dos seguintes pré-requisitos:

Criar um namespace

  1. Entre no portal do Azure.

  2. Selecione Todos os serviços no menu esquerdo. Selecione Integração, procure por Retransmissões, passe o mouse sobre Retransmissões e clique em Criar.

    Captura de tela mostrando a seleção de Retransmissões –> botão Criar.

  3. Na página Criar namespace, siga estas etapas:

    1. Escolha uma assinatura do Azure na qual criar o namespace.

    2. Em Grupo de recursos, escolha um grupo de recursos existente no qual colocar o namespace ou crie um.

    3. Insira um nome para o namespace de Retransmissão.

    4. Selecione o país ou região no qual o namespace deve ser hospedado.

    5. Selecione Revisar + criar na parte inferior da página.

      Captura de tela mostrando a página Criar namespace.

    6. Na página Examinar + criar escolha Criar.

    7. Depois de alguns minutos, você verá a página de Retransmissão do namespace.

      Captura de tela mostrando a home page do namespace de Retransmissão.

Obter credenciais de gerenciamento

  1. Na página Retransmissão, selecione Políticas de acesso compartilhado no menu à esquerda.

  2. Na página Políticas de acesso compartilhado, selecione RootManageSharedAccessKey.

  3. Em Política de SAS: RootManageSharedAccessKey, clique no botão Copiar ao lado da opção Cadeia de Conexão Primária. Isso copiará a cadeia de conexão para a área de transferência para uso posterior. Cole esse valor no Bloco de notas ou em outro local temporário.

  4. Repita a etapa anterior para copiar e colar o valor de Chave primária para um local temporário para uso posterior.

    Captura de tela mostrando as informações de conexão do namespace de Retransmissão.

Criar uma Conexão Híbrida

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

  1. No menu à esquerda, em Entidades, selecione Conexões Híbridas e selecione + Conexão Híbrida.

    Captura de tela mostrando a página Conexões Híbridas.

  2. Na página Criar Conexão Híbrida, insira um nome para a conexão híbrida e selecione Criar.

    Captura de tela mostrando a página Criar Conexão Híbrida.

Criar um aplicativo de servidor (escuta)

No Visual Studio, grave um aplicativo de console em C# para escutar e receber mensagens da retransmissão.

Criar um aplicativo de console

N o Visual Studio, crie um novo projeto de Aplicativo de Console (.NET Framework).

Adicione o pacote NuGet de retransmissão

  1. Clique com o botão direito do mouse no projeto recém-criado e selecione Gerenciar Pacotes NuGet.
  2. Selecione Procurar e, em seguida, procure Microsoft.Azure.Relay. Nos resultados da pesquisa, selecione Retransmissão do Microsoft Azure.
  3. Selecione Instalar para concluir a instalação. Fechar a caixa de diálogo.

Gravar código para receber mensagens

  1. Na parte superior do arquivo Program.cs, substitua as instruções using existentes pelas instruções using a seguir:

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

  2. Adicione constantes à classe Program para os detalhes da conexão híbrida. Substitua os espaços reservados pelos valores obtidos quando você criou a conexão híbrida. Use o nome totalmente qualificado do namespace.

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

  3. 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);
}

  4. 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);
}

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

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

    O arquivo Program.cs concluído deve ter esta aparência:

    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 um aplicativo de cliente (remetente)

No Visual Studio, grave um aplicativo de console em C# para enviar mensagens à retransmissão.

Criar um aplicativo de console

N o Visual Studio, crie um novo projeto de Aplicativo de Console (.NET Framework).

Adicione o pacote NuGet de retransmissão

  1. Clique com o botão direito do mouse no projeto recém-criado e selecione Gerenciar Pacotes NuGet.
  2. Selecione Procurar e, em seguida, procure Microsoft.Azure.Relay. Nos resultados da pesquisa, selecione Retransmissão do Microsoft Azure.
  3. Selecione Instalar para concluir a instalação. Fechar a caixa de diálogo.

Gravar código para enviar mensagens

  1. Na parte superior do arquivo Program.cs, substitua as instruções using existentes pelas instruções using a seguir:

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

  2. Adicione constantes à classe Program para os detalhes da conexão híbrida. Substitua os espaços reservados pelos valores obtidos quando você criou a conexão híbrida. Use o nome totalmente qualificado do namespace.

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

  3. 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);
}

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

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

    O Program.cs deve ter esta aparência:

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

Observação

O código de exemplo neste artigo utiliza uma cadeia de conexão para autenticar em um namespace da Retransmissão do Azure a fim de 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 comprometidas mais facilmente. Para obter informações detalhadas e o código de exemplo para usar a autenticação do Microsoft Entra ID, veja Autenticar e autorizar um aplicativo com o Microsoft Entra ID para acessar entidades da Retransmissão do Azure e Autenticar uma identidade gerenciada com o Microsoft Entra ID para acessar os recursos da Retransmissão do Azure.

Executar os aplicativos

  1. Execute o aplicativo de servidor.

  2. Execute o aplicativo de cliente e insira algum texto.

  3. Verifique se o console do aplicativo para servidores exibe o texto inserido no aplicativo cliente.

    Janelas de console que testam os aplicativos cliente e servidor.

Conteúdo relacionado

Neste Início Rápido, você criou aplicativos de cliente e servidor do .NET que usavam WebSockets para enviar e receber mensagens. O recurso Conexões Híbridas de Retransmissão do Azure também dá suporte ao uso de HTTP para enviar e receber mensagens. Para saber como usar HTTP com as Conexões Híbridas de Retransmissão do Azure, consulte o Início Rápido do 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, confira o Início Rápido de WebSockets do Node.js ou o Início Rápido do HTTP Node.js.