|
| 1 | +# Azure WebJobs Web PubSub client library for .NET |
| 2 | + |
| 3 | +This extension provides functionality for receiving Web PubSub webhook calls in Azure Functions, allowing you to easily write functions that respond to any event published to Web PubSub. |
| 4 | + |
| 5 | +## Getting started |
| 6 | + |
| 7 | +### Install the package |
| 8 | + |
| 9 | +Install the Web PubSub extension with [NuGet][nuget]: |
| 10 | + |
| 11 | +```Powershell |
| 12 | +dotnet add package Microsoft.Azure.WebJobs.Extensions.WebPubSub --prerelease |
| 13 | +``` |
| 14 | + |
| 15 | +### Prerequisites |
| 16 | + |
| 17 | +You must have an [Azure subscription](https://azure.microsoft.com/free/) and an Azure resource group with a Web PubSub resource. Follow this [step-by-step tutorial](https://review.docs.microsoft.com/azure/azure-web-pubsub/howto-develop-create-instance?branch=release-azure-web-pubsub) to create an Azure Web PubSub instance. |
| 18 | + |
| 19 | +### Authenticate the client |
| 20 | + |
| 21 | +In order to let the extension work with Azure Web PubSub service, you will need to provide a valid `ConnectionString`. |
| 22 | + |
| 23 | +You can find the **Keys** for you Azure Web PubSub service in the [Azure Portal](https://portal.azure.com/). |
| 24 | + |
| 25 | +The `AzureWebJobsStorage` connection string is used to preserve the processing checkpoint information as required refer to [Storage considerations](https://docs.microsoft.com/azure/azure-functions/storage-considerations#storage-account-requirements) |
| 26 | + |
| 27 | +For the local development use the `local.settings.json` file to store the connection string, `<connection_name>` can be set to `WebPubSubConnectionString` as default supported in the extension, or you can set customized names by mapping it with `ConnectionStringSetting = <connection_name>` in function binding attributes: |
| 28 | + |
| 29 | +```json |
| 30 | +{ |
| 31 | + "Values": { |
| 32 | + "AzureWebJobsStorage": "UseDevelopmentStorage=true", |
| 33 | + "<connection_name>": "Endpoint=https://<webpubsub-name>.webpubsub.azure.com;AccessKey=<access-key>;Version=1.0;" |
| 34 | + } |
| 35 | +} |
| 36 | +``` |
| 37 | +When deployed use the [application settings](https://docs.microsoft.com/azure/azure-functions/functions-how-to-use-azure-function-app-settings) to set the connection string. |
| 38 | + |
| 39 | +## Key concepts |
| 40 | + |
| 41 | +### Using Web PubSub input binding |
| 42 | + |
| 43 | +Please follow the [input binding tutorial](#functions-that-uses-web-pubsub-input-binding) to learn about using this extension for building `WebPubSubConnection` to create Websockets connection to service with input binding. |
| 44 | + |
| 45 | +### Using Web PubSub output binding |
| 46 | + |
| 47 | +Please follow the [output binding tutorial](#functions-that-uses-web-pubsub-output-binding) to learn about using this extension for publishing Web PubSub messages. |
| 48 | + |
| 49 | +### Using Web PubSub trigger |
| 50 | + |
| 51 | +Please follow the [trigger binding tutorial](#functions-that-uses-web-pubsub-trigger) to learn about triggering an Azure Function when an event is sent from service upstream. |
| 52 | + |
| 53 | +In `Connect` and `Message` events, function will respect return values to send back service. Then service will depend on the response to proceed the request or else. The responses and events are paired. For example, `Connect` will only respect `ConnectResponse` or `ErrorResponse`, and ignore other returns. When `ErrorResponse` is returned, service will drop client connection. Please follow the [trigger binding return value tutorial](#functions-that-uses-web-pubsub-trigger-return-value) to learn about using the trigger return value. |
| 54 | + |
| 55 | +## Examples |
| 56 | + |
| 57 | +### Functions that uses Web PubSub input binding |
| 58 | + |
| 59 | +```cs |
| 60 | +[FunctionName("WebPubSubInputBindingFunction")] |
| 61 | +public static WebPubSubConnection Run( |
| 62 | + [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req, |
| 63 | + [WebPubSubConnection(Hub = "simplechat", UserId = "{query.userid}")] WebPubSubConnection connection) |
| 64 | +{ |
| 65 | + Console.WriteLine("login"); |
| 66 | + return connection; |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +### Functions that uses Web PubSub output binding |
| 71 | + |
| 72 | +```cs |
| 73 | +[FunctionName("WebPubSubOutputBindingFunction")] |
| 74 | +public static async Task RunAsync( |
| 75 | + [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req, |
| 76 | + [WebPubSub(Hub = "simplechat")] IAsyncCollector<WebPubSubOperation> operation) |
| 77 | +{ |
| 78 | + await operation.AddAsync(new SendToAll |
| 79 | + { |
| 80 | + Message = BinaryData.FromString("Hello Web PubSub"), |
| 81 | + DataType = MessageDataType.Text |
| 82 | + }); |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +### Functions that uses Web PubSub trigger |
| 87 | + |
| 88 | +```cs |
| 89 | +[FunctionName("WebPubSubTriggerFunction")] |
| 90 | +public static void Run( |
| 91 | + [WebPubSubTrigger("message", WebPubSubEventType.User)] |
| 92 | + ConnectionContext context, |
| 93 | + string message, |
| 94 | + MessageDataType dataType) |
| 95 | +{ |
| 96 | + Console.WriteLine($"Request from: {context.userId}"); |
| 97 | + Console.WriteLine($"Request message: {message}"); |
| 98 | + Console.WriteLine($"Request message DataType: {dataType}"); |
| 99 | +} |
| 100 | +``` |
| 101 | + |
| 102 | +### Functions that uses Web PubSub trigger return value |
| 103 | + |
| 104 | +```cs |
| 105 | +[FunctionName("WebPubSubTriggerReturnValueFunction")] |
| 106 | +public static MessageResponse RunAsync( |
| 107 | + [WebPubSubTrigger("message", WebPubSubEventType.User)] ConnectionContext context) |
| 108 | +{ |
| 109 | + return new MessageResponse |
| 110 | + { |
| 111 | + Message = BinaryData.FromString("ack"), |
| 112 | + DataType = MessageDataType.Text |
| 113 | + }; |
| 114 | +} |
| 115 | +``` |
| 116 | + |
| 117 | +## Troubleshooting |
| 118 | + |
| 119 | +Please refer to [Monitor Azure Functions](https://docs.microsoft.com/azure/azure-functions/functions-monitoring) for troubleshooting guidance. |
| 120 | + |
| 121 | +## Next steps |
| 122 | + |
| 123 | +Read the [introduction to Azure Function](https://docs.microsoft.com/azure/azure-functions/functions-overview) or [creating an Azure Function guide](https://docs.microsoft.com/azure/azure-functions/functions-create-first-azure-function). |
| 124 | + |
| 125 | +## Contributing |
| 126 | + |
| 127 | +See our [CONTRIBUTING.md][contrib] for details on building, |
| 128 | +testing, and contributing to this library. |
| 129 | + |
| 130 | +This project welcomes contributions and suggestions. Most contributions require |
| 131 | +you to agree to a Contributor License Agreement (CLA) declaring that you have |
| 132 | +the right to, and actually do, grant us the rights to use your contribution. For |
| 133 | +details, visit [cla.microsoft.com][cla]. |
| 134 | + |
| 135 | +This project has adopted the [Microsoft Open Source Code of Conduct][coc]. |
| 136 | +For more information see the [Code of Conduct FAQ][coc_faq] |
| 137 | +or contact [[email protected]][coc_contact] with any |
| 138 | +additional questions or comments. |
| 139 | + |
| 140 | + |
| 141 | + |
| 142 | +<!-- LINKS --> |
| 143 | +[source]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/search/Microsoft.Azure.WebJobs.Extensions.WebPubSub/src |
| 144 | +[package]: https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.WebPubSub/ |
| 145 | +[docs]: https://docs.microsoft.com/dotnet/api/Microsoft.Azure.WebJobs.Extensions.WebPubSub |
| 146 | +[nuget]: https://www.nuget.org/ |
| 147 | + |
| 148 | +[contrib]: https://github.com/Azure/azure-sdk-for-net/tree/master/CONTRIBUTING.md |
| 149 | +[cla]: https://cla.microsoft.com |
| 150 | +[coc]: https://opensource.microsoft.com/codeofconduct/ |
| 151 | +[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ |
| 152 | +[coc_contact]: mailto:[email protected] |
0 commit comments