Merge pull request #99163 from anthonychu/20191216-tabify-durable-concepts

Tabify Durable Functions concepts articles

Author: v-albemi

articles/azure-functions/durable/durable-functions-custom-orchestration-status.md

@@ -8,7 +8,7 @@ ms.author: azfuncdf
 
 # Custom orchestration status in Durable Functions (Azure Functions)
 
-Custom orchestration status lets you set a custom status value for your orchestrator function. This status is provided via the HTTP GetStatus API or the `DurableOrchestrationClient.GetStatusAsync` API.
+Custom orchestration status lets you set a custom status value for your orchestrator function. This status is provided via the [HTTP GetStatus API](durable-functions-http-api.md#get-instance-status) or the [`GetStatusAsync` API](durable-functions-instance-management.md#query-instances) on the orchestration client.
 
 ## Sample use cases
 
@@ -19,7 +19,7 @@ Custom orchestration status lets you set a custom status value for your orchestr
 
 Clients can poll the status end point and display a progress UI that visualizes the current execution stage. The following sample demonstrates progress sharing:
 
-#### C#
+# [C#](#tab/csharp)
 
 ```csharp
 [FunctionName("E1_HelloSequence")]
@@ -46,7 +46,9 @@ public static string SayHello([ActivityTrigger] string name)
 }
 ```
 
-#### JavaScript (Functions 2.0 only)
+# [JavaScript](#tab/javascript)
+
+`E1_HelloSequence` orchestrator function:
 
 ```javascript
 const df = require("durable-functions");
@@ -66,15 +68,19 @@ module.exports = df.orchestrator(function*(context){
 });
 ```
 
+`E1_SayHello` activity function:
+
 ```javascript
 module.exports = async function(context, name) {
     return `Hello ${name}!`;
 };
 ```
 
+---
+
 And then the client will receive the output of the orchestration only when `CustomStatus` field is set to "London":
 
-#### C#
+# [C#](#tab/csharp)
 
 ```csharp
 [FunctionName("HttpStart")]
@@ -107,7 +113,7 @@ public static async Task<HttpResponseMessage> Run(
 }
 ```
 
-#### JavaScript (Functions 2.0 only)
+# [JavaScript](#tab/javascript)
 
 ```javascript
 const df = require("durable-functions");
@@ -139,11 +145,13 @@ module.exports = async function(context, req) {
 > [!NOTE]
 > In JavaScript, the `customStatus` field will be set when the next `yield` or `return` action is scheduled.
 
+---
+
 ### Output customization
 
 Another interesting scenario is segmenting users by returning customized output based on unique characteristics or interactions. With the help of custom orchestration status, the client-side code will stay generic. All main modifications will happen on the server side as shown in the following sample:
 
-#### C#
+# [C#](#tab/csharp)
 
 ```csharp
 [FunctionName("CityRecommender")]
@@ -181,7 +189,7 @@ public static void Run(
 }
 ```
 
-#### JavaScript (Functions 2.0 only)
+# [JavaScript](#tab/javascript)
 
 ```javascript
 const df = require("durable-functions");
@@ -214,11 +222,13 @@ module.exports = df.orchestrator(function*(context) {
 });
 ```
 
+---
+
 ### Instruction specification
 
 The orchestrator can provide unique instructions to the clients via the custom state. The custom status instructions will be mapped to the steps in the orchestration code:
 
-#### C#
+# [C#](#tab/csharp)
 
 ```csharp
 [FunctionName("ReserveTicket")]
@@ -246,7 +256,7 @@ public static async Task<bool> Run(
 }
 ```
 
-#### JavaScript (Functions 2.0 only)
+# [JavaScript](#tab/javascript)
 
 ```javascript
 const df = require("durable-functions");
@@ -273,11 +283,13 @@ module.exports = df.orchestrator(function*(context) {
 });
 ```
 
+---
+
 ## Sample
 
 In the following sample, the custom status is set first;
 
-### C#
+# [C#](#tab/csharp)
 
 ```csharp
 public static async Task SetStatusTest([OrchestrationTrigger] IDurableOrchestrationContext context)
@@ -292,7 +304,7 @@ public static async Task SetStatusTest([OrchestrationTrigger] IDurableOrchestrat
 }
 ```
 
-### JavaScript (Functions 2.0 only)
+# [JavaScript](#tab/javascript)
 
 ```javascript
 const df = require("durable-functions");
@@ -308,6 +320,8 @@ module.exports = df.orchestrator(function*(context) {
 });
 ```
 
+---
+
 While the orchestration is running, external clients can fetch this custom status:
 
 ```http

articles/azure-functions/durable/durable-functions-entities.md

@@ -45,11 +45,13 @@ An entity operation can also create, read, update, and delete the state of the e
 
 ## Define entities
 
-Currently, the two distinct APIs for defining entities are a:
+Currently, the two distinct APIs for defining entities are:
 
 **Function-based syntax**, where entities are represented as functions and operations are explicitly dispatched by the application. This syntax works well for entities with simple state, few operations, or a dynamic set of operations like in application frameworks. This syntax can be tedious to maintain because it doesn't catch type errors at compile time.
 
-**Class-based syntax**, where entities and operations are represented by classes and methods. This syntax produces more easily readable code and allows operations to be invoked in a type-safe way. The class-based syntax is a thin layer on top of the function-based syntax, so both variants can be used interchangeably in the same application.
+**Class-based syntax (.NET only)**, where entities and operations are represented by classes and methods. This syntax produces more easily readable code and allows operations to be invoked in a type-safe way. The class-based syntax is a thin layer on top of the function-based syntax, so both variants can be used interchangeably in the same application.
+
+# [C#](#tab/csharp)
 
 ### Example: Function-based syntax - C#
 
@@ -103,11 +105,13 @@ The state of this entity is an object of type `Counter`, which contains a field
 
 For more information on the class-based syntax and how to use it, see [Defining entity classes](durable-functions-dotnet-entities.md#defining-entity-classes).
 
+# [JavaScript](#tab/javascript)
+
 ### Example: JavaScript entity
 
 Durable entities are available in JavaScript starting with version **1.3.0** of the `durable-functions` npm package. The following code is the `Counter` entity implemented as a durable function written in JavaScript.
 
-**function.json**
+**Counter/function.json**
 ```json
 {
   "bindings": [
@@ -121,7 +125,7 @@ Durable entities are available in JavaScript starting with version **1.3.0** of
 }
 ```
 
-**index.js**
+**Counter/index.js**
 ```javascript
 const df = require("durable-functions");
 
@@ -142,6 +146,8 @@ module.exports = df.entity(function(context) {
 });
 ```
 
+---
+
 ## Access entities
 
 Entities can be accessed using one-way or two-way communication. The following terminology distinguishes the two forms of communication: 
@@ -157,13 +163,15 @@ Entities can be accessed from within client functions, from within orchestrator
 
 The following examples illustrate these various ways of accessing entities.
 
-> [!NOTE]
-> For simplicity, the following examples show the loosely typed syntax for accessing entities. In general, we recommend that you [access entities through interfaces](durable-functions-dotnet-entities.md#accessing-entities-through-interfaces) because it provides more type checking.
-
 ### Example: Client signals an entity
 
 To access entities from an ordinary Azure Function, which is also known as a client function, use the [entity client binding](durable-functions-bindings.md#entity-client). The following example shows a queue-triggered function signaling an entity using this binding.
 
+# [C#](#tab/csharp)
+
+> [!NOTE]
+> For simplicity, the following examples show the loosely typed syntax for accessing entities. In general, we recommend that you [access entities through interfaces](durable-functions-dotnet-entities.md#accessing-entities-through-interfaces) because it provides more type checking.
+
 ```csharp
 [FunctionName("AddFromQueue")]
 public static Task Run(
@@ -177,6 +185,8 @@ public static Task Run(
 }
 ```
 
+# [JavaScript](#tab/javascript)
+
 ```javascript
 const df = require("durable-functions");
 
@@ -187,12 +197,16 @@ module.exports = async function (context) {
 };
 ```
 
+---
+
 The term *signal* means that the entity API invocation is one-way and asynchronous. It's not possible for a client function to know when the entity has processed the operation. Also, the client function can't observe any result values or exceptions. 
 
 ### Example: Client reads an entity state
 
 Client functions can also query the state of an entity, as shown in the following example:
 
+# [C#](#tab/csharp)
+
 ```csharp
 [FunctionName("QueryCounter")]
 public static async Task<HttpResponseMessage> Run(
@@ -205,6 +219,8 @@ public static async Task<HttpResponseMessage> Run(
 }
 ```
 
+# [JavaScript](#tab/javascript)
+
 ```javascript
 const df = require("durable-functions");
 
@@ -216,12 +232,16 @@ module.exports = async function (context) {
 };
 ```
 
+---
+
 Entity state queries are sent to the Durable tracking store and return the entity's most recently persisted state. This state is always a "committed" state, that is, it's never a temporary intermediate state assumed in the middle of executing an operation. However, it's possible that this state is stale compared to the entity's in-memory state. Only orchestrations can read an entity's in-memory state, as described in the following section.
 
 ### Example: Orchestration signals and calls an entity
 
 Orchestrator functions can access entities by using APIs on the [orchestration trigger binding](durable-functions-bindings.md#orchestration-trigger). The following example code shows an orchestrator function calling and signaling a `Counter` entity.
 
+# [C#](#tab/csharp)
+
 ```csharp
 [FunctionName("CounterOrchestration")]
 public static async Task Run(
@@ -239,6 +259,8 @@ public static async Task Run(
 }
 ```
 
+# [JavaScript](#tab/javascript)
+
 ```javascript
 const df = require("durable-functions");
 
@@ -253,6 +275,8 @@ module.exports = df.orchestrator(function*(context){
 > [!NOTE]
 > JavaScript does not currently support signaling an entity from an orchestrator. Use `callEntity` instead.
 
+---
+
 Only orchestrations are capable of calling entities and getting a response, which could be either a return value or an exception. Client functions that use the [client binding](durable-functions-bindings.md#entity-client) can only signal entities.
 
 > [!NOTE]
@@ -263,6 +287,8 @@ Only orchestrations are capable of calling entities and getting a response, whic
 An entity function can send signals to other entities, or even itself, while it executes an operation.
 For example, we can modify the previous `Counter` entity example so that it sends a "milestone-reached" signal to some monitor entity when the counter reaches the value 100.
 
+# [C#](#tab/csharp)
+
 ```csharp
    case "add":
         var currentValue = ctx.GetState<int>();
@@ -276,6 +302,8 @@ For example, we can modify the previous `Counter` entity example so that it send
         break;
 ```
 
+# [JavaScript](#tab/javascript)
+
 ```javascript
     case "add":
         const amount = context.df.getInput();
@@ -287,7 +315,9 @@ For example, we can modify the previous `Counter` entity example so that it send
         break;
 ```
 
-## Entity coordination
+---
+
+## <a name="entity-coordination"></a>Entity coordination (currently .NET only)
 
 There might be times when you need to coordinate operations across multiple entities. For example, in a banking application, you might have entities that represent individual bank accounts. When you transfer funds from one account to another, you must ensure that the source account has sufficient funds. You also must ensure that updates to both the source and destination accounts are done in a transactionally consistent way.