Tutorial: introdução ao ASP.NET Core SignalRTutorial: Get started with ASP.NET Core SignalR

Este tutorial ensina as noções básicas da criação de um aplicativo em tempo real usando o SignalR.This tutorial teaches the basics of building a real-time app using SignalR. Você aprenderá como:You learn how to:

  • Crie um projeto Web.Create a web project.
  • Adicione a biblioteca de cliente SignalR.Add the SignalR client library.
  • Crie um hub de SignalR.Create a SignalR hub.
  • Configure o projeto a ser usado SignalR.Configure the project to use SignalR.
  • Adicione o código que envia mensagens de qualquer cliente para todos os clientes conectados.Add code that sends messages from any client to all connected clients.

No final, você terá um aplicativo de chat funcionando:At the end, you'll have a working chat app:

[! Parar. Aplicativo de exemplo não LOC (Signalr)]

PrerequisitesPrerequisites

Criar um projeto de aplicativo WebCreate a web app project

  • No menu, selecione Arquivo > Novo Projeto.From the menu, select File > New Project.

  • Na caixa de diálogo Criar novo projeto, selecione Aplicativo Web ASP.NET Core e depois selecione Avançar.In the Create a new project dialog, select ASP.NET Core Web Application, and then select Next.

  • Na caixa de diálogo Configurar seu novo projeto, nomeie o projeto SignalRChat e, em seguida, selecione Criar.In the Configure your new project dialog, name the project SignalRChat, and then select Create.

  • Na caixa de diálogo criar um novo aplicativo web ASP.NET Core , selecione .net Core e ASP.NET Core 3,0.In the Create a new ASP.NET Core web Application dialog, select .NET Core and ASP.NET Core 3.0.

  • Selecione Aplicativo Web para criar um projeto que usa Razor Pages e, em seguida, selecione Criar.Select Web Application to create a project that uses Razor Pages, and then select Create.

    Caixa de diálogo Novo Projeto no Visual Studio

Adicionar a biblioteca de cliente SignalRAdd the SignalR client library

A biblioteca do SignalR Server está incluída na estrutura compartilhada do ASP.NET Core 3,0.The SignalR server library is included in the ASP.NET Core 3.0 shared framework. A biblioteca de clientes do JavaScript não é incluída automaticamente no projeto.The JavaScript client library isn't automatically included in the project. Neste tutorial, você usará o LibMan (Library Manager) para obter a biblioteca de clientes de unpkg.For this tutorial, you use Library Manager (LibMan) to get the client library from unpkg. unpkg é uma CDN (rede de distribuição de conteúdo) que pode distribuir qualquer conteúdo do npm, o gerenciador de pacotes do Node.js.unpkg is a content delivery network (CDN)) that can deliver anything found in npm, the Node.js package manager.

  • No Gerenciador de Soluções, clique com o botão direito do mouse no projeto e selecione Adicionar > Biblioteca do Lado do Cliente.In Solution Explorer, right-click the project, and select Add > Client-Side Library.

  • Na caixa de diálogo Adicionar Biblioteca do Lado do Cliente, para Provedor, selecione unpkg.In the Add Client-Side Library dialog, for Provider select unpkg.

  • Para Biblioteca, insira @microsoft/signalr@latest.For Library, enter @microsoft/signalr@latest.

  • Selecione Escolher arquivos específicos, expanda a pasta distribuidor/navegador e selecione signalr.js e signalr.min.js.Select Choose specific files, expand the dist/browser folder, and select signalr.js and signalr.min.js.

  • Defina local de destino como wwwroot/js/signalr/ e selecione instalar.Set Target Location to wwwroot/js/signalr/, and select Install.

    Caixa de diálogo Adicionar Biblioteca do Lado do Cliente – selecionar biblioteca

    LibMan cria uma pasta wwwroot/js/signalr e copia os arquivos selecionados nela.LibMan creates a wwwroot/js/signalr folder and copies the selected files to it.

Criar um hub de SignalRCreate a SignalR hub

Um hub é uma classe que funciona como um pipeline de alto nível que lida com a comunicação entre cliente e servidor.A hub is a class that serves as a high-level pipeline that handles client-server communication.

  • Na pasta do projeto SignalRChat, crie uma pasta Hubs.In the SignalRChat project folder, create a Hubs folder.

  • Na pasta Hubs, crie um arquivo ChatHub.cs com o código a seguir:In the Hubs folder, create a ChatHub.cs file with the following code:

    using Microsoft.AspNetCore.SignalR;
    using System.Threading.Tasks;
    
    namespace SignalRChat.Hubs
    {
        public class ChatHub : Hub
        {
            public async Task SendMessage(string user, string message)
            {
                await Clients.All.SendAsync("ReceiveMessage", user, message);
            }
        }
    }
    

    A classe ChatHub herda da classe SignalR Hub.The ChatHub class inherits from the SignalR Hub class. A classe Hub gerencia conexões, grupos e sistemas de mensagens.The Hub class manages connections, groups, and messaging.

    O método SendMessage pode ser chamado por um cliente conectado para enviar uma mensagem a todos os clientes.The SendMessage method can be called by a connected client to send a message to all clients. O código cliente do JavaScript que chama o método é mostrado posteriormente no tutorial.JavaScript client code that calls the method is shown later in the tutorial. SignalR código é assíncrono para fornecer a escalabilidade máxima. code is asynchronous to provide maximum scalability.

Configurar SignalRConfigure SignalR

O servidor de SignalR deve ser configurado para passar SignalR solicitações para SignalR.The SignalR server must be configured to pass SignalR requests to SignalR.

  • Adicione o seguinte código realçado ao arquivo Startup.cs.Add the following highlighted code to the Startup.cs file.

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Threading.Tasks;
    using Microsoft.AspNetCore.Builder;
    using Microsoft.AspNetCore.Hosting;
    using Microsoft.AspNetCore.HttpsPolicy;
    using Microsoft.Extensions.Configuration;
    using Microsoft.Extensions.DependencyInjection;
    using Microsoft.Extensions.Hosting;
    using SignalRChat.Hubs;
    
    namespace SignalRChat
    {
        public class Startup
        {
            public Startup(IConfiguration configuration)
            {
                Configuration = configuration;
            }
    
            public IConfiguration Configuration { get; }
    
            // This method gets called by the runtime. Use this method to add services to the container.
            public void ConfigureServices(IServiceCollection services)
            {
                services.AddRazorPages();
                services.AddSignalR();
            }
    
            // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
            public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
            {
                if (env.IsDevelopment())
                {
                    app.UseDeveloperExceptionPage();
                }
                else
                {
                    app.UseExceptionHandler("/Error");
                    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
                    app.UseHsts();
                }
    
                app.UseHttpsRedirection();
                app.UseStaticFiles();
    
                app.UseRouting();
    
                app.UseAuthorization();
    
                app.UseEndpoints(endpoints =>
                {
                    endpoints.MapRazorPages();
                    endpoints.MapHub<ChatHub>("/chatHub");
                });
            }
        }
    }
    

    Essas alterações adicionam SignalR à injeção de dependência de ASP.NET Core e sistemas de roteamento.These changes add SignalR to the ASP.NET Core dependency injection and routing systems.

Adicionar SignalR código de clienteAdd SignalR client code

  • Substitua o conteúdo Pages\Index.cshtml pelo código a seguir:Replace the content in Pages\Index.cshtml with the following code:

    @page
        <div class="container">
            <div class="row">&nbsp;</div>
            <div class="row">
                <div class="col-2">User</div>
                <div class="col-4"><input type="text" id="userInput" /></div>
            </div>
            <div class="row">
                <div class="col-2">Message</div>
                <div class="col-4"><input type="text" id="messageInput" /></div>
            </div>
            <div class="row">&nbsp;</div>
            <div class="row">
                <div class="col-6">
                    <input type="button" id="sendButton" value="Send Message" />
                </div>
            </div>
        </div>
        <div class="row">
            <div class="col-12">
                <hr />
            </div>
        </div>
        <div class="row">
            <div class="col-6">
                <ul id="messagesList"></ul>
            </div>
        </div>
    <script src="~/js/signalr/dist/browser/signalr.js"></script>
    <script src="~/js/chat.js"></script>
    

    O código anterior:The preceding code:

    • Cria as caixas de texto para o nome e a mensagem de texto e um botão Enviar.Creates text boxes for name and message text, and a submit button.
    • Cria uma lista com id="messagesList" para exibir as mensagens que são recebidas do hub de SignalR.Creates a list with id="messagesList" for displaying messages that are received from the SignalR hub.
    • Inclui referências de script para SignalR e o código do aplicativo chat. js que você cria na próxima etapa.Includes script references to SignalR and the chat.js application code that you create in the next step.
  • Na pasta wwwroot/js, crie um arquivo chat.js com o código a seguir:In the wwwroot/js folder, create a chat.js file with the following code:

    "use strict";
    
    var connection = new signalR.HubConnectionBuilder().withUrl("/chatHub").build();
    
    //Disable send button until connection is established
    document.getElementById("sendButton").disabled = true;
    
    connection.on("ReceiveMessage", function (user, message) {
        var msg = message.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
        var encodedMsg = user + " says " + msg;
        var li = document.createElement("li");
        li.textContent = encodedMsg;
        document.getElementById("messagesList").appendChild(li);
    });
    
    connection.start().then(function () {
        document.getElementById("sendButton").disabled = false;
    }).catch(function (err) {
        return console.error(err.toString());
    });
    
    document.getElementById("sendButton").addEventListener("click", function (event) {
        var user = document.getElementById("userInput").value;
        var message = document.getElementById("messageInput").value;
        connection.invoke("SendMessage", user, message).catch(function (err) {
            return console.error(err.toString());
        });
        event.preventDefault();
    });
    

    O código anterior:The preceding code:

    • Cria e inicia uma conexão.Creates and starts a connection.
    • Adiciona no botão Enviar um manipulador que envia mensagens ao hub.Adds to the submit button a handler that sends messages to the hub.
    • Adiciona no objeto de conexão um manipulador que recebe mensagens do hub e as adiciona à lista.Adds to the connection object a handler that receives messages from the hub and adds them to the list.

Executar o aplicativoRun the app

  • Pressione CTRL + F5 para executar o aplicativo sem depuração.Press CTRL+F5 to run the app without debugging.
  • Copie a URL da barra de endereços, abra outra instância ou guia do navegador e cole a URL na barra de endereços.Copy the URL from the address bar, open another browser instance or tab, and paste the URL in the address bar.

  • Escolha qualquer navegador, insira um nome e uma mensagem e selecione o botão Enviar Mensagem.Choose either browser, enter a name and message, and select the Send Message button.

    O nome e a mensagem são exibidos em ambas as páginas instantaneamente.The name and message are displayed on both pages instantly.

    [! Parar. Aplicativo de exemplo não LOC (Signalr)]

Dica

  • Se o aplicativo não funcionar, abra as ferramentas para desenvolvedores do navegador (F12) e acesse o console.If the app doesn't work, open your browser developer tools (F12) and go to the console. Você pode encontrar erros relacionados ao código HTML e JavaScript.You might see errors related to your HTML and JavaScript code. Por exemplo, suponha que você coloque signalr.js em uma pasta diferente daquela direcionada.For example, suppose you put signalr.js in a different folder than directed. Nesse caso, a referência a esse arquivo não funcionará e ocorrerá um erro 404 no console.In that case the reference to that file won't work and you'll see a 404 error in the console. Erro de signalr.js não encontradosignalr.js not found error

  • Se você receber o erro ERR_SPDY_INADEQUATE_TRANSPORT_SECURITY no Chrome, execute estes comandos para atualizar seu certificado de desenvolvimento:If you get the error ERR_SPDY_INADEQUATE_TRANSPORT_SECURITY in Chrome, run these commands to update your development certificate:

    dotnet dev-certs https --clean
    dotnet dev-certs https --trust
    

Este tutorial ensina as noções básicas da criação de um aplicativo em tempo real usando o SignalR.This tutorial teaches the basics of building a real-time app using SignalR. Você aprenderá como:You learn how to:

  • Crie um projeto Web.Create a web project.
  • Adicione a biblioteca de cliente SignalR.Add the SignalR client library.
  • Crie um hub de SignalR.Create a SignalR hub.
  • Configure o projeto a ser usado SignalR.Configure the project to use SignalR.
  • Adicione o código que envia mensagens de qualquer cliente para todos os clientes conectados.Add code that sends messages from any client to all connected clients.
    No final, você terá um aplicativo de chat em funcionamento: [! Parar. Não-LOC (Signalr)] aplicativo de exemploAt the end, you'll have a working chat app: SignalR sample app

PrerequisitesPrerequisites

Aviso

Se você usar o Visual Studio 2017, confira problema de dotnet/sdk nº 3124 para obter informações sobre as versões do SDK do .NET Core que não funcionam com o Visual Studio.If you use Visual Studio 2017, see dotnet/sdk issue #3124 for information about .NET Core SDK versions that don't work with Visual Studio.

Criar um projeto WebCreate a web project

  • No menu, selecione Arquivo > Novo Projeto.From the menu, select File > New Project.

  • Na caixa de diálogo Novo Projeto, selecione Instalado > Visual C# > Web > Aplicativo Web ASP.NET Core.In the New Project dialog, select Installed > Visual C# > Web > ASP.NET Core Web Application. Dê ao projeto o nome de SignalRChat.Name the project SignalRChat.

    Caixa de diálogo Novo Projeto no Visual Studio

  • Selecione Aplicativo Web para criar um projeto que usa Razor Pages.Select Web Application to create a project that uses Razor Pages.

  • Selecione uma estrutura de destino do .NET Core, selecione ASP.NET Core 2.2 e clique em OK.Select a target framework of .NET Core, select ASP.NET Core 2.2, and click OK.

    Caixa de diálogo Novo Projeto no Visual Studio

Adicionar a biblioteca de cliente SignalRAdd the SignalR client library

A biblioteca do SignalR Server está incluída no metapacote do Microsoft.AspNetCore.App.The SignalR server library is included in the Microsoft.AspNetCore.App metapackage. A biblioteca de clientes do JavaScript não é incluída automaticamente no projeto.The JavaScript client library isn't automatically included in the project. Neste tutorial, você usará o LibMan (Library Manager) para obter a biblioteca de clientes de unpkg.For this tutorial, you use Library Manager (LibMan) to get the client library from unpkg. unpkg é uma CDN (rede de distribuição de conteúdo) que pode distribuir qualquer conteúdo do npm, o gerenciador de pacotes do Node.js.unpkg is a content delivery network (CDN)) that can deliver anything found in npm, the Node.js package manager.

  • No Gerenciador de Soluções, clique com o botão direito do mouse no projeto e selecione Adicionar > Biblioteca do Lado do Cliente.In Solution Explorer, right-click the project, and select Add > Client-Side Library.

  • Na caixa de diálogo Adicionar Biblioteca do Lado do Cliente, para Provedor, selecione unpkg.In the Add Client-Side Library dialog, for Provider select unpkg.

  • Para Biblioteca, insira @aspnet/signalr@1 e selecione a versão mais recente que não seja uma versão prévia.For Library, enter @aspnet/signalr@1, and select the latest version that isn't preview.

    Caixa de diálogo Adicionar Biblioteca do Lado do Cliente – selecionar biblioteca

  • Selecione Escolher arquivos específicos, expanda a pasta distribuidor/navegador e selecione signalr.js e signalr.min.js.Select Choose specific files, expand the dist/browser folder, and select signalr.js and signalr.min.js.

  • Defina Localização de Destino como wwwroot/lib/signalr/ e selecione Instalar.Set Target Location to wwwroot/lib/signalr/, and select Install.

    Caixa de diálogo Adicionar Biblioteca do Lado do Cliente – selecionar arquivos e destino

    O LibMan cria uma pasta wwwroot/lib/signalr e copia os arquivos selecionados para ela.LibMan creates a wwwroot/lib/signalr folder and copies the selected files to it.

Criar um hub de SignalRCreate a SignalR hub

Um hub é uma classe que funciona como um pipeline de alto nível que lida com a comunicação entre cliente e servidor.A hub is a class that serves as a high-level pipeline that handles client-server communication.

  • Na pasta do projeto SignalRChat, crie uma pasta Hubs.In the SignalRChat project folder, create a Hubs folder.

  • Na pasta Hubs, crie um arquivo ChatHub.cs com o código a seguir:In the Hubs folder, create a ChatHub.cs file with the following code:

    using Microsoft.AspNetCore.SignalR;
    using System.Threading.Tasks;
    
    namespace SignalRChat.Hubs
    {
        public class ChatHub : Hub
        {
            public async Task SendMessage(string user, string message)
            {
                await Clients.All.SendAsync("ReceiveMessage", user, message);
            }
        }
    }
    

    A classe ChatHub herda da classe SignalR Hub.The ChatHub class inherits from the SignalR Hub class. A classe Hub gerencia conexões, grupos e sistemas de mensagens.The Hub class manages connections, groups, and messaging.

    O método SendMessage pode ser chamado por um cliente conectado para enviar uma mensagem a todos os clientes.The SendMessage method can be called by a connected client to send a message to all clients. O código cliente do JavaScript que chama o método é mostrado posteriormente no tutorial.JavaScript client code that calls the method is shown later in the tutorial. SignalR código é assíncrono para fornecer a escalabilidade máxima. code is asynchronous to provide maximum scalability.

Configurar SignalRConfigure SignalR

O servidor de SignalR deve ser configurado para passar SignalR solicitações para SignalR.The SignalR server must be configured to pass SignalR requests to SignalR.

  • Adicione o seguinte código realçado ao arquivo Startup.cs.Add the following highlighted code to the Startup.cs file.

    using Microsoft.AspNetCore.Builder;
    using Microsoft.AspNetCore.Hosting;
    using Microsoft.AspNetCore.Http;
    using Microsoft.AspNetCore.Mvc;
    using Microsoft.Extensions.Configuration;
    using Microsoft.Extensions.DependencyInjection;
    using SignalRChat.Hubs;
    
    namespace SignalRChat
    {
        public class Startup
        {
            public Startup(IConfiguration configuration)
            {
                Configuration = configuration;
            }
    
            public IConfiguration Configuration { get; }
    
            // This method gets called by the runtime. Use this method to add services to the container.
            public void ConfigureServices(IServiceCollection services)
            {
                services.Configure<CookiePolicyOptions>(options =>
                {
                    // This lambda determines whether user consent for non-essential cookies is needed for a given request.
                    options.CheckConsentNeeded = context => true;
                    options.MinimumSameSitePolicy = SameSiteMode.None;
                });
    
    
                services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
    
                services.AddSignalR();
            }
    
            // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
            public void Configure(IApplicationBuilder app, IHostingEnvironment env)
            {
                if (env.IsDevelopment())
                {
                    app.UseDeveloperExceptionPage();
                }
                else
                {
                    app.UseExceptionHandler("/Error");
                    app.UseHsts();
                }
    
                app.UseHttpsRedirection();
                app.UseStaticFiles();
                app.UseCookiePolicy();
                app.UseSignalR(routes =>
                {
                    routes.MapHub<ChatHub>("/chatHub");
                });
                app.UseMvc();
            }
        }
    }
    

    Essas alterações adicionam SignalR ao sistema de injeção de dependência ASP.NET Core e ao pipeline de middleware.These changes add SignalR to the ASP.NET Core dependency injection system and the middleware pipeline.

Adicionar SignalR código de clienteAdd SignalR client code

  • Substitua o conteúdo Pages\Index.cshtml pelo código a seguir:Replace the content in Pages\Index.cshtml with the following code:

    @page
    <div class="container">
        <div class="row">&nbsp;</div>
        <div class="row">
            <div class="col-6">&nbsp;</div>
            <div class="col-6">
                User..........<input type="text" id="userInput" />
                <br />
                Message...<input type="text" id="messageInput" />
                <input type="button" id="sendButton" value="Send Message" />
            </div>
        </div>
        <div class="row">
            <div class="col-12">
                <hr />
            </div>
        </div>
        <div class="row">
            <div class="col-6">&nbsp;</div>
            <div class="col-6">
                <ul id="messagesList"></ul>
            </div>
        </div>
    </div>
    <script src="~/lib/signalr/dist/browser/signalr.js"></script>
    <script src="~/js/chat.js"></script>
    

    O código anterior:The preceding code:

    • Cria as caixas de texto para o nome e a mensagem de texto e um botão Enviar.Creates text boxes for name and message text, and a submit button.
    • Cria uma lista com id="messagesList" para exibir as mensagens que são recebidas do hub de SignalR.Creates a list with id="messagesList" for displaying messages that are received from the SignalR hub.
    • Inclui referências de script para SignalR e o código do aplicativo chat. js que você cria na próxima etapa.Includes script references to SignalR and the chat.js application code that you create in the next step.
  • Na pasta wwwroot/js, crie um arquivo chat.js com o código a seguir:In the wwwroot/js folder, create a chat.js file with the following code:

    "use strict";
    
    var connection = new signalR.HubConnectionBuilder().withUrl("/chatHub").build();
    
    //Disable send button until connection is established
    document.getElementById("sendButton").disabled = true;
    
    connection.on("ReceiveMessage", function (user, message) {
        var msg = message.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
        var encodedMsg = user + " says " + msg;
        var li = document.createElement("li");
        li.textContent = encodedMsg;
        document.getElementById("messagesList").appendChild(li);
    });
    
    connection.start().then(function(){
        document.getElementById("sendButton").disabled = false;
    }).catch(function (err) {
        return console.error(err.toString());
    });
    
    document.getElementById("sendButton").addEventListener("click", function (event) {
        var user = document.getElementById("userInput").value;
        var message = document.getElementById("messageInput").value;
        connection.invoke("SendMessage", user, message).catch(function (err) {
            return console.error(err.toString());
        });
        event.preventDefault();
    });
    

    O código anterior:The preceding code:

    • Cria e inicia uma conexão.Creates and starts a connection.
    • Adiciona no botão Enviar um manipulador que envia mensagens ao hub.Adds to the submit button a handler that sends messages to the hub.
    • Adiciona no objeto de conexão um manipulador que recebe mensagens do hub e as adiciona à lista.Adds to the connection object a handler that receives messages from the hub and adds them to the list.

Executar o aplicativoRun the app

  • Pressione CTRL + F5 para executar o aplicativo sem depuração.Press CTRL+F5 to run the app without debugging.
  • Copie a URL da barra de endereços, abra outra instância ou guia do navegador e cole a URL na barra de endereços.Copy the URL from the address bar, open another browser instance or tab, and paste the URL in the address bar.

  • Escolha qualquer navegador, insira um nome e uma mensagem e selecione o botão Enviar Mensagem.Choose either browser, enter a name and message, and select the Send Message button.

    O nome e a mensagem são exibidos em ambas as páginas instantaneamente.The name and message are displayed on both pages instantly.

    [! Parar. Aplicativo de exemplo não LOC (Signalr)]

Dica

Se o aplicativo não funcionar, abra as ferramentas para desenvolvedores do navegador (F12) e acesse o console.If the app doesn't work, open your browser developer tools (F12) and go to the console. Você pode encontrar erros relacionados ao código HTML e JavaScript.You might see errors related to your HTML and JavaScript code. Por exemplo, suponha que você coloque signalr.js em uma pasta diferente daquela direcionada.For example, suppose you put signalr.js in a different folder than directed. Nesse caso, a referência a esse arquivo não funcionará e ocorrerá um erro 404 no console.In that case the reference to that file won't work and you'll see a 404 error in the console.
Erro de signalr.js não encontradosignalr.js not found error

Recursos adicionaisAdditional resources