Add version parameter to start_new method for orchestration instances

- Introduced optional `version` parameter in `DurableOrchestrationClient.start_new()`
- Updated related methods and documentation to support versioning
- Modified sample function app to accept version from query parameters
- Added unit test for URL construction with version

Author: AnatoliB

CHANGES_SUMMARY.md

@@ -0,0 +1,86 @@
+# Version Override Feature - Changes Summary
+
+## Overview
+Added the ability to pass a version parameter to `client.start_new()` to override the default version specified in `host.json`.
+
+## Changes Made
+
+### 1. DurableOrchestrationClient.py
+**Location**: `azure/durable_functions/models/DurableOrchestrationClient.py`
+
+#### Added `version` parameter to `start_new` method:
+- Added optional `version` parameter (line 52)
+- Updated docstring to document the new parameter
+- Passed version to `_get_start_new_url` helper method
+
+#### Updated `_get_start_new_url` helper method:
+- Added optional `version` parameter (line 646)
+- Appends version as query parameter when provided: `?version={version}`
+
+### 2. Sample Function App
+**Location**: `samples-v2/orchestration_versioning/function_app.py`
+
+Updated `http_start` function to:
+- Read version from query parameter: `req.params.get('version')`
+- Pass version to `client.start_new()` when provided
+- Log the version being used
+
+### 3. Sample README
+**Location**: `samples-v2/orchestration_versioning/README.md`
+
+Added new section "Overriding Version Programmatically" that documents:
+- How to pass version programmatically: `client.start_new("my_orchestrator", version="1.5")`
+- How to pass version via HTTP query parameter: `?version=2.0`
+- Use cases for explicit version override
+
+### 4. Unit Tests
+**Location**: `tests/models/test_DurableOrchestrationClient.py`
+
+Added `test_get_start_new_url_with_version` test to verify:
+- URL construction with version query parameter
+- Correct format: `orchestrators/{functionName}/{instanceId}?version={version}`
+
+## Usage Examples
+
+### Programmatic Usage
+```python
+# Start orchestration with specific version
+instance_id = await client.start_new("my_orchestrator", version="2.0")
+
+# Start with version and custom instance ID
+instance_id = await client.start_new(
+    "my_orchestrator", 
+    instance_id="custom-id-123",
+    version="1.5"
+)
+
+# Start with version and input
+instance_id = await client.start_new(
+    "my_orchestrator",
+    client_input={"key": "value"},
+    version="3.0"
+)
+```
+
+### HTTP Query Parameter Usage
+```bash
+# Start orchestration with version 2.0
+curl http://localhost:7071/api/orchestrators/my_orchestrator?version=2.0
+
+# Start orchestration with version 1.0
+curl http://localhost:7071/api/orchestrators/my_orchestrator?version=1.0
+```
+
+## Benefits
+
+1. **Testing**: Test new versions without modifying `host.json`
+2. **Gradual Rollout**: Control which requests use which version
+3. **Multi-Version Support**: Run multiple versions simultaneously
+4. **Flexibility**: Override version on a per-request basis
+
+## Backward Compatibility
+
+This change is fully backward compatible:
+- The `version` parameter is optional
+- When not provided, behavior remains unchanged (uses `defaultVersion` from `host.json`)
+- Existing code continues to work without modification

azure/durable_functions/models/DurableOrchestrationClient.py

@@ -48,7 +48,8 @@ def __init__(self, context: str):
     async def start_new(self,
                         orchestration_function_name: str,
                         instance_id: Optional[str] = None,
-                        client_input: Optional[Any] = None) -> str:
+                        client_input: Optional[Any] = None,
+                        version: Optional[str] = None) -> str:
         """Start a new instance of the specified orchestrator function.
 
         If an orchestration instance with the specified ID already exists, the
@@ -63,14 +64,17 @@ async def start_new(self,
             the Durable Functions extension will generate a random GUID (recommended).
         client_input : Optional[Any]
             JSON-serializable input value for the orchestrator function.
+        version : Optional[str]
+            The version to assign to the orchestration instance. If not specified,
+            the defaultVersion from host.json will be used.
 
         Returns
         -------
         str
             The ID of the new orchestration instance if successful, None if not.
         """
         request_url = self._get_start_new_url(
-            instance_id=instance_id, orchestration_function_name=orchestration_function_name)
+            instance_id=instance_id, orchestration_function_name=orchestration_function_name, version=version)
 
         trace_parent, trace_state = DurableOrchestrationClient._get_current_activity_context()
 
@@ -639,10 +643,15 @@ def _parse_purge_instance_history_response(
             raise Exception(result)
 
     def _get_start_new_url(
-            self, instance_id: Optional[str], orchestration_function_name: str) -> str:
+            self, instance_id: Optional[str], orchestration_function_name: str,
+            version: Optional[str] = None) -> str:
         instance_path = f'/{instance_id}' if instance_id is not None else ''
         request_url = f'{self._orchestration_bindings.rpc_base_url}orchestrators/' \
                       f'{orchestration_function_name}{instance_path}'
+        
+        if version is not None:
+            request_url += f'?version={version}'
+        
         return request_url
 
     def _get_raise_event_url(

samples-v2/orchestration_versioning/README.md

@@ -33,7 +33,7 @@ What happens to *existing orchestration instances* that were started *before* th
 6. Trigger the external event.
 7. Observe that the orchestration output.
 
-```
+```text
 Orchestration version: 1.0
 Suborchestration version: 2.0
 Hello from A!
@@ -42,3 +42,18 @@ Hello from A!
 Note that the value returned by `context.version` is permanently associated with the orchestrator instance and is not impacted by the `defaultVersion` change. As a result, the orchestrator follows the old execution path to guarantee deterministic replay behavior.
 
 However, the suborchestration version is `2.0` because this suborchestration was created *after* the `defaultVersion` change.
+
+## Overriding Version Programmatically
+
+In addition to using `defaultVersion` in `host.json`, you can also specify a version explicitly when starting an orchestration using the `version` parameter of `client.start_new()`:
+
+```python
+# Start with a specific version
+instance_id = await client.start_new("my_orchestrator", version="1.5")
+```
+
+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

samples-v2/orchestration_versioning/function_app.py

@@ -8,9 +8,17 @@
 @myApp.durable_client_input(client_name="client")
 async def http_start(req: func.HttpRequest, client):
     function_name = req.route_params.get('functionName')
-    instance_id = await client.start_new(function_name)
 
-    logging.info(f"Started orchestration with ID = '{instance_id}'.")
+    # Get optional version from query parameter
+    version = req.params.get('version')
+    
+    if version:
+        instance_id = await client.start_new(function_name, version=version)
+        logging.info(f"Started orchestration with ID = '{instance_id}' and version = '{version}'.")
+    else:
+        instance_id = await client.start_new(function_name)
+        logging.info(f"Started orchestration with ID = '{instance_id}'.")
+    
     return client.create_check_status_response(req, instance_id)
 
 @myApp.orchestration_trigger(context_name="context")

tests/models/test_DurableOrchestrationClient.py

@@ -82,6 +82,17 @@ def test_get_start_new_url(binding_string):
     assert expected_url == start_new_url
 
 
+def test_get_start_new_url_with_version(binding_string):
+    client = DurableOrchestrationClient(binding_string)
+    instance_id = "2e2568e7-a906-43bd-8364-c81733c5891e"
+    function_name = "my_function"
+    version = "2.0"
+    start_new_url = client._get_start_new_url(instance_id, function_name, version)
+    expected_url = replace_stand_in_bits(
+        f"{RPC_BASE_URL}orchestrators/{function_name}/{instance_id}?version={version}")
+    assert expected_url == start_new_url
+
+
 def test_get_input_returns_none_when_none_supplied():
     result = DurableOrchestrationClient._get_json_input(None)
     assert result is None