Add instructions for running Durable functions on Azure (#475)

AnatoliB · web-flow · commit d3556aa6ffe2 · 2020-06-12T00:02:46.000-07:00
diff --git a/docs/durable-experimental-instructions.md b/docs/durable-experimental-instructions.md
@@ -1,42 +1,54 @@
-# How to try experimental Durable PowerShell functions
+# How to try Durable PowerShell functions
 
-## **PLEASE READ THIS:**
+## Please note
 
-> This is an experimental feature. Do **not** enable or try to use it for production purposes. The programming model may change, so the sample code or any app code you come up with may not work in the next versions. The main purpose of making it available now is to enable experimentation and early feedback. **Your feedback is highly appreciated**, and please feel free to file [GitHub issues](https://github.com/Azure/azure-functions-powershell-worker/issues/new).
+- This feature is getting ready for Public Preview. If you use it for production purposes, be aware that the programming model may change before GA, so the sample code or any app code you come up with may not work in the next versions.
+- **Your feedback is highly appreciated**, please feel free to file [GitHub issues](https://github.com/Azure/azure-functions-powershell-worker/issues/new) if anything does not work as expected.
+- Make sure you are using Azure Functions **v3** runtime. There are no plans to support Durable PowerShell on Azure Functions **v1** or **v2**.
+- Only Durable Functions **2.x** will be officially supported (see [Durable Functions versions overview](https://docs.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-versions)). Technically, the current implementation works with Durable Functions **1.x** as well. However, it may stop working before GA.
+- Only a limited number of patterns is enabled at this point:
+  - [Function chaining](https://docs.microsoft.com/azure/azure-functions/durable/durable-functions-overview?tabs=csharp#chaining)
+  - [Fan out/fan in](https://docs.microsoft.com/azure/azure-functions/durable/durable-functions-overview?tabs=csharp#fan-in-out)
+  - [Async HTTP APIs](https://docs.microsoft.com/azure/azure-functions/durable/durable-functions-overview?tabs=csharp#async-http)
 
-> If you want to try the latest version locally, consider following these instructions as they automate and simplify the steps below: https://git.io/PS7DurableFunctionsNow
+## Local setup
 
-> You can also get started using a dev container with Visual Studio Code Remote for Containers or Visual Studio Online: https://github.com/anthonychu/powershell-durable-preview
+_This step is required if you intend to run Durable PowerShell functions on your local machine. Otherwise, feel free to skip this step._
 
-## 1. PowerShell worker version
+At the moment of writing this (June 11, 2020), the PowerShell Worker version deployed by Azure Functions Core Tools does support Durable Functions yet. If you want to run Durable PowerShell functions locally, consider the following options:
 
-At the moment of writing this (March 14, 2020), the Durable PowerShell implementation deployed to Azure is outdated. If you want to follow the instructions below, please install a more recent version locally:
-- Install [Azure Functions Core Tools](https://docs.microsoft.com/azure/azure-functions/functions-run-local?tabs=windows%2Ccsharp%2Cbash#install-the-azure-functions-core-tools) **v3.x** (if not installed yet).
-- Download the latest PowerShell worker package:
-``` PowerShell
-Save-Package -Name 'Microsoft.Azure.Functions.PowershellWorker.PS7' -Source 'https://ci.appveyor.com/nuget/azure-functions-powershell-wor-0842fakagqy6/' -ProviderName NuGet -Path ~\Downloads\
-```
-- Rename the downloaded .nuget file to .zip and extract the content of the `contentFiles\any\any\workers\powershell` folder to `workers\powershell` under the [Core Tools](https://github.com/Azure/azure-functions-powershell-worker/blob/dev/README.md#published-host), overwriting the existing files.
+- **Option 1**: Get started using a dev container with Visual Studio Code Remote for Containers or Visual Studio Online: https://github.com/anthonychu/powershell-durable-preview
 
-If you want to try this on Azure, you will have to wait a bit longer.
+- **Option 2**: Consider following these instructions as they automate and simplify the steps below: https://git.io/PS7DurableFunctionsNow
 
-## 2. Sample app
+- **Option 3**: Install the latest PowerShell Worker build manually:
 
-Start with the sample durable app at `examples/durable/DurableApp`.
+  - Install [Azure Functions Core Tools](https://docs.microsoft.com/azure/azure-functions/functions-run-local?tabs=windows%2Ccsharp%2Cbash#install-the-azure-functions-core-tools) **v3.x** (if not installed yet).
 
-Note:
+  - Download the latest PowerShell worker package:
 
-- Please make sure you are using Azure Functions **v3** runtime. There are no plans to support Durable PowerShell on Azure Functions **v1** or **v2**.
-- Only Durable Functions **2.x** will be supported (see [Durable Functions versions overview](https://docs.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-versions)). Technically, the current implementation works with Durable Functions **1.x** as well. However, it may stop working before GA, and there is no plan to support Durable Functions **1.x** officially in any case.
-- Please make sure you are using the sample code version corresponding to the version of the PowerShell Worker. The programming model is still changing, so older or newer samples may not work. So, if you are trying Durable PowerShell on Azure, use the samples tagged with the version of the PowerShell worker deployed to Azure. Alternatively, take the latest PowerShell Worker code from the **dev** branch, and rebuild and run the PowerShell Worker locally.
-- Only a limited number of patterns is enabled at this point:
-  - [Function chaining](https://docs.microsoft.com/azure/azure-functions/durable/durable-functions-overview?tabs=csharp#chaining)
-  - [Fan out/fan in](https://docs.microsoft.com/azure/azure-functions/durable/durable-functions-overview?tabs=csharp#fan-in-out)
-  - [Async HTTP APIs](https://docs.microsoft.com/azure/azure-functions/durable/durable-functions-overview?tabs=csharp#async-http)
+    ``` PowerShell
+    Save-Package -Name 'Microsoft.Azure.Functions.PowershellWorker.PS7' -Source 'https://ci.appveyor.com/nuget/azure-functions-powershell-wor-0842fakagqy6/' -ProviderName NuGet -Path ~\Downloads\
+    ```
+
+  - Rename the downloaded .nuget file to .zip and extract the content of the `contentFiles\any\any\workers\powershell` folder to `workers\powershell` under the [Core Tools](https://github.com/Azure/azure-functions-powershell-worker/blob/dev/README.md#published-host), overwriting the existing files.
+
+- **Option 4**: Wait for the next (higher than 3.0.2534) release of Azure Functions Core Tools.
+
+## Azure setup
+
+_This step is required if you intend to run Durable PowerShell functions on Azure. Otherwise, feel free to skip this step._
 
-## 3. Install the required extensions
+- Create a PowerShell Function app on Azure.
+- Use the [instructions](https://github.com/Azure/azure-functions-powershell-worker/issues/371#issuecomment-641026259) to switch your app to PowerShell 7.
 
-Before deploying your app, run the following command in the app directory:
+## Sample app
+
+Start with the sample app at `examples/durable/DurableApp` in this repository.
+
+### 1. Install extensions
+
+Before deploying or starting it, run the following command in the app directory:
 
 ``` bash
 func extensions install --powershell
@@ -48,59 +60,50 @@ Please note that the Microsoft.Azure.WebJobs.Extensions.DurableTask package shou
 <PackageReference Include="Microsoft.Azure.WebJobs.Extensions.DurableTask" Version="2.0.0" />
 ```
 
-## 4. App settings
+### 2. Configure app settings
 
 Set the following app settings (if running on Azure) or just use the sample local.settings.json (if running locally):
-
-``` json
-{
-  "Values": {
-    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
-    "AzureWebJobsFeatureFlags": "AllowSynchronousIO",
-    "FUNCTIONS_WORKER_RUNTIME": "powershell",
-    "PSWorkerInProcConcurrencyUpperBound": 10
-  }
-}
-```
-
-- Make sure `AzureWebJobsStorage` [points to a valid Azure storage account](https://docs.microsoft.com/azure/azure-functions/functions-app-settings#azurewebjobsstorage). This storage is required for data persisted by Durable Functions.
+- Make sure `AzureWebJobsStorage` [points to a valid Azure storage account](https://docs.microsoft.com/azure/azure-functions/functions-app-settings#azurewebjobsstorage). This storage is required for data persisted by Durable Functions. When you create a new Function app on Azure, it normally points to an automatically provisioned storage account. If you intend to run the app locally, you can either keep the "UseDevelopmentStorage=true" value in the sample local.settings.json (in this case you will also need to install and start Azure Storage Emulator), or replace it with a connection string pointing to a real Azure storage account.
 - `AzureWebJobsFeatureFlags` must contain `AllowSynchronousIO`. Don't ask.
-- `FUNCTIONS_WORKER_RUNTIME` must be set to `powershell`.
 - You may need to adjust `PSWorkerInProcConcurrencyUpperBound` to increase [concurrency](https://docs.microsoft.com/azure/azure-functions/functions-reference-powershell#concurrency) for the Fan-out/Fan-in pattern.
 
-## 5. Starting the app
+### 3. Deploy the app
 
-If you have `UseDevelopmentStorage=true` as the `AzureWebJobsStorage` value, remember to start the Azure Storage Emulator.
+If running locally, skip the step, otherwise deploy the app to Azure as you normally would.
 
-Configure the environment variable FUNCTIONS_WORKER_RUNTIME_VERSION to select PowerShell 7:
+### 4. Start the app
 
-``` PowerShell
-$env:FUNCTIONS_WORKER_RUNTIME_VERSION = '~7'
-```
+If running locally:
+- If you have `UseDevelopmentStorage=true` as the `AzureWebJobsStorage` value, remember to start the Azure Storage Emulator first.
+- Configure the environment variable FUNCTIONS_WORKER_RUNTIME_VERSION to select PowerShell 7:
+  ``` PowerShell
+  $env:FUNCTIONS_WORKER_RUNTIME_VERSION = '~7'
+  ```
+- Start the app:
+  ``` bash
+  func start
+  ```
 
-and start the app:
+If running on Azure:
+- Just start the app as you normally would.
 
-``` bash
-func start
-```
-
-## 6. Function Chaining pattern
+### 5. Try Function Chaining pattern
 
 Start the FunctionChainingStart function:
 
 ``` PowerShell
 Invoke-RestMethod 'http://localhost:7071/api/FunctionChainingStart'
 ```
 
-## 7. Fan-out/Fan-in pattern
+### 6. Try Fan-out/Fan-in pattern
 
 Start the FanOutFanInStart function:
 
 ``` PowerShell
 Invoke-RestMethod 'http://localhost:7071/api/FanOutFanInStart'
 ```
 
-## 8. Async HTTP APIs
+### 7. Try Async HTTP APIs pattern
 
 When you invoke FunctionChainingStart or FanOutFanInStart, it returns an HTTP 202 response with the orchestration management URLs, so you can start invoking statusQueryGetUri and wait for the orchestration to complete:
 
@@ -115,3 +118,7 @@ while ($true) {
     }
 }
 ```
+
+### 8. Have fun, experiment, participate!
+
+Please let us know how you use Durable PowerShell functions and what does not (_yet_) work as you expect. **Your feedback is highly appreciated**, please feel free to file [GitHub issues](https://github.com/Azure/azure-functions-powershell-worker/issues/new).
