|
| 1 | +# Azure Web PubSub extension of isolated-process Azure Functions client library for .NET |
| 2 | + |
| 3 | +This extension defines the binding types and triggers in the .NET isolated worker process for Azure Functions, allowing you to write functions that respond to any event published to Web PubSub. |
| 4 | + |
| 5 | +[Source code][source] | |
| 6 | +Package | |
| 7 | +API reference documentation | |
| 8 | +[Product documentation](https://aka.ms/awps/doc) | |
| 9 | +[Samples] |
| 10 | + |
| 11 | +## Getting started |
| 12 | + |
| 13 | +### Install the package |
| 14 | + |
| 15 | +Install the client library from [NuGet]: |
| 16 | + |
| 17 | +```dotnetcli |
| 18 | +dotnet add package Microsoft.Azure.Functions.Worker.Extensions.WebPubSub |
| 19 | +``` |
| 20 | + |
| 21 | +### Prerequisites |
| 22 | + |
| 23 | +You must have an [Azure subscription][free_subs] and an Azure resource group with a Web PubSub resource. Follow this [step-by-step tutorial][tutorial] to create an Azure Web PubSub instance. |
| 24 | + |
| 25 | +### Authenticate the client |
| 26 | + |
| 27 | +In order to let the extension work with Azure Web PubSub service, you will need to provide a valid `ConnectionString`. |
| 28 | + |
| 29 | +You can find the **Keys** for you Azure Web PubSub service in the [Azure Portal][portal]. |
| 30 | + |
| 31 | +The `AzureWebJobsStorage` connection string is used to preserve the processing checkpoint information as required refer to [Storage considerations][storage] |
| 32 | + |
| 33 | +For the local development use the `local.settings.json` file to store the connection string, `<connection-string>` can be set to `WebPubSubConnectionString` as default supported in the extension, or you can set customized names by mapping it with `Connection = <connection-string>` in function binding attributes: |
| 34 | + |
| 35 | +```json |
| 36 | +{ |
| 37 | + "Values": { |
| 38 | + "AzureWebJobsStorage": "UseDevelopmentStorage=true", |
| 39 | + "<connection-string>": "Endpoint=https://<webpubsub-name>.webpubsub.azure.com;AccessKey=<access-key>;Version=1.0;" |
| 40 | + } |
| 41 | +} |
| 42 | +``` |
| 43 | +When deployed use the [application settings][app_setting] to set the connection string. |
| 44 | + |
| 45 | +## Key concepts |
| 46 | + |
| 47 | +### Using Web PubSub input binding |
| 48 | + |
| 49 | +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. |
| 50 | + |
| 51 | +### Using Web PubSub output binding |
| 52 | + |
| 53 | +Please follow the [output binding tutorial](#functions-that-uses-web-pubsub-output-binding) to learn about using this extension for publishing Web PubSub messages. |
| 54 | + |
| 55 | +### Using Web PubSub trigger |
| 56 | + |
| 57 | +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. |
| 58 | + |
| 59 | +In `Connect` and `UserEvent` 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 `ConnectEventResponse` or `EventErrorResponse`, and ignore other returns. When `EventErrorResponse` is returned, service will drop client connection. |
| 60 | + |
| 61 | +## Examples |
| 62 | + |
| 63 | +### Functions that uses Web PubSub input binding |
| 64 | + |
| 65 | +Use `WebPubSubConnectionInput` to build the client negotiate URL. |
| 66 | + |
| 67 | +```C# Snippet:WebPubSubConnectionInputFunction |
| 68 | +[Function("Negotiate")] |
| 69 | +public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req, |
| 70 | +[WebPubSubConnectionInput(Hub = "<web_pubsub_hub>", Connection = "<web_pubsub_connection_name>")] WebPubSubConnection connectionInfo) |
| 71 | +{ |
| 72 | + var response = req.CreateResponse(HttpStatusCode.OK); |
| 73 | + response.WriteAsJsonAsync(connectionInfo); |
| 74 | + return response; |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +Use `WebPubSubContextInput` to read Web PubSub request under `HttpTrigger`. This is useful when work with Static Web Apps which supports `HttpTrigger` functions only. |
| 79 | + |
| 80 | +```C# Snippet:WebPubSubContextInputFunction |
| 81 | +// validate method when upstream set as http://<func-host>/api/{event} |
| 82 | +[Function("validate")] |
| 83 | +public static HttpResponseData Validate( |
| 84 | + [HttpTrigger(AuthorizationLevel.Anonymous, "options")] HttpRequestData req, |
| 85 | + [WebPubSubContextInput] WebPubSubContext wpsReq) |
| 86 | +{ |
| 87 | + return BuildHttpResponseData(req, wpsReq.Response); |
| 88 | +} |
| 89 | + |
| 90 | +// Respond AbuseProtection to put header correctly. |
| 91 | +private static HttpResponseData BuildHttpResponseData(HttpRequestData request, SimpleResponse wpsResponse) |
| 92 | +{ |
| 93 | + var response = request.CreateResponse(); |
| 94 | + response.StatusCode = (HttpStatusCode)wpsResponse.Status; |
| 95 | + response.Body = response.Body; |
| 96 | + foreach (var header in wpsResponse.Headers) |
| 97 | + { |
| 98 | + response.Headers.Add(header.Key, header.Value); |
| 99 | + } |
| 100 | + return response; |
| 101 | +} |
| 102 | +``` |
| 103 | + |
| 104 | +### Functions that uses Web PubSub output binding |
| 105 | + |
| 106 | +```C# Snippet:WebPubSubOutputFunction |
| 107 | +[Function("Notification")] |
| 108 | +[WebPubSubOutput(Hub = "<web_pubsub_hub>", Connection = "<web_pubsub_connection_name>")] |
| 109 | +public static WebPubSubAction Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req) |
| 110 | +{ |
| 111 | + return new SendToAllAction |
| 112 | + { |
| 113 | + Data = BinaryData.FromString($"Hello SendToAll."), |
| 114 | + DataType = WebPubSubDataType.Text |
| 115 | + }; |
| 116 | +} |
| 117 | +``` |
| 118 | + |
| 119 | +### Functions that uses Web PubSub trigger |
| 120 | + |
| 121 | +```C# Snippet:WebPubSubTriggerUserEventFunction |
| 122 | +[Function("Broadcast")] |
| 123 | +public static UserEventResponse Run( |
| 124 | +[WebPubSubTrigger("<web_pubsub_hub>", WebPubSubEventType.User, "message")] UserEventRequest request) |
| 125 | +{ |
| 126 | + return new UserEventResponse("[SYSTEM ACK] Received."); |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +For more details see the [samples README][samples]. |
| 131 | + |
| 132 | +## Troubleshooting |
| 133 | + |
| 134 | +Please refer to [Monitor Azure Functions][monitor] for troubleshooting guidance. |
| 135 | + |
| 136 | +## Next steps |
| 137 | + |
| 138 | +Read the [introduction to Azure Function][func_intro] or [creating an Azure Function guide][create]. |
| 139 | + |
| 140 | +## Contributing |
| 141 | + |
| 142 | +See our [CONTRIBUTING.md][contrib] for details on building, |
| 143 | +testing, and contributing to this library. |
| 144 | + |
| 145 | +This project welcomes contributions and suggestions. Most contributions require |
| 146 | +you to agree to a Contributor License Agreement (CLA) declaring that you have |
| 147 | +the right to, and actually do, grant us the rights to use your contribution. For |
| 148 | +details, visit [cla.microsoft.com][cla]. |
| 149 | + |
| 150 | +This project has adopted the [Microsoft Open Source Code of Conduct][coc]. |
| 151 | +For more information see the [Code of Conduct FAQ][coc_faq] |
| 152 | +or contact [[email protected]][coc_contact] with any |
| 153 | +additional questions or comments. |
| 154 | + |
| 155 | + |
| 156 | + |
| 157 | +<!-- LINKS --> |
| 158 | +<!-- TODO: update to sdk main branch after initial merge --> |
| 159 | +[source]: https://github.com/JialinXin/azure-sdk-for-net/tree/awps/isolated-func/sdk/webpubsub/Microsoft.Azure.Functions.Worker.Extensions.WebPubSub/src |
| 160 | +<!-- [package] TODO: add after initial release --> |
| 161 | +<!-- [api_docs] TODO: add after initial release --> |
| 162 | +<!-- TODO: update to sdk main branch after initial merge --> |
| 163 | +[samples]: https://github.com/JialinXin/azure-sdk-for-net/tree/awps/isolated-func/sdk/webpubsub/Microsoft.Azure.Functions.Worker.Extensions.WebPubSub/samples |
| 164 | +[nuget]: https://www.nuget.org/ |
| 165 | +[free_subs]: https://azure.microsoft.com/free/dotnet/ |
| 166 | +[portal]: https://portal.azure.com/ |
| 167 | +[tutorial]: https://learn.microsoft.com/azure/azure-web-pubsub/howto-develop-create-instance |
| 168 | +[storage]: https://learn.microsoft.com/azure/azure-functions/storage-considerations#storage-account-requirements |
| 169 | +[app_setting]: https://learn.microsoft.com/azure/azure-functions/functions-how-to-use-azure-function-app-settings |
| 170 | +[monitor]: https://learn.microsoft.com/azure/azure-functions/functions-monitoring |
| 171 | +[func_intro]: https://learn.microsoft.com/azure/azure-functions/functions-overview |
| 172 | +[create]: https://learn.microsoft.com/azure/azure-functions/functions-overview |
| 173 | + |
| 174 | +[contrib]: https://github.com/Azure/azure-sdk-for-net/tree/main/CONTRIBUTING.md |
| 175 | +[cla]: https://cla.microsoft.com |
| 176 | +[coc]: https://opensource.microsoft.com/codeofconduct/ |
| 177 | +[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ |
| 178 | +[coc_contact]: mailto:[email protected] |
0 commit comments