WebSockets WebSockets

Протокол WebSocket предоставляет механизм быстрого и безопасного двустороннего взаимодействия между клиентом и сервером через HTTP(S) и поддерживает и UTF-8, и двоичные сообщения. WebSockets provide a mechanism for fast, secure, two-way communication between a client and a server over the web using HTTP(S), and supporting both UTF-8 and binary messages.

В протоколе WebSocket данные немедленно передаются через полнодуплексное односокетное подключение, при этом сообщения могут отправляться и приниматься с обеих конечных точек в реальном времени. Under the WebSocket Protocol, data is transferred immediately over a full-duplex single socket connection, allowing messages to be sent and received from both endpoints in real time. WebSocket отлично подходит для многопользовательских игр (в режиме реального времени и пошаговом режиме), мгновенных уведомлений социальных сетей, отображения новой информации о курсе акций или погоде, а также других приложений, для которых необходима безопасная и быстрая передача данных. WebSockets are ideal for use in multiplayer gaming (both real-time and turn-based), instant social network notifications, up-to-date displays of stock or weather information, and other apps requiring secure and fast data transfer.

Чтобы установить подключение WebSocket, клиент и сервер обмениваются специальным подтверждением, основанным на протоколе HTTP. To establish a WebSocket connection, a specific, HTTP-based handshake is exchanged between the client and the server. В случае успешного выполнения протокол прикладного уровня «обновляется» с HTTP до WebSocket, используя ранее установленное соединение TCP. If successful, the application-layer protocol is «upgraded» from HTTP to WebSockets, using the previously established TCP connection. После этого HTTP больше не задействован. Данные могут быть отправлены или получены с использованием протокола WebSocket любой конечной точкой в любое время до завершения подключения WebSocket. Once this occurs, HTTP is completely out of the picture; data can be sent or received using the WebSocket protocol by both endpoints, until the WebSocket connection is closed.

Примечание. Клиент не может использовать WebSocket для передачи данных, если сервер не использует протокол WebSocket. Note A client cannot use WebSockets to transfer data unless the server also uses the WebSocket protocol. Если сервер не поддерживает WebSocket, вам придется использовать другой метод передачи данных. If the server does not support WebSockets, then you must use another method of data transfer.

Универсальная платформа Windows (UWP) поддерживает использование WebSocket как клиентами, так и серверами. The Universal Windows Platform (UWP) provides support for both client and server use of WebSockets. Пространство имен Windows.Networking.Sockets определяет два класса WebSocket для использования клиентами —MessageWebSocket и StreamWebSocket. The Windows.Networking.Sockets namespace defines two WebSocket classes for use by clients—MessageWebSocket, and StreamWebSocket. Вот сравнение этих двух классов WebSocket. Here’s a comparison of these two WebSocket classes.

MessageWebSocket MessageWebSocket	StreamWebSocket StreamWebSocket
Все сообщение WebSocket считывается или записывается за одну операцию. An entire WebSocket message is read/written in a single operation.	Части сообщения могут считываться в ходе каждой из операций чтения. Sections of a message can be read with each read operation.
Подходит, если сообщения не очень большие. Suitable when messages are not very large.	Подходит для передачи очень больших файлов (например, фото или видео). Suitable when very large files (such as photos or videos) are being transferred.
Поддерживает двоичные сообщения и сообщения в кодировке UTF-8. Supports both UTF-8 and binary messages.	Поддерживает только двоичные сообщения. Supports only binary messages.
Аналогичны UDP или сокету датаграмм (предназначены для частых, небольших сообщений), но обладают надежностью, гарантированным порядком пакетов и контролем перегрузки, присущими TCP. Similar to a UDP or datagram socket (in the sense of being intended for frequent, small messages), but with TCP’s reliability, packet order guarantees, and congestion control.	Аналогичны TCP или сокету потока. Similar to a TCP or stream socket.

Защита подключения с помощью TLS/SSL Secure your connection with TLS/SSL

В большинстве случаев необходимо использовать безопасное подключение WebSocket, чтобы зашифровать отправляемые и получаемые данные. In most cases, you’ll want to use a secure WebSocket connection so that the data you send and receive is encrypted. Это также увеличивает шансы успешного подключения, так как многие посредники, такие как брандмауэры и прокси-серверы, отклоняют незашифрованные подключения WebSocket. This will also increase the chances that your connection will succeed, because many intermediaries such as firewalls and proxies reject unencrypted WebSocket connections. Протокол WebSocket определяет эти две схемы URI. The WebSocket protocol defines these two URI schemes.

Схема универсального кода ресурса (URI) URI scheme	Цель Purpose
wss: wss:	Используется для защищенных соединений, которые должны быть зашифрованы. Use for secure connections that should be encrypted.
ws: ws:	Используется для незашифрованных соединений. Use for unencrypted connections.

Чтобы зашифровать подключение WebSocket, воспользуйтесь схемой URI wss: . To encrypt your WebSocket connection, use the wss: URI scheme. Ниже приведен пример. Here’s an example.

Использование сокета MessageWebSocket для подключения Use MessageWebSocket to connect

MessageWebSocket позволяет одной операцией считать и записать все сообщение WebSocket. MessageWebSocket allows an entire WebSocket message to be read/written in a single operation. Следовательно, его можно использовать, если сообщения небольшие. Consequently, it’s suitable when messages are not very large. Этот класс поддерживает двоичные сообщения и сообщения в кодировке UTF-8. The class supports both UTF-8 and binary messages.

В примере кода ниже эхо-сервер WebSocket.org — это служба, которая возвращает отправителю любое отправленное ей сообщение. The example code below uses the WebSocket.org echo server—a service that echoes back to the sender any message sent to it.

Обработка событий MessageWebSocket.MessageReceived и MessageWebSocket.Closed Handle the MessageWebSocket.MessageReceived and MessageWebSocket.Closed events

Как показано в приведенном выше примере, до установки подключения и отправки данных с помощью MessageWebSocket необходимо подписаться на события MessageWebSocket.MessageReceived и MessageWebSocket.Closed. As shown in the example above, before establishing a connection and sending data with a MessageWebSocket, you should subscribe to the MessageWebSocket.MessageReceived and MessageWebSocket.Closed events.

Событие MessageReceived создается при получении данных. MessageReceived is raised when data is received. Доступ к данным осуществляется через MessageWebSocketMessageReceivedEventArgs. The data can be accessed via MessageWebSocketMessageReceivedEventArgs. Событие Closed создается, когда клиент или сервер закрывает сокет. Closed is raised when the client or the server closes the socket.

Отправка данных в MessageWebSocket Send data on a MessageWebSocket

После установки подключения можно отправлять данные на сервер. Once a connection is established, you can send data to the server. Это можно сделать с помощью свойства MessageWebSocket.OutputStream и DataWriter для записи данных. You do this by using the MessageWebSocket.OutputStream property, and a DataWriter, to write the data.

Примечание. DataWriter становится владельцем потока вывода. Note The DataWriter takes ownership of the output stream. Когда DataWriter выходит за пределы области, если к нему прикреплен поток вывода, DataWriter освобождает поток вывода. When the DataWriter goes out of scope, if the output stream is attached to it, the DataWriter deallocates the output stream. После этого все последующие попытки использовать поток вывода будут неудачными со значением HRESULT 0x80000013. After that, subsequent attempts to use the output stream fail with an HRESULT value of 0x80000013. Но можно вызвать метод DataWriter.DetachStream, чтобы отсоединить поток вывода от DataWriter и вернуть владение потоком событию MessageWebSocket. But you can call DataWriter.DetachStream to detach the output stream from the DataWriter and return ownership of the stream to the MessageWebSocket.

Использование StreamWebSocket для подключения Use StreamWebSocket to connect

StreamWebSocket позволяет считывать части сообщения при каждой операции чтения. StreamWebSocket allows sections of a message to be read with each read operation. Следовательно, он подходит для передачи очень больших файлов (например, фото или видео). Consequently, it’s suitable when very large files (such as photos or videos) are being transferred. Этот класс поддерживает только двоичные сообщения. The class supports only binary messages.

В примере кода ниже эхо-сервер WebSocket.org — это служба, которая возвращает отправителю любое отправленное ей сообщение. The example code below uses the WebSocket.org echo server—a service that echoes back to the sender any message sent to it.

Обработка события StreamWebSocket.Closed Handle the StreamWebSocket.Closed event

Прежде чем устанавливать подключение и отправлять данные с помощью StreamWebSocket, необходимо подписаться на событие StreamWebSocket.Closed. Before establishing a connection and sending data with a StreamWebSocket, you should subscribe to the StreamWebSocket.Closed event. Событие Closed создается, когда клиент или сервер закрывает сокет. Closed is raised when the client or the server closes the socket.

Отправка данных в StreamWebSocket Send data on a StreamWebSocket

После установки подключения можно отправлять данные на сервер. Once a connection is established, you can send data to the server. Это можно сделать с помощью свойства StreamWebSocket.OutputStream и DataWriter для записи данных. You do this by using the StreamWebSocket.OutputStream property, and a DataWriter, to write the data.

Примечание. Если вы хотите записать больше данных в один сокет, не забудьте вызвать метод DataWriter.DetachStream, чтобы отсоединить поток вывода от DataWriter до того, как DataWriter выйдет за пределы области. Note If you want to write more data on the same socket, then be sure to call DataWriter.DetachStream to detach the output stream from the DataWriter before the DataWriter goes out of scope. В результате владельцем потока становится MessageWebSocket. This returns ownership of the stream to the MessageWebSocket.

Получение данных в StreamWebSocket Receive data on a StreamWebSocket

Дополнительные параметры для MessageWebSocket и StreamWebSocket Advanced options for MessageWebSocket and StreamWebSocket

Прежде чем устанавливать подключение, можно задать дополнительные параметры в сокете, задав свойства в MessageWebSocketControl или StreamWebSocketControl. Before establishing a connection, you can set advanced options on a socket by setting properties on either MessageWebSocketControl or StreamWebSocketControl. Вы осуществляете доступ к экземпляру этих классов из самого объекта сокета через его свойство MessageWebSocket.Control или StreamWebSocket.Control в зависимости от ситуации. You access an instance of those classes from the socket object itself either via its MessageWebSocket.Control property or its StreamWebSocket.Control property, as appropriate.

Вот пример использования StreamWebSocket. Here’s an example using StreamWebSocket. Такая же схема применяется к MessageWebSocket. The same pattern applies to MessageWebSocket.

Примечание. Не пытайтесь изменить свойство элемента управления после вызова ConnectAsync. Note Don’t try to change a control property after you’ve called ConnectAsync. Единственное исключение из этого правила — MessageWebSocketControl.MessageType. The only exception to that rule is MessageWebSocketControl.MessageType.

Классы информации WebSocket WebSocket information classes

MessageWebSocket и StreamWebSocket имеют соответствующий класс, который обеспечивает дополнительную информацию об объекте. MessageWebSocket and StreamWebSocket each have a corresponding class that provides additional information about the object.

MessageWebSocketInformation предоставляет информацию о MessageWebSocket, и вы извлекаете его экземпляр с помощью свойства MessageWebSocket.Information. MessageWebSocketInformation provides information about a MessageWebSocket, and you retrieve an instance of it using the MessageWebSocket.Information property.

StreamWebSocketInformation предоставляет информацию о StreamWebSocket, и вы извлекаете его экземпляр с помощью свойства StreamWebSocket.Information. StreamWebSocketInformation provides information about a StreamWebSocket, and you retrieve an instance of it using the StreamWebSocket.Information property.

Обратите внимание, что свойства в этих классах информации доступны только для чтения, но их можно использовать для извлечения информации в любой момент в течение срока жизни объекта веб-сокета. Note that the properties on these information classes are read-only, but you can use them to retrieve information at any time during the lifetime of a web socket object.

Обработка исключений Handling exceptions

Ошибка, обнаруженная в операции MessageWebSocket или StreamWebSocket, возвращается в виде значения HRESULT. An error encountered on a MessageWebSocket or StreamWebSocket operation is returned as an HRESULT value. Можно передать значение HRESULT методу WebSocketError.GetStatus, чтобы преобразовать его в значение перечисления WebErrorStatus. You can pass that HRESULT value to the WebSocketError.GetStatus method to convert it into a WebErrorStatus enumeration value.

Большинство значений перечисления WebErrorStatus соответствуют ошибке, возвращаемой стандартной операцией клиента HTTP. Most WebErrorStatus enumeration values correspond to an error returned by the native HTTP client operation. Ваше приложение может включать значения перечисления WebErrorStatus, чтобы по-разному действовать в зависимости от причины исключения. Your app can switch on WebErrorStatus enumeration values to modify app behavior depending on the cause of the exception.

Для ошибок при проверке параметров можно использовать также значение HRESULT из исключения, чтобы получить подробные сведения об ошибке. For parameter validation errors, you can use the HRESULT from the exception to learn more detailed information about the error. Возможные значения HRESULT перечислены в Winerror.h , который находится в вашей установке SDK (например, в папке C:\Program Files (x86)\Windows Kits\10\Include\ \shared ). Possible HRESULT values are listed in Winerror.h , which can be found in your SDK installation (for example, in the folder C:\Program Files (x86)\Windows Kits\10\Include\ \shared ). Для многих ошибок при проверке параметров HRESULT возвращает значение E_INVALIDARG. For most parameter validation errors, the HRESULT returned is E_INVALIDARG.

Назначение времени ожидания при выполнении операций с WebSocket Setting timeouts on WebSocket operations

Классы MessageWebSocket и StreamWebSocket используют внутреннюю системную службу для отправки запросов клиента WebSocket и получения откликов от сервера. MessageWebSocket and StreamWebSocket use an internal system service to send WebSocket client requests, and to receive responses from a server. Время ожидания, используемое для операции подключения WebSocket, по умолчанию составляет 60 секунд. The default timeout value used for a WebSocket connect operation is 60 seconds. Если HTTP-сервер, поддерживающий WebSocket, не отвечает или не может ответить на запрос подключения WebSocket (он временно недоступен или блокируется в результате отказа сети), внутренняя системная служба ожидает заданные по умолчанию 60 секунд, а затем возвращает ошибку. If the HTTP server that supports WebSockets doesn’t or can’t respond to the WebSocket connection request (it’s temporarily down, or blocked by a network outage), then the internal system service waits the default 60 seconds before it returns an error. Эта ошибка вызывает исключение в методе WebSocket ConnectAsync. That error causes an exception to be thrown on the WebSocket ConnectAsync method. Время ожидания для операций отправки и получения после установки подключения WebSocket по умолчанию составляет 30 секунд. For send and receive operations after a WebSocket connection has been established, the default timeout is 30 seconds.

Если запрос имени HTTP-сервера в URI возвращает несколько IP-адресов, то перед завершением с ошибкой внутренняя системная служба проверяет до 5 IP-адресов для сайта, по умолчанию ожидая ответа по каждому адресу в течение 60 секунд. If the name query for an HTTP server name in the URI returns multiple IP addresses for the name, then the internal system service tries up to 5 IP addresses for the site (each with a default timeout of 60 seconds) before it fails. Следовательно, ваше приложение может ждать несколько минут, пытаясь подключиться к нескольким IP-адресам, прежде чем обработает исключение. Consequently, your app could wait several minutes trying to connect to multiple IP addresses before it handles an exception. Пользователю в этом случае может показаться, что приложение не работает. This behavior might appear to the user like the app has stopped working.

Чтобы ускорить реакцию приложения и свести эти проблемы к минимуму, можно задать более короткое время ожидания для запросов на подключение. To make your app more responsive and minimize these issues, you can set a shorter timeout on connection requests. Время ожидания задается одинаково для MessageWebSocket и StreamWebSocket. You set a timeout in a similar way for both MessageWebSocket and StreamWebSocket.