Учебник. Начало работы с SignalR ASP.NET CoreTutorial: Get started with ASP.NET Core SignalR

В этом учебнике описаны основы создания приложения, работающего в режиме реального времени, с помощью SignalR.This tutorial teaches the basics of building a real-time app using SignalR. Вы научитесь:You learn how to:

  • Создайте веб-проект.Create a web project.
  • добавлять клиентскую библиотеку SignalR.Add the SignalR client library.
  • создавать концентратор SignalR.Create a SignalR hub.
  • настраивать проект для использования SignalR;Configure the project to use SignalR.
  • Добавлять код для отправки сообщений из любого клиента всем подключенным клиентам.Add code that sends messages from any client to all connected clients.

В итоге вы получите работающее приложение чата:At the end, you'll have a working chat app:

Пример приложения SignalR

Предварительные требованияPrerequisites

Создание проекта веб-приложенияCreate a web app project

  • В меню выберите Файл > Создать проект.From the menu, select File > New Project.

  • В диалоговом окне Создать проект выберите Веб-приложение ASP.NET Core и нажмите Далее.In the Create a new project dialog, select ASP.NET Core Web Application, and then select Next.

  • В диалоговом окне Настроить новый проект укажите имя проекта SignalRChat, а затем выберите Создать.In the Configure your new project dialog, name the project SignalRChat, and then select Create.

  • В диалоговом окне Создание веб-приложения ASP.NET Core выберите платформы .NET Core и 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.

  • Выберите Веб-приложение, чтобы создать проект, который использует Razor Pages, и нажмите Создать.Select Web Application to create a project that uses Razor Pages, and then select Create.

    Диалоговое окно создания проекта в Visual Studio

Добавление клиентской библиотеки SignalRAdd the SignalR client library

Серверная библиотека SignalR входит в состав общей платформы ASP.NET Core 3.0.The SignalR server library is included in the ASP.NET Core 3.0 shared framework. Клиентская библиотека JavaScript не добавляется в проект автоматически.The JavaScript client library isn't automatically included in the project. В рамках этого руководства вы будете использовать диспетчер библиотек (LibMan), чтобы получить клиентскую библиотеку из unpkg.For this tutorial, you use Library Manager (LibMan) to get the client library from unpkg. unpkg — это сеть доставки содержимого, которая позволяет доставить любое содержимое из npm (диспетчера пакетов Node.js).unpkg is a content delivery network (CDN)) that can deliver anything found in npm, the Node.js package manager.

  • В обозревателе решений щелкните проект правой кнопкой мыши и выберите Добавить > Клиентская библиотека.In Solution Explorer, right-click the project, and select Add > Client-Side Library.

  • В диалоговом окне Add Client-Side Library (Добавить клиентскую библиотеку) для параметра Поставщик выберите unpkg.In the Add Client-Side Library dialog, for Provider select unpkg.

  • Для параметра Библиотека введите @microsoft/signalr@latest.For Library, enter @microsoft/signalr@latest.

  • Щелкните Choose specific files (Выбрать определенные файлы), разверните папку dist/browser и выберите signalr.js и signalr.min.js.Select Choose specific files, expand the dist/browser folder, and select signalr.js and signalr.min.js.

  • В поле Целевое расположение укажите wwwroot/js/signalr/ и нажмите кнопку Установить.Set Target Location to wwwroot/js/signalr/, and select Install.

    Диалоговое окно добавления клиентской библиотеки — выбор библиотеки

    LibMan создает папку wwwroot/js/signalr и копирует в нее выбранные файлы.LibMan creates a wwwroot/js/signalr folder and copies the selected files to it.

Создание концентратора SignalRCreate a SignalR hub

hub — это класс, который служит в качестве конвейера высокого уровня для обработки взаимодействия между клиентом и сервером.A hub is a class that serves as a high-level pipeline that handles client-server communication.

  • В папке проекта SignalRChat создайте папку Hubs.In the SignalRChat project folder, create a Hubs folder.

  • В папке Hubs создайте файл ChatHub.cs со следующим кодом: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);
            }
        }
    }
    

    Класс ChatHub наследуется от класса SignalR Hub.The ChatHub class inherits from the SignalR Hub class. Класс Hub управляет подключениями, группами и обменом сообщениями.The Hub class manages connections, groups, and messaging.

    Метод SendMessage может вызываться подключенным клиентом, чтобы отправить сообщение всем клиентам.The SendMessage method can be called by a connected client to send a message to all clients. Далее в этом учебника показан клиентский код JavaScript, который вызывает метод.JavaScript client code that calls the method is shown later in the tutorial. Код SignalR является асинхронным, поэтому обеспечивает максимальную масштабируемость.SignalR code is asynchronous to provide maximum scalability.

Настройка SignalRConfigure SignalR

Сервер SignalR должен быть настроен для передачи запросов SignalR к SignalR.The SignalR server must be configured to pass SignalR requests to SignalR.

  • Добавьте следующий выделенный код в файл 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");
                });
            }
        }
    }
    

    В результате SignalR будет добавлен в системы внедрения зависимостей и маршрутизации ASP.NET Core.These changes add SignalR to the ASP.NET Core dependency injection and routing systems.

Добавление клиентского кода SignalRAdd SignalR client code

  • Замените содержимое в файле Pages\Index.cshtml следующим кодом: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>
    

    Предыдущий код:The preceding code:

    • Создает текстовые поля для имени и текста сообщения и кнопку отправки.Creates text boxes for name and message text, and a submit button.
    • Создает список с id="messagesList" для отображения сообщений, полученных от концентратора SignalR.Creates a list with id="messagesList" for displaying messages that are received from the SignalR hub.
    • Содержит ссылки на скрипты для SignalR и код приложения chat.js, который создается в следующем шаге.Includes script references to SignalR and the chat.js application code that you create in the next step.
  • В папке wwwroot/js создайте файл chat.js со следующим кодом: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();
    });
    

    Предыдущий код:The preceding code:

    • Создает и запускает подключение.Creates and starts a connection.
    • Добавляет к кнопке отправки обработчик, который отправляет сообщения в концентратор.Adds to the submit button a handler that sends messages to the hub.
    • Добавляет к объекту подключения обработчик, который получает сообщения из концентратора и добавляет их в список.Adds to the connection object a handler that receives messages from the hub and adds them to the list.

Запуск приложенияRun the app

  • Нажмите клавиши CTRL+F5, чтобы запустить приложение без отладки.Press CTRL+F5 to run the app without debugging.
  • Скопируйте URL-адрес из адресной строки, откройте другой экземпляр или вкладку браузера и вставьте URL-адрес в адресную строку.Copy the URL from the address bar, open another browser instance or tab, and paste the URL in the address bar.

  • Выберите любой браузер, введите имя и сообщение и нажмите кнопку Отправить сообщение.Choose either browser, enter a name and message, and select the Send Message button.

    Имя и сообщение отображаются на обеих страницах мгновенно.The name and message are displayed on both pages instantly.

    Пример приложения SignalR

Совет

  • Если приложение не работает, откройте средства разработчика для браузера (F12) и перейдите в консоль.If the app doesn't work, open your browser developer tools (F12) and go to the console. Вы можете увидеть ошибки, связанные с вашим кодом HTML и JavaScript.You might see errors related to your HTML and JavaScript code. Предположим, вы поместили signalr.js не в ту папку, которую указали.For example, suppose you put signalr.js in a different folder than directed. В этом случае ссылка на этот файл не будет работать, и вы увидите сообщение об ошибке 404 в консоли.In that case the reference to that file won't work and you'll see a 404 error in the console. ошибка: signalr.js не найденsignalr.js not found error

  • Если возникает ошибка ERR_SPDY_INADEQUATE_TRANSPORT_SECURITY в Chrome, выполните эти команды, чтобы обновить сертификат разработки: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
    

В этом учебнике описаны основы создания приложения, работающего в режиме реального времени, с помощью SignalR.This tutorial teaches the basics of building a real-time app using SignalR. Вы научитесь:You learn how to:

  • Создайте веб-проект.Create a web project.
  • добавлять клиентскую библиотеку SignalR.Add the SignalR client library.
  • создавать концентратор SignalR.Create a SignalR hub.
  • настраивать проект для использования SignalR;Configure the project to use SignalR.
  • Добавлять код для отправки сообщений из любого клиента всем подключенным клиентам.Add code that sends messages from any client to all connected clients.
    В итоге вы получите приложение для работы с чатом: Пример приложения SignalR.At the end, you'll have a working chat app: SignalR sample app

Предварительные требованияPrerequisites

Предупреждение

Если вы используете Visual Studio 2017, см. обсуждение dotnet/sdk issue #3124 для получения сведений о версиях пакета SDK для .NET Core, которые не работают с 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.

Создайте веб-проект.Create a web project

  • В меню выберите Файл > Создать проект.From the menu, select File > New Project.

  • В диалоговом окне Новый проект выберите Установленные > Visual C# > Веб > Веб-приложение ASP.NET Core.In the New Project dialog, select Installed > Visual C# > Web > ASP.NET Core Web Application. Назовите проект SignalRChat.Name the project SignalRChat.

    Диалоговое окно создания проекта в Visual Studio

  • Выберите Веб-приложение, чтобы создать проект, который использует Razor Pages.Select Web Application to create a project that uses Razor Pages.

  • Выберите целевую платформу .NET Core, ASP.NET Core 2.2 и нажмите кнопку ОК.Select a target framework of .NET Core, select ASP.NET Core 2.2, and click OK.

    Диалоговое окно создания проекта в Visual Studio

Добавление клиентской библиотеки SignalRAdd the SignalR client library

Библиотека сервера SignalR входит в состав метапакета Microsoft.AspNetCore.App.The SignalR server library is included in the Microsoft.AspNetCore.App metapackage. Клиентская библиотека JavaScript не добавляется в проект автоматически.The JavaScript client library isn't automatically included in the project. В рамках этого руководства вы будете использовать диспетчер библиотек (LibMan), чтобы получить клиентскую библиотеку из unpkg.For this tutorial, you use Library Manager (LibMan) to get the client library from unpkg. unpkg — это сеть доставки содержимого, которая позволяет доставить любое содержимое из npm (диспетчера пакетов Node.js).unpkg is a content delivery network (CDN)) that can deliver anything found in npm, the Node.js package manager.

  • В обозревателе решений щелкните проект правой кнопкой мыши и выберите Добавить > Клиентская библиотека.In Solution Explorer, right-click the project, and select Add > Client-Side Library.

  • В диалоговом окне Add Client-Side Library (Добавить клиентскую библиотеку) для параметра Поставщик выберите unpkg.In the Add Client-Side Library dialog, for Provider select unpkg.

  • В поле Библиотека введите @microsoft/signalr@3 и выберите последнюю версию, но не предварительную.For Library, enter @microsoft/signalr@3, and select the latest version that isn't preview.

    Диалоговое окно добавления клиентской библиотеки — выбор библиотеки

  • Щелкните Choose specific files (Выбрать определенные файлы), разверните папку dist/browser и выберите signalr.js и signalr.min.js.Select Choose specific files, expand the dist/browser folder, and select signalr.js and signalr.min.js.

  • В поле Целевое расположение укажите wwwroot/lib/signalr/ и нажмите кнопку Установить.Set Target Location to wwwroot/lib/signalr/, and select Install.

    Диалоговое окно добавления клиентской библиотеки — выбор файлов и назначения

    LibMan создает папку wwwroot/lib/signalr и копирует в нее выбранные файлы.LibMan creates a wwwroot/lib/signalr folder and copies the selected files to it.

Создание концентратора SignalRCreate a SignalR hub

hub — это класс, который служит в качестве конвейера высокого уровня для обработки взаимодействия между клиентом и сервером.A hub is a class that serves as a high-level pipeline that handles client-server communication.

  • В папке проекта SignalRChat создайте папку Hubs.In the SignalRChat project folder, create a Hubs folder.

  • В папке Hubs создайте файл ChatHub.cs со следующим кодом: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);
            }
        }
    }
    

    Класс ChatHub наследуется от класса SignalR Hub.The ChatHub class inherits from the SignalR Hub class. Класс Hub управляет подключениями, группами и обменом сообщениями.The Hub class manages connections, groups, and messaging.

    Метод SendMessage может вызываться подключенным клиентом, чтобы отправить сообщение всем клиентам.The SendMessage method can be called by a connected client to send a message to all clients. Далее в этом учебника показан клиентский код JavaScript, который вызывает метод.JavaScript client code that calls the method is shown later in the tutorial. Код SignalR является асинхронным, поэтому обеспечивает максимальную масштабируемость.SignalR code is asynchronous to provide maximum scalability.

Настройка SignalRConfigure SignalR

Сервер SignalR должен быть настроен для передачи запросов SignalR к SignalR.The SignalR server must be configured to pass SignalR requests to SignalR.

  • Добавьте следующий выделенный код в файл 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();
            }
        }
    }
    

    В результате SignalR будет добавлен в систему внедрения зависимостей ASP.NET Core и конвейер ПО промежуточного слоя.These changes add SignalR to the ASP.NET Core dependency injection system and the middleware pipeline.

Добавление клиентского кода SignalRAdd SignalR client code

  • Замените содержимое в файле Pages\Index.cshtml следующим кодом: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>
    

    Предыдущий код:The preceding code:

    • Создает текстовые поля для имени и текста сообщения и кнопку отправки.Creates text boxes for name and message text, and a submit button.
    • Создает список с id="messagesList" для отображения сообщений, полученных от концентратора SignalR.Creates a list with id="messagesList" for displaying messages that are received from the SignalR hub.
    • Содержит ссылки на скрипты для SignalR и код приложения chat.js, который создается в следующем шаге.Includes script references to SignalR and the chat.js application code that you create in the next step.
  • В папке wwwroot/js создайте файл chat.js со следующим кодом: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();
    });
    

    Предыдущий код:The preceding code:

    • Создает и запускает подключение.Creates and starts a connection.
    • Добавляет к кнопке отправки обработчик, который отправляет сообщения в концентратор.Adds to the submit button a handler that sends messages to the hub.
    • Добавляет к объекту подключения обработчик, который получает сообщения из концентратора и добавляет их в список.Adds to the connection object a handler that receives messages from the hub and adds them to the list.

Запуск приложенияRun the app

  • Нажмите клавиши CTRL+F5, чтобы запустить приложение без отладки.Press CTRL+F5 to run the app without debugging.
  • Скопируйте URL-адрес из адресной строки, откройте другой экземпляр или вкладку браузера и вставьте URL-адрес в адресную строку.Copy the URL from the address bar, open another browser instance or tab, and paste the URL in the address bar.

  • Выберите любой браузер, введите имя и сообщение и нажмите кнопку Отправить сообщение.Choose either browser, enter a name and message, and select the Send Message button.

    Имя и сообщение отображаются на обеих страницах мгновенно.The name and message are displayed on both pages instantly.

    Пример приложения SignalR

Совет

Если приложение не работает, откройте средства разработчика для браузера (F12) и перейдите в консоль.If the app doesn't work, open your browser developer tools (F12) and go to the console. Вы можете увидеть ошибки, связанные с вашим кодом HTML и JavaScript.You might see errors related to your HTML and JavaScript code. Предположим, вы поместили signalr.js не в ту папку, которую указали.For example, suppose you put signalr.js in a different folder than directed. В этом случае ссылка на этот файл не будет работать, и вы увидите сообщение об ошибке 404 в консоли.In that case the reference to that file won't work and you'll see a 404 error in the console.
ошибка: signalr.js не найденsignalr.js not found error

Дополнительные ресурсыAdditional resources