[WebPubSub]Add isolated-process extension for WebPubSub (#34618)

* Add isolated-process extension for WebPubSub * clean changelog * export API. * fix changelog. * uniform version. * update README and minor fixes. * property fix. * re-factor samples * Add allowed product slug and link fix. * minor description fix. * fix link * Revert eng changes, need separate PR. * Fix cached name would be mixed in the same function. * update sample products tag. * Support polymorphic serialization in output. * Sync to latest extension version. * update sample * Sync sample to fix CI.
Azure · Apr 27, 2023 · e8c40cc · e8c40cc
1 parent 9164bfd
commit e8c40cc
Show file tree

Hide file tree

Showing 60 changed files with 2,326 additions and 1 deletion.
diff --git a/eng/Packages.Data.props b/eng/Packages.Data.props
@@ -151,6 +151,7 @@
     <PackageReference Update="Microsoft.AspNetCore.Http" Version="2.1.22" />
     <PackageReference Update="Microsoft.AspNetCore.Http.Connections" Version="1.0.15" />
     <PackageReference Update="Microsoft.Azure.Functions.Extensions" Version="1.0.0" />
+    <PackageReference Update="Microsoft.Azure.Functions.Worker.Extensions.Abstractions" Version="1.1.0" />
     <PackageReference Update="Microsoft.Extensions.Azure" Version="1.6.3" />
     <PackageReference Update="Microsoft.Extensions.DependencyInjection.Abstractions" Version="2.1.0" />
     <PackageReference Update="Microsoft.Extensions.Configuration" Version="2.1.0" />

diff --git a/sdk/webpubsub/Microsoft.Azure.Functions.Worker.Extensions.WebPubSub/CHANGELOG.md b/sdk/webpubsub/Microsoft.Azure.Functions.Worker.Extensions.WebPubSub/CHANGELOG.md
@@ -0,0 +1,11 @@
+# Release History
+
+## 1.5.0-beta.1 (Unreleased)
+
+### Features Added
+
+### Breaking Changes
+
+### Bugs Fixed
+
+### Other Changes
diff --git a/sdk/webpubsub/Microsoft.Azure.Functions.Worker.Extensions.WebPubSub/Directory.Build.props b/sdk/webpubsub/Microsoft.Azure.Functions.Worker.Extensions.WebPubSub/Directory.Build.props
@@ -0,0 +1,6 @@
+<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <!--
+    Add any shared properties you want for the projects under this package directory that need to be set before the auto imported Directory.Build.props
+  -->
+  <Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory).., Directory.Build.props))\Directory.Build.props" />
+</Project>
diff --git a/...ons.Worker.Extensions.WebPubSub/Microsoft.Azure.Functions.Worker.Extensions.WebPubSub.sln b/...ons.Worker.Extensions.WebPubSub/Microsoft.Azure.Functions.Worker.Extensions.WebPubSub.sln
@@ -0,0 +1,25 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.4.33213.308
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microsoft.Azure.Functions.Worker.Extensions.WebPubSub", "src\Microsoft.Azure.Functions.Worker.Extensions.WebPubSub.csproj", "{8FD378FF-7228-4A8D-AB9B-65D60A386E94}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{8FD378FF-7228-4A8D-AB9B-65D60A386E94}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{8FD378FF-7228-4A8D-AB9B-65D60A386E94}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{8FD378FF-7228-4A8D-AB9B-65D60A386E94}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{8FD378FF-7228-4A8D-AB9B-65D60A386E94}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {6A1FF741-58C3-4C13-A0D5-54902BE0CC44}
+	EndGlobalSection
+EndGlobal
diff --git a/sdk/webpubsub/Microsoft.Azure.Functions.Worker.Extensions.WebPubSub/README.md b/sdk/webpubsub/Microsoft.Azure.Functions.Worker.Extensions.WebPubSub/README.md
@@ -0,0 +1,178 @@
+# Azure Web PubSub extension of isolated-process Azure Functions client library for .NET
+
+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.
+
+[Source code][source] |
+Package |
+API reference documentation |
+[Product documentation](https://aka.ms/awps/doc) |
+[Samples]
+
+## Getting started
+
+### Install the package
+
+Install the client library from [NuGet]:
+
+```dotnetcli
+dotnet add package Microsoft.Azure.Functions.Worker.Extensions.WebPubSub
+```
+
+### Prerequisites
+
+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.
+
+### Authenticate the client
+
+In order to let the extension work with Azure Web PubSub service, you will need to provide a valid `ConnectionString`. 
+
+You can find the **Keys** for you Azure Web PubSub service in the [Azure Portal][portal].
+
+The `AzureWebJobsStorage` connection string is used to preserve the processing checkpoint information as required refer to [Storage considerations][storage]
+
+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:
+
+```json
+{
+  "Values": {
+    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
+    "<connection-string>": "Endpoint=https://<webpubsub-name>.webpubsub.azure.com;AccessKey=<access-key>;Version=1.0;"
+  }
+}
+```
+When deployed use the [application settings][app_setting] to set the connection string.
+
+## Key concepts
+
+### Using Web PubSub input binding
+
+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.
+
+### Using Web PubSub output binding
+
+Please follow the [output binding tutorial](#functions-that-uses-web-pubsub-output-binding) to learn about using this extension for publishing Web PubSub messages.
+
+### Using Web PubSub trigger
+
+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.
+
+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.
+
+## Examples
+
+### Functions that uses Web PubSub input binding
+
+Use `WebPubSubConnectionInput` to build the client negotiate URL.
+
+```C# Snippet:WebPubSubConnectionInputFunction
+[Function("Negotiate")]
+public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
+[WebPubSubConnectionInput(Hub = "<web_pubsub_hub>", Connection = "<web_pubsub_connection_name>")] WebPubSubConnection connectionInfo)
+{
+    var response = req.CreateResponse(HttpStatusCode.OK);
+    response.WriteAsJsonAsync(connectionInfo);
+    return response;
+}
+```
+
+Use `WebPubSubContextInput` to read Web PubSub request under `HttpTrigger`. This is useful when work with Static Web Apps which supports `HttpTrigger` functions only.
+
+```C# Snippet:WebPubSubContextInputFunction
+// validate method when upstream set as http://<func-host>/api/{event}
+[Function("validate")]
+public static HttpResponseData Validate(
+    [HttpTrigger(AuthorizationLevel.Anonymous, "options")] HttpRequestData req,
+    [WebPubSubContextInput] WebPubSubContext wpsReq)
+{
+    return BuildHttpResponseData(req, wpsReq.Response);
+}
+
+// Respond AbuseProtection to put header correctly.
+private static HttpResponseData BuildHttpResponseData(HttpRequestData request, SimpleResponse wpsResponse)
+{
+    var response = request.CreateResponse();
+    response.StatusCode = (HttpStatusCode)wpsResponse.Status;
+    response.Body = response.Body;
+    foreach (var header in wpsResponse.Headers)
+    {
+        response.Headers.Add(header.Key, header.Value);
+    }
+    return response;
+}
+```
+
+### Functions that uses Web PubSub output binding
+
+```C# Snippet:WebPubSubOutputFunction
+[Function("Notification")]
+[WebPubSubOutput(Hub = "<web_pubsub_hub>", Connection = "<web_pubsub_connection_name>")]
+public static WebPubSubAction Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req)
+{
+    return new SendToAllAction
+    {
+        Data = BinaryData.FromString($"Hello SendToAll."),
+        DataType = WebPubSubDataType.Text
+    };
+}
+```
+
+### Functions that uses Web PubSub trigger
+
+```C# Snippet:WebPubSubTriggerUserEventFunction
+[Function("Broadcast")]
+public static UserEventResponse Run(
+[WebPubSubTrigger("<web_pubsub_hub>", WebPubSubEventType.User, "message")] UserEventRequest request)
+{
+    return new UserEventResponse("[SYSTEM ACK] Received.");
+}
+```
+
+For more details see the [samples README][samples].
+
+## Troubleshooting
+
+Please refer to [Monitor Azure Functions][monitor] for troubleshooting guidance.
+
+## Next steps
+
+Read the [introduction to Azure Function][func_intro] or [creating an Azure Function guide][create].
+
+## Contributing
+
+See our [CONTRIBUTING.md][contrib] for details on building,
+testing, and contributing to this library.
+
+This project welcomes contributions and suggestions.  Most contributions require
+you to agree to a Contributor License Agreement (CLA) declaring that you have
+the right to, and actually do, grant us the rights to use your contribution. For
+details, visit [cla.microsoft.com][cla].
+
+This project has adopted the [Microsoft Open Source Code of Conduct][coc].
+For more information see the [Code of Conduct FAQ][coc_faq]
+or contact [[email protected]][coc_contact] with any
+additional questions or comments.
+
+![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Fsearch%2FMicrosoft.Azure.Functions.Worker.Extensions.WebPubSub%2FREADME.png)
+
+<!-- LINKS -->
+<!-- TODO: update to sdk main branch after initial merge -->
+[source]: https://github.com/JialinXin/azure-sdk-for-net/tree/awps/isolated-func/sdk/webpubsub/Microsoft.Azure.Functions.Worker.Extensions.WebPubSub/src
+<!-- [package] TODO: add after initial release -->
+<!-- [api_docs] TODO: add after initial release -->
+<!-- TODO: update to sdk main branch after initial merge -->
+[samples]: https://github.com/JialinXin/azure-sdk-for-net/tree/awps/isolated-func/sdk/webpubsub/Microsoft.Azure.Functions.Worker.Extensions.WebPubSub/samples
+[nuget]: https://www.nuget.org/
+[free_subs]: https://azure.microsoft.com/free/dotnet/
+[portal]: https://portal.azure.com/
+[tutorial]: https://learn.microsoft.com/azure/azure-web-pubsub/howto-develop-create-instance
+[storage]: https://learn.microsoft.com/azure/azure-functions/storage-considerations#storage-account-requirements
+[app_setting]: https://learn.microsoft.com/azure/azure-functions/functions-how-to-use-azure-function-app-settings
+[monitor]: https://learn.microsoft.com/azure/azure-functions/functions-monitoring
+[func_intro]: https://learn.microsoft.com/azure/azure-functions/functions-overview
+[create]: https://learn.microsoft.com/azure/azure-functions/functions-overview
+
+[contrib]: https://github.com/Azure/azure-sdk-for-net/tree/main/CONTRIBUTING.md
+[cla]: https://cla.microsoft.com
+[coc]: https://opensource.microsoft.com/codeofconduct/
+[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
+[coc_contact]: mailto:[email protected]