Skip to content

Improve error message for manual orchestrator and entity function invocation - #3302

Merged
wangbill (YunchuWang) merged 7 commits into
devfrom
copilot/improve-error-message-orchestrator
Aug 25, 2026
Merged

wangbill (YunchuWang) merged 7 commits into
devfrom
copilot/improve-error-message-orchestrator

Conversation

Copilot AI commented Jan 5, 2026 •

Copy link
Copy Markdown
Contributor

Summary

What changed?

  • Return a clear InvalidOperationException when the Portal/Admin API directly invokes an orchestrator or entity trigger.
  • Handle both Admin API payload shapes: {"input":""} arrives as a serialized string, while {} arrives as a null trigger value.
  • Use worker-neutral guidance that applies to in-process, isolated, and other out-of-process workers.
  • Preserve the original ArgumentException, including the actual type, for other unsupported trigger values.
  • Add unit coverage and a real Core Tools/Admin API E2E test for orchestrator and entity invocation with both payload shapes.

Why is this change needed?

Manually invoking an orchestrator or entity function from the Azure Portal currently produces a binding conversion error that does not explain that these durable function types must be scheduled through a Durable client.

The host-side binding is shared by in-process and out-of-process execution. The guidance therefore avoids model-specific APIs such as StartNewAsync. Portal/Admin API invocation is detected from the actual host values: a serialized string when input is present and null when it is omitted. Other unexpected host/runtime values still report their concrete type.

Issues / work items


Project checklist

  • Documentation changes are not required
  • Release notes are not required for the next release
  • Backport is not required
  • All required tests have been added/updated (unit tests, E2E tests)
  • No extra work is required to be leveraged by OutOfProc SDKs
  • No change to the version of the WebJobs.Extensions.DurableTask package
  • No EventIds were added to EventSource logs
  • This change should be added to the v2.x branch
  • Breaking change?

AI-assisted code disclosure (required)

Was an AI tool used? (select one)

  • No
  • Yes, AI helped write parts of this PR (e.g., GitHub Copilot)
  • Yes, an AI agent generated most of this PR

If AI was used:

  • Tool(s): GitHub Copilot
  • AI-assisted areas/files: trigger binding providers, TriggerBindingProviderTests.cs, HttpHelpers.cs, and DirectInvocationTests.cs
  • What you changed after AI output: Restricted friendly errors to actual Admin API input shapes, made guidance worker-neutral, preserved diagnostic fallbacks, and validated the behavior through the real Core Tools/Admin API path.

AI verification (required if AI was used):

  • I understand the code and can explain it
  • I verified referenced APIs/types exist and are correct
  • I reviewed edge cases/failure paths (timeouts, retries, cancellation, exceptions)
  • I reviewed concurrency/async behavior
  • I checked for unintended breaking or behavior changes

Testing

Automated tests

Targeted trigger-binding tests:

dotnet test test/FunctionsV2/WebJobs.Extensions.DurableTask.Tests.V2.csproj \
  -p:IsTestProject=true \
  --filter FullyQualifiedName~TriggerBindingProviderTests \
  --no-restore

Passed on net8.0 and net10.0: 6/6 tests on each target, with no build or analyzer warnings.

Full FunctionsV2 non-E2E test suite previously passed on both targets: 422/422 tests on net8.0 and 422/422 tests on net10.0.

The dotnet-isolated E2E app build succeeded:

build-e2e-test.ps1 -SkipCoreTools -E2EAppName BasicDotNetIsolated -TargetFramework net8.0

DirectInvocationTests then passed 4/4 against a real Core Tools host in about 18 seconds. The test posts to /admin/functions/{functionName} and verifies host logs for:

  • HelloCities with {"input":""}
  • HelloCities with {} (the omitted-input-to-null gap)
  • Counter with {"input":""}
  • Counter with {} (the omitted-input-to-null gap)

The Core Tools host was cleaned up after the run.

Official Azure Pipelines build 300135 validated the current PR merge commit e216e820:

  • All 28 latest job attempts passed across both target frameworks, storage backends, language workers, smoke tests, build/unit tests, analyzers, dependency validation, and SDL checks.
  • The initial .NET isolated Net10 smoke attempt hit the pipeline's shared-output race (Microsoft.Azure.Functions.Worker.Extensions.DurableTask.deps.json was locked while the agent disk was 96.73% full). Retrying only that failed job passed with no source changes.
  • GitHub CodeQL (four language jobs), dependency submission, and CLA checks passed.

Manual validation (only if runtime/behavior changed)

Covered by the real Core Tools/Admin API E2E validation above.


Notes for reviewers

Activity functions are intentionally excluded. ActivityTriggerAttributeBindingProvider supports Portal/Admin string input, and the existing CallActivity_Like_From_Azure_Portal E2E test covers that behavior.

…ocation

Co-authored-by: YunchuWang <12449837+YunchuWang@users.noreply.github.com>
Copilot AI changed the title [WIP] Improve error message for orchestrator function invocation Improve error message for manual orchestrator and entity function invocation Jan 5, 2026
Copilot AI lite review requested due to automatic review settings August 20, 2026 18:58

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR improves the developer/user experience when an orchestrator or entity function is manually invoked (e.g., via the Azure Portal “Run” button) by replacing a cryptic binding conversion failure with a clearer exception and actionable guidance.

Changes:

  • Updated orchestrator trigger binding to throw a friendlier exception/message when the trigger input isn’t a valid orchestration context.
  • Updated entity trigger binding to throw a similar friendlier exception/message for consistency.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File Description
src/WebJobs.Extensions.DurableTask/Bindings/OrchestrationTriggerAttributeBindingProvider.cs Replaces the generic “unknown bind” exception with a direct-invocation guidance message for orchestrator trigger binding.
src/WebJobs.Extensions.DurableTask/Bindings/EntityTriggerAttributeBindingProvider.cs Applies the same style of direct-invocation guidance message for entity trigger binding.

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 620c8b07-1ed8-4070-ab0a-83a07d40580a
Copilot AI review requested due to automatic review settings August 21, 2026 21:04

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

@YunchuWang
wangbill (YunchuWang) marked this pull request as ready for review August 21, 2026 21:29
@YunchuWang

Copy link
Copy Markdown
Member

Azure Pipelines build 299636 was retried after three infrastructure failures. The retry cleared both Windows failures (Validate build and unit tests and Language E2E AzureStorageNet10).

The remaining Linux .NET isolated Net8 smoke job failed before test execution for the same agent-side reason as its first attempt: / was 96.38% full and MSBuild could not write test/SmokeTests/OOProcSmokeTests/DotNetIsolated/bin/output/DotNetIsolated.runtimeconfig.json because another process held the shared output file. No assertion or changed binding code failed.

Equivalent validation for commit 0010b5ca is green:

Copilot AI review requested due to automatic review settings August 24, 2026 16:56

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

@YunchuWang

Copy link
Copy Markdown
Member

Superseding the earlier infrastructure-failure note: official Azure Pipelines build 300022 validated the current PR merge commit and passed the complete 28-job matrix, including .NET isolated Net8, both Windows language E2E jobs, and build/unit tests.

Treat omitted Admin API input as direct invocation for orchestrator and entity triggers, and cover the real Core Tools endpoint behavior with E2E tests.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings August 24, 2026 23:11

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

@YunchuWang

Copy link
Copy Markdown
Member

Official Azure Pipelines build 300135 now validates the current PR merge commit e216e820: all 28 latest job attempts passed.

The first .NET isolated Net10 smoke attempt failed before host startup because the pipeline built net8/net10 into the same output directory, locking Microsoft.Azure.Functions.Worker.Extensions.DurableTask.deps.json; the agent also reported 96.73% disk usage. Retrying only that job passed without any source change. GitHub CodeQL, dependency submission, and CLA checks are also green.

Remove unreachable null fallbacks after direct invocation values have already been handled.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: bbfc6f4b-dec2-4d30-ace8-be903cca5b88
Copilot AI review requested due to automatic review settings August 25, 2026 12:55

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

throw new ArgumentException($"Don't know how to bind to {value?.GetType().Name ?? "null"}.", nameof(value));
throw new InvalidOperationException(
"Durable entity functions do not support direct invocation. " +
"Signal an entity from a client or orchestrator function by using a Durable client.");

@andystaples andystaples left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved, though the copilot nit is technically correct I'm not going to block on it

@YunchuWang
wangbill (YunchuWang) merged commit 5f7189c into dev Aug 25, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Need a friendlier error message when attempting to invoke an orchestrator function from the portal

4 participants