快速入門:從主控台應用程式廣播即時訊息Quickstart: Broadcast real-time messages from console app

Azure SignalR 服務能提供 REST API 以支援如廣播等的伺服器至用戶端通訊案例。Azure SignalR Service provides REST API to support server to client communication scenarios, such as broadcasting. 您可以選擇任何可進行 REST API 呼叫的程式設計語言。You can choose any programming language that can make REST API call. 您可以將訊息張貼到所有已連線的用戶端、依名稱指定的特定用戶端,或是某個用戶端群組。You can post messages to all connected clients, a specific client by name, or a group of clients.

在此快速入門中,您將會了解如何以 C# 從命令列應用程式將訊息傳送至已連線的用戶端應用程式。In this quickstart, you will learn how to send messages from a command-line app to connected client apps in C#.

必要條件Prerequisites

此快速入門可以在 macOS、Windows 或 Linux 上執行。This quickstart can be run on macOS, Windows, or Linux.

如果您沒有 Azure 訂用帳戶,請在開始前建立免費帳戶If you don't have an Azure subscription, create a free account before you begin.

登入 AzureSign in to Azure

使用您的 Azure 帳戶登入 Azure 入口網站 (https://portal.azure.com/)。Sign in to the Azure portal at https://portal.azure.com/ with your Azure account.

建立 Azure SignalR 服務執行個體Create an Azure SignalR Service instance

您的應用程式將會連線至 Azure 中的 SignalR 服務執行個體。Your application will connect to a SignalR Service instance in Azure.

  1. 選取 Azure 入口網站左上角的 [新增] 按鈕。Select the New button found on the upper left-hand corner of the Azure portal. 在 [新增] 畫面的搜尋方塊中輸入 SignalR 服務並按 Enter。In the New screen, type SignalR Service in the search box and press enter.

    搜尋 SignalR 服務

  2. 從搜尋結果中選取 [SignalR 服務],然後選取 [建立]。Select SignalR Service from the search results, then select Create.

  3. 輸入下列設定。Enter the following settings.

    設定Setting 建議的值Suggested value 說明Description
    資源名稱Resource name 全域唯一的名稱Globally unique name 能識別您的新 SignalR 服務執行個體的名稱。Name that identifies your new SignalR Service instance. 有效字元是 a-z0-9-Valid characters are a-z, 0-9, and -.
    訂用帳戶Subscription 您的訂用帳戶Your subscription 將在其下建立這個新 SignalR 服務執行個體的訂用帳戶。The subscription under which this new SignalR Service instance is created.
    資源群組Resource Group myResourceGroupmyResourceGroup 要在其中建立 SignalR 服務執行個體之新資源群組的名稱。Name for the new resource group in which to create your SignalR Service instance.
    位置Location 美國西部West US 選擇您附近的區域Choose a region near you.
    定價層Pricing tier 免費Free 免費試用 Azure SignalR 服務。Try Azure SignalR Service for free.
    單位計數Unit count 不適用Not applicable 單位計數會指出您的 SignalR 服務執行個體可接受的連線數目。Unit count specifies how many connections your SignalR Service instance can accept. 它只能在標準層中設定。It is only configurable in the Standard tier.

    建立 SignalR 服務

  4. 選取 [建立] 以開始部署 SignalR 服務執行個體。Select Create to start deploying the SignalR Service instance.

  5. 在部署執行個體之後,請在入口網站中開啟它,然後找出其 [設定] 頁面。After the instance is deployed, open it in the portal and locate its Settings page. 只有透過 Azure Functions 繫結或 REST API 使用 Azure SignalR 服務時,才要將 [服務模式] 設定變更為 [無伺服器]。Change the Service Mode setting to Serverless only if you are using Azure SignalR Service through Azure Functions binding or REST API. 否則,將它保留為 [傳統] 或 [預設]。Leave it in Classic or Default otherwise.

複製範例應用程式Clone the sample application

在服務部署期間,讓我們來準備程式碼。While the service is deploying, let's switch to prepare the code. 複製 GitHub 上的範例應用程式 (英文),設定 SignalR 服務連接字串,然後在本機執行該應用程式。Clone the sample app from GitHub, set the SignalR Service connection string, and run the application locally.

  1. 開啟 git 終端機視窗。Open a git terminal window. 變更至您想要複製範例專案的資料夾。Change to a folder where you want to clone the sample project.

  2. 執行下列命令來複製範例存放庫。Run the following command to clone the sample repository. 此命令會在您的電腦上建立範例應用程式副本。This command creates a copy of the sample app on your computer.

    git clone https://github.com/aspnet/AzureSignalR-samples.git
    

建置並執行範例Build and run the sample

此範例為示範 Azure SignalR 服務之用途的主控台應用程式。This sample is a console app showing the use of Azure SignalR Service. 它提供兩個模式:It provides two modes:

  • 伺服器模式:使用簡單的命令來呼叫 Azure SignalR 服務 REST API。Server Mode: use simple commands to call Azure SignalR Service REST API.
  • 用戶端模式:連線至 Azure SignalR 服務並接收來自伺服器的訊息。Client Mode: connect to Azure SignalR Service and receive messages from server.

此外,您也可以了解如何產生存取權杖以向 Azure SignalR 服務進行驗證。Also you can find how to generate an access token to authenticate with Azure SignalR Service.

建置可執行檔Build the executable file

我們會使用 macOS osx.10.13-x64 作為範例。We use macOS osx.10.13-x64 as example. 您可以尋找參考以了解如何在其他平台上建置。You can find reference on how to build on other platforms.

cd AzureSignalR-samples/samples/Serverless/

dotnet publish -c Release -r osx.10.13-x64

啟動用戶端Start a client

cd bin/Release/netcoreapp2.1/osx.10.13-x64/

Serverless client <ClientName> -c "<ConnectionString>" -h <HubName>

啟動伺服器Start a server

cd bin/Release/netcoreapp2.1/osx.10.13-x64/

Serverless server -c "<ConnectionString>" -h <HubName>

在不發行的情況下執行範例Run the sample without publishing

您也可以執行下列命令來啟動伺服器或用戶端You can also run the command below to start a server or client

# Start a server
dotnet run -- server -c "<ConnectionString>" -h <HubName>

# Start a client
dotnet run -- client <ClientName> -c "<ConnectionString>" -h <HubName>

使用使用者祕密來指定連接字串Use user-secrets to specify Connection String

您可以在範例的根目錄中執行 dotnet user-secrets set Azure:SignalR:ConnectionString "<ConnectionString>"You can run dotnet user-secrets set Azure:SignalR:ConnectionString "<ConnectionString>" in the root directory of the sample. 在那之後,您便不再需要 -c "<ConnectionString>" 這個選項。After that, you don't need the option -c "<ConnectionString>" anymore.

使用量Usage

在伺服器啟動之後,使用下列命令來傳送訊息:After the server started, use the command to send message:

send user <User Id>
send users <User List>
send group <Group Name>
send groups <Group List>
broadcast

您可以啟動具不同用戶端名稱的多個用戶端。You can start multiple clients with different client names.

與第三方服務整合 Integration with third-party services

Azure SignalR 服務可讓第三方服務與系統整合。The Azure SignalR service allows third-party services to integrate with the system.

技術規格的定義Definition of technical specifications

下表顯示目前所支援的所有 REST API 版本。The following table shows all the versions of the REST APIs supported to date. 您也可以找到每個特定版本的定義檔You can also find the definition file for each specific version

版本Version API 狀態API State Door 特定Specific
1.0-preview 可用Available 50025002 SwaggerSwagger
1.0 可用Available 標準Standard SwaggerSwagger

下列清單提供每個特定版本的可用 API 清單。The list of available APIs for each specific version is available in the following list.

APIAPI 1.0-preview 1.0
廣播到所有目標Broadcast to all
廣播到群組Broadcast to a group
廣播到部分群組Broadcast to some groups (已取代) (Deprecated) N / A
傳送給特定使用者Send to specific users
傳送給部分使用者Send to some users (已取代) (Deprecated) N / A
將使用者新增至群組Adding a user to a group N / A
從群組中移除使用者Removing a user from a group N / A

廣播給所有人Broadcast to everyone

版本Version API HTTP 方法API HTTP Method 要求 URLRequest URL Request bodyRequest body
1.0-preview POST https://<instance-name>.service.signalr.net:5002/api/v1-preview/hub/<hub-name> {"target": "<method-name>", "arguments": [...]}
1.0 POST https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name> 同上Same as above

廣播到群組Broadcast to a group

版本Version API HTTP 方法API HTTP Method 要求 URLRequest URL Request bodyRequest body
1.0-preview POST https://<instance-name>.service.signalr.net:5002/api/v1-preview/hub/<hub-name>/group/<group-name> {"target": "<method-name>", "arguments": [...]}
1.0 POST https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name> 同上Same as above

傳送給特定使用者Sending to specific users

版本Version API HTTP 方法API HTTP Method 要求 URLRequest URL Request bodyRequest body
1.0-preview POST https://<instance-name>.service.signalr.net:5002/api/v1-preview/hub/<hub-name>/user/<user-id> {"target": "<method-name>", "arguments": [...]}
1.0 POST https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/users/<user-id> 同上Same as above

將使用者新增至群組Adding a user to a group

版本Version API HTTP 方法API HTTP Method 要求 URLRequest URL
1.0 PUT https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name>/users/<userid>

從群組中移除使用者Removing a user from a group

版本Version API HTTP 方法API HTTP Method 要求 URLRequest URL
1.0 DELETE https://<instance-name>.service.signalr.net/api/v1/hubs/<hub-name>/groups/<group-name>/users/<userid>

清除資源Clean up resources

如果您將不繼續使用此應用程式,請使用下列步驟來刪除本快速入門所建立的全部資源,這樣才不會產生任何費用:If you're not going to continue to use this app, delete all resources created by this quickstart with the following steps so you don't incur any charges:

  1. 在 Azure 入口網站中選取靠左側的 [資源群組],然後選取您所建立的群組。In the Azure portal, select Resource groups on the far left, and then select the resource group you created. 或者,您也可以使用搜尋方塊來依資源群組的名稱尋找它。Alternatively, you may use the search box to find the resource group by its name.

  2. 在開啟的視窗中選取資源群組,然後按一下 [刪除資源群組]。In the window that opens, select the resource group, and then click Delete resource group.

  3. 在新視窗中輸入要刪除之資源群組的名稱,然後按一下 [刪除]。In the new window, type the name of the resource group to delete, and then click Delete.

後續步驟Next steps

在本快速入門中,您已了解如何使用 REST API 將即時訊息從 SignalR Service 廣播至用戶端。In this quickstart, you learned how to use REST API to broadcast real-time message from SignalR Service to clients. 接下來,請深入了解如何使用 SignalR Service 繫結 (以 REST API 為基礎所建置) 來開發和部署 Azure Functions。Next, learn more about how to develop and deploy Azure Functions with SignalR Service binding, which is built on top of REST API.