Add versioning support for sub-orchestrators in Durable Functions

AnatoliB · AnatoliB · commit abc36196e7fc · 2025-10-03T23:23:38.000-07:00
- Introduced optional `version` parameter in `call_sub_orchestrator` and `call_sub_orchestrator_with_retry` methods.
- Updated `CallSubOrchestratorAction` and `CallSubOrchestratorWithRetryAction` to handle versioning.
- Enhanced README and sample functions to demonstrate version usage.
- Added comprehensive documentation on version override feature.
diff --git a/VERSION_FEATURE_SUMMARY.md b/VERSION_FEATURE_SUMMARY.md
@@ -0,0 +1,199 @@
+# Version Override Feature - Complete Summary
+
+## Overview
+
+Added comprehensive version override capabilities to Azure Durable Functions Python SDK:
+
+1. **Orchestration Start**: Pass version when starting orchestrations via `client.start_new()`
+2. **Sub-Orchestrators**: Pass version when calling sub-orchestrators via `context.call_sub_orchestrator()`
+3. **Sub-Orchestrators with Retry**: Pass version when calling sub-orchestrators with retry
+
+## Complete Changes
+
+### Core SDK Changes
+
+#### 1. DurableOrchestrationClient.py
+**Location**: `azure/durable_functions/models/DurableOrchestrationClient.py`
+
+**`start_new` method:**
+- Added optional `version: Optional[str] = None` parameter
+- Updated docstring to document version override behavior
+- Passes version to `_get_start_new_url()` helper
+
+**`_get_start_new_url` helper:**
+- Added optional `version: Optional[str] = None` parameter
+- Appends version as query parameter: `?version={version}` when provided
+
+#### 2. CallSubOrchestratorAction.py
+**Location**: `azure/durable_functions/models/actions/CallSubOrchestratorAction.py`
+
+- Added optional `version: Optional[str] = None` parameter to `__init__`
+- Stored `self.version` as instance attribute
+- Added version serialization in `to_json()` method: `add_attrib(json_dict, self, 'version', 'version')`
+
+#### 3. CallSubOrchestratorWithRetryAction.py
+**Location**: `azure/durable_functions/models/actions/CallSubOrchestratorWithRetryAction.py`
+
+- Added optional `version: Optional[str] = None` parameter to `__init__`
+- Stored `self.version` as instance attribute
+- Added version serialization in `to_json()` method: `add_attrib(json_dict, self, 'version', 'version')`
+
+#### 4. DurableOrchestrationContext.py
+**Location**: `azure/durable_functions/models/DurableOrchestrationContext.py`
+
+**`call_sub_orchestrator` method:**
+- Added optional `version: Optional[str] = None` parameter
+- Updated docstring with version documentation
+- Passes version to `CallSubOrchestratorAction(name, input_, instance_id, version)`
+
+**`call_sub_orchestrator_with_retry` method:**
+- Added optional `version: Optional[str] = None` parameter
+- Updated docstring with version documentation
+- Passes version to `CallSubOrchestratorWithRetryAction(name, retry_options, input_, instance_id, version)`
+
+### Sample Updates
+
+#### 5. Sample Function App
+**Location**: `samples-v2/orchestration_versioning/function_app.py`
+
+**`http_start` function:**
+- Reads version from query parameter: `version = req.params.get('version')`
+- Conditionally passes version to `client.start_new()`
+- Logs whether version was explicitly provided
+
+**`my_orchestrator` function:**
+- Demonstrates calling sub-orchestrator with explicit version: `version="1.5"`
+- Demonstrates calling sub-orchestrator without version (uses default)
+- Returns both results to show version difference
+
+#### 6. Sample README
+**Location**: `samples-v2/orchestration_versioning/README.md`
+
+Added comprehensive documentation:
+- "Overriding Version Programmatically" section for `client.start_new()`
+- "Passing Version to Sub-Orchestrators" section
+- Code examples for all use cases
+- Explanation of benefits and use cases
+
+### Testing
+
+#### 7. Unit Tests
+**Location**: `tests/models/test_DurableOrchestrationClient.py`
+
+Added `test_get_start_new_url_with_version`:
+- Verifies URL construction with version parameter
+- Validates format: `{base_url}orchestrators/{functionName}/{instanceId}?version={version}`
+
+## Usage Examples
+
+### 1. Starting Orchestration with Version
+
+```python
+# Via client.start_new()
+instance_id = await client.start_new("my_orchestrator", version="2.0")
+
+# Via HTTP query parameter
+# GET /api/orchestrators/my_orchestrator?version=2.0
+```
+
+### 2. Calling Sub-Orchestrator with Version
+
+```python
+# Without retry
+sub_result = yield context.call_sub_orchestrator(
+    'my_sub_orchestrator',
+    input_={'key': 'value'},
+    version="1.5"
+)
+
+# With retry
+sub_result = yield context.call_sub_orchestrator_with_retry(
+    'my_sub_orchestrator',
+    retry_options=retry_options,
+    input_={'key': 'value'},
+    version="2.0"
+)
+```
+
+### 3. Mixed Version Orchestration
+
+```python
+@myApp.orchestration_trigger(context_name="context")
+def my_orchestrator(context: df.DurableOrchestrationContext):
+    # Parent uses version from client.start_new() or defaultVersion
+    
+    # Sub-orchestrator with explicit version
+    sub_v1 = yield context.call_sub_orchestrator('processor', version="1.0")
+    
+    # Sub-orchestrator with different explicit version
+    sub_v2 = yield context.call_sub_orchestrator('processor', version="2.0")
+    
+    # Sub-orchestrator using default version
+    sub_default = yield context.call_sub_orchestrator('processor')
+    
+    return [sub_v1, sub_v2, sub_default]
+```
+
+## Benefits
+
+### Testing
+- Test new versions without modifying `host.json`
+- Run integration tests with specific versions
+- Verify version-specific behavior
+
+### Gradual Rollout
+- Control which requests use which version
+- Perform A/B testing between versions
+- Gradually migrate traffic to new versions
+
+### Multi-Version Support
+- Run multiple orchestration versions simultaneously
+- Support different clients with different version requirements
+- Maintain backward compatibility during transitions
+
+### Sub-Orchestrator Flexibility
+- Mix different sub-orchestrator versions in one parent
+- Incrementally upgrade sub-orchestrators
+- Test new sub-orchestrator versions in production
+
+## Backward Compatibility
+
+All changes are fully backward compatible:
+
+✅ **Optional Parameters**: All `version` parameters are optional  
+✅ **Default Behavior**: When not specified, uses `defaultVersion` from `host.json`  
+✅ **Existing Code**: All existing code continues to work without modification  
+✅ **API Stability**: No breaking changes to existing method signatures
+
+## Version Precedence
+
+The version resolution order is:
+
+1. **Explicit version parameter** (highest priority)
+   - Passed to `client.start_new()`, `call_sub_orchestrator()`, etc.
+2. **defaultVersion in host.json** (fallback)
+   - Used when no explicit version is provided
+
+## Architecture Flow
+
+```
+HTTP Request with ?version=2.0
+    ↓
+http_start function
+    ↓
+client.start_new("my_orchestrator", version="2.0")
+    ↓
+DurableOrchestrationClient._get_start_new_url()
+    ↓
+POST to: orchestrators/my_orchestrator?version=2.0
+    ↓
+Durable Functions Extension assigns version="2.0"
+    ↓
+context.version == "2.0" in orchestrator
+    ↓
+context.call_sub_orchestrator('sub', version="1.5")
+    ↓
+CallSubOrchestratorAction with version="1.5"
+    ↓
+Sub-orchestrator runs with version="1.5"
+```
diff --git a/azure/durable_functions/models/DurableOrchestrationContext.py b/azure/durable_functions/models/DurableOrchestrationContext.py
@@ -285,7 +285,8 @@ def call_http(self, method: str, uri: str, content: Optional[str] = None,
 
     def call_sub_orchestrator(self,
                               name: Union[str, Callable], input_: Optional[Any] = None,
-                              instance_id: Optional[str] = None) -> TaskBase:
+                              instance_id: Optional[str] = None,
+                              version: Optional[str] = None) -> TaskBase:
         """Schedule sub-orchestration function named `name` for execution.
 
         Parameters
@@ -296,6 +297,9 @@ def call_sub_orchestrator(self,
             The JSON-serializable input to pass to the orchestrator function.
         instance_id: Optional[str]
             A unique ID to use for the sub-orchestration instance.
+        version: Optional[str]
+            The version to assign to the sub-orchestration instance. If not specified,
+            the defaultVersion from host.json will be used.
 
         Returns
         -------
@@ -313,14 +317,15 @@ def call_sub_orchestrator(self,
         if isinstance(name, FunctionBuilder):
             name = self._get_function_name(name, OrchestrationTrigger)
 
-        action = CallSubOrchestratorAction(name, input_, instance_id)
+        action = CallSubOrchestratorAction(name, input_, instance_id, version)
         task = self._generate_task(action)
         return task
 
     def call_sub_orchestrator_with_retry(self,
                                          name: Union[str, Callable], retry_options: RetryOptions,
                                          input_: Optional[Any] = None,
-                                         instance_id: Optional[str] = None) -> TaskBase:
+                                         instance_id: Optional[str] = None,
+                                         version: Optional[str] = None) -> TaskBase:
         """Schedule sub-orchestration function named `name` for execution, with retry-options.
 
         Parameters
@@ -333,6 +338,9 @@ def call_sub_orchestrator_with_retry(self,
             The JSON-serializable input to pass to the activity function. Defaults to None.
         instance_id: str
             The instance ID of the sub-orchestrator to call.
+        version: Optional[str]
+            The version to assign to the sub-orchestration instance. If not specified,
+            the defaultVersion from host.json will be used.
 
         Returns
         -------
@@ -350,7 +358,7 @@ def call_sub_orchestrator_with_retry(self,
         if isinstance(name, FunctionBuilder):
             name = self._get_function_name(name, OrchestrationTrigger)
 
-        action = CallSubOrchestratorWithRetryAction(name, retry_options, input_, instance_id)
+        action = CallSubOrchestratorWithRetryAction(name, retry_options, input_, instance_id, version)
         task = self._generate_task(action, retry_options)
         return task
 
diff --git a/azure/durable_functions/models/actions/CallSubOrchestratorAction.py b/azure/durable_functions/models/actions/CallSubOrchestratorAction.py
@@ -11,10 +11,11 @@ class CallSubOrchestratorAction(Action):
     """Defines the structure of the Call SubOrchestrator object."""
 
     def __init__(self, function_name: str, _input: Optional[Any] = None,
-                 instance_id: Optional[str] = None):
+                 instance_id: Optional[str] = None, version: Optional[str] = None):
         self.function_name: str = function_name
         self._input: str = dumps(_input, default=_serialize_custom_object)
         self.instance_id: Optional[str] = instance_id
+        self.version: Optional[str] = version
 
         if not self.function_name:
             raise ValueError("function_name cannot be empty")
@@ -37,4 +38,5 @@ def to_json(self) -> Dict[str, Union[str, int]]:
         add_attrib(json_dict, self, 'function_name', 'functionName')
         add_attrib(json_dict, self, '_input', 'input')
         add_attrib(json_dict, self, 'instance_id', 'instanceId')
+        add_attrib(json_dict, self, 'version', 'version')
         return json_dict
diff --git a/azure/durable_functions/models/actions/CallSubOrchestratorWithRetryAction.py b/azure/durable_functions/models/actions/CallSubOrchestratorWithRetryAction.py
@@ -13,11 +13,12 @@ class CallSubOrchestratorWithRetryAction(Action):
 
     def __init__(self, function_name: str, retry_options: RetryOptions,
                  _input: Optional[Any] = None,
-                 instance_id: Optional[str] = None):
+                 instance_id: Optional[str] = None, version: Optional[str] = None):
         self.function_name: str = function_name
         self._input: str = dumps(_input, default=_serialize_custom_object)
         self.retry_options: RetryOptions = retry_options
         self.instance_id: Optional[str] = instance_id
+        self.version: Optional[str] = version
 
         if not self.function_name:
             raise ValueError("function_name cannot be empty")
@@ -41,4 +42,5 @@ def to_json(self) -> Dict[str, Union[str, int]]:
         add_attrib(json_dict, self, '_input', 'input')
         add_json_attrib(json_dict, self, 'retry_options', 'retryOptions')
         add_attrib(json_dict, self, 'instance_id', 'instanceId')
+        add_attrib(json_dict, self, 'version', 'version')
         return json_dict
diff --git a/samples-v2/orchestration_versioning/README.md b/samples-v2/orchestration_versioning/README.md
@@ -52,8 +52,23 @@ In addition to using `defaultVersion` in `host.json`, you can also specify a ver
 instance_id = await client.start_new("my_orchestrator", version="1.5")
 ```
 
+You can also specify a version when calling sub-orchestrators from within an orchestrator function:
+
+```python
+# Call sub-orchestrator with specific version
+sub_result = yield context.call_sub_orchestrator('my_sub_orchestrator', version="1.5")
+
+# Call sub-orchestrator with retry and specific version
+sub_result = yield context.call_sub_orchestrator_with_retry(
+    'my_sub_orchestrator',
+    retry_options=retry_options,
+    version="2.0"
+)
+```
+
 When a version is explicitly provided, it takes precedence over the `defaultVersion` in `host.json`. This allows you to:
 
 - Test new orchestration versions without changing configuration
 - Run multiple versions simultaneously
 - Gradually roll out new versions by controlling which requests use which version
+- Running A/B tests with different sub-orchestrator implementations
diff --git a/samples-v2/orchestration_versioning/function_app.py b/samples-v2/orchestration_versioning/function_app.py
@@ -37,9 +37,19 @@ def my_orchestrator(context: df.DurableOrchestrationContext):
     # yield context.wait_for_external_event("Continue")
     # context.set_custom_status("Continue event received")
     
-    # New sub-orchestrations will use the current defaultVersion specified in host.json
-    sub_result = yield context.call_sub_orchestrator('my_sub_orchestrator')
-    return [f'Orchestration version: {context.version}', f'Suborchestration version: {sub_result}', activity_result]
+    # You can explicitly pass a version to sub-orchestrators
+    # This demonstrates calling sub-orchestrator with version="0.9"
+    sub_result_with_version = yield context.call_sub_orchestrator('my_sub_orchestrator', version="0.9")
+    
+    # Without specifying version, the sub-orchestrator will use the current defaultVersion
+    sub_result_default = yield context.call_sub_orchestrator('my_sub_orchestrator')
+    
+    return [
+        f'Orchestration version: {context.version}', 
+        f'Suborchestration version (explicit): {sub_result_with_version}',
+        f'Suborchestration version (default): {sub_result_default}',
+        activity_result
+    ]
 
 @myApp.orchestration_trigger(context_name="context")
 def my_sub_orchestrator(context: df.DurableOrchestrationContext):
