Skip to content

Changes to add .NET SDK support - #12

Merged
starfleeth merged 19 commits into
codex/refactor-sdk-referencesfrom
dotnet_sdk_changes
Sep 3, 2026
Merged

Changes to add .NET SDK support#12
starfleeth merged 19 commits into
codex/refactor-sdk-referencesfrom
dotnet_sdk_changes

Conversation

@harish-narayanappa-10

@harish-narayanappa-10 harish-narayanappa-10 commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

What was changed

  • Add .NET SDK support for Serverless Workers on AWS Lambda
  • Documents the .NET SDK alongside other languages
  • Corrects the sample location: the docs link to a branch (blob/ea/aws-lambda) that no longer exists; the sample is on main at src/LambdaWorker
  • removed claudisms (redundant/irrelevant/duplicated information) that I could find

.NET specifics documented

  • Separate NuGet package in lockstep with Temporalio 1.18.0
  • TemporalLambdaWorker.CreateHandler as the entry point
  • Publish must be RID-specific (--runtime linux-x64 / linux-arm64):
    the SDK wraps a native Rust core, libtemporalio_sdk_core_c_bridge.so,
    which a portable publish omits.
  • Worker-level default versioning behavior is AutoUpgrade
  • The SSL_CERT_FILE / root CA issue on some Lambda .NET images, which
    presents as a TLS failure that is not a configuration problem.
  • Telemetry IAM permissions and --tracing-config Mode=Active, from the
    sample's enable-telemetry.sh.

Testing

Verified using an end to end creation/deployment/run of a sample application via Claude Code prompts

harish-narayanappa-10 and others added 15 commits August 31, 2026 19:09
Documents the .NET SDK alongside Go, Python, TypeScript, and Java,
verified against Temporalio.Extensions.Aws.Lambda 1.18.0 (public API read
from the package's own XML documentation) and samples-dotnet@main
src/LambdaWorker, which is maintained code with a test project.

.NET specifics documented:
- Separate NuGet package in lockstep with Temporalio 1.18.0, with
  OpenTelemetry in a second package rather than an extra on the first.
- TemporalLambdaWorker.CreateHandler as the entry point, with sync and
  async configure overloads; registrations go through WorkerOptions.
- Publish must be RID-specific (--runtime linux-x64 / linux-arm64):
  the SDK wraps a native Rust core, libtemporalio_sdk_core_c_bridge.so,
  which a portable publish omits. This is .NET's equivalent of Python's
  manylinux wheels and Go's GOARCH, with the same first-invocation
  failure mode. Includes the sample's presence check.
- The handler string has three colon-separated parts,
  ASSEMBLY::NAMESPACE.TYPE::METHOD -- the only SDK with that shape.
- Worker-level default versioning behavior is AutoUpgrade, where
  TypeScript's is PINNED. Defaults are not uniform; set them explicitly.
- The SSL_CERT_FILE / root CA issue on some Lambda .NET images, which
  presents as a TLS failure that is not a configuration problem.
- Telemetry IAM permissions and --tracing-config Mode=Active, from the
  sample's enable-telemetry.sh.

Also corrects the sample location: the docs link to a branch
(blob/ea/aws-lambda) that no longer exists; the sample is on main at
src/LambdaWorker.

Note that .NET uses --timeout 600 and --memory-size 256, the same as Go,
Python and TypeScript, which supports reading Java's 90/1024 as a
Java-specific choice rather than a documentation inconsistency.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Deployed a .NET hello-world Worker end to end on Lambda. Three findings,
none of which came from reading documentation.

SSL_CERT_FILE is required, not optional. An otherwise-correct .NET
deployment fails its first invocation with:

  Connection failed: Server connection error:
  tonic::transport::Error(Transport, NativeCertsNotFound)

because AWS's .NET 8 Lambda images force-override SSL_CERT_FILE and the
SDK's Rust core cannot load system root CAs. The variable now appears in
the .NET create-function block and the environment-variable table rather
than only in troubleshooting, since without it the deployment does not
work at all.

The error is also actively misleading: "certs not found" refers to the
OS root CA store, not to any credential, and the connection fails before
authentication is attempted. Diagnostics now says so explicitly and
gives two discriminators, because the natural response -- checking the
API key, Namespace, invocation role and External ID -- is wasted effort.
Only .NET is affected: Python shares the Rust core but its runtime image
does not override the variable, and Java uses the JVM truststore.

Workflow.Logger is silent by default in .NET, because
TemporalWorkerOptions.LoggerFactory defaults to the client's, which is
also unset. Activity Console.WriteLine still reaches CloudWatch, so the
gap looks selective rather than total. That completes a set of three
SDKs with three unrelated causes for the same symptom.

Also adds a caution to iam.md: read the invocation role's policy back
after any update-stack that changes LambdaFunctionARNs. UPDATE_COMPLETE
does not mean the ARNs are well-formed, the list is replaced rather than
merged, and malformed entries silently revoke access for every function
they omit. Includes the zsh $VAR:l expansion trap that produced exactly
that outcome during this run.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
# Conflicts:
#	README.md
#	references/aws-lambda/diagnostics.md
#	references/aws-lambda/observability.md
#	references/aws-lambda/setup.md
#	references/sdk-configuration.md
The merged branch corrected four unverified doc citations in setup.md's Java
create-function section. The SDK-reference refactor had moved that text to
sdk-java.md, so resolving the merge in favour of the new structure dropped
them. Apply them where the text now lives.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ule or technical claim changes.

  - SKILL.md: remove trailing rationale from four rules; correct the pre-question note to point at steps 2 and 3, not step 2 alone.
  - sdk-*.md: drop "useful" from the "Ordering when sources disagree" heading, which the refactor had copied into all five files.
@harish-narayanappa-10
harish-narayanappa-10 marked this pull request as ready for review September 3, 2026 18:28
@harish-narayanappa-10
harish-narayanappa-10 requested a review from a team as a code owner September 3, 2026 18:28
Comment thread README.md
Comment thread SKILL.md Outdated
@starfleeth

Copy link
Copy Markdown
Collaborator

Thanks for restacking this PR on top of #11. The branch relationship now looks correct. I still have several requested changes, organized by priority:

1. Ownership blockers

The shared files should remain provider-level orchestration references, while SDK-specific configuration belongs in the language reference.

  • Remove the build-toolchain enumeration added to setup.md. Each SDK reference should own its build and packaging prerequisites.
  • Remove the .NET-only SSL_CERT_FILE entry from the shared setup.md environment table. That belongs exclusively in sdk-dotnet.md.
  • Remove the shared telemetry IAM permissions and X-Ray command from sdk-dotnet.md. Keep the .NET-specific OTel integration there, followed by a reference to observability.md for shared infrastructure.
  • Keep diagnostics.md SDK-neutral. It should not count how many SDKs exhibit a symptom; it should identify the shared symptom and route to the selected SDK reference.

2. Prose and research-diary content

Please remove the research diary and authorial narration. Provenance should be expressed through stable source references, not descriptions of how a conclusion was reached during one deployment or documentation-reading session.

Examples include:

  • <!-- verified: reproduced and fixed on a real deployment -->
  • <!-- inferred from the sample ... the variable name is not stated in the .NET docs page read -->
  • “Temporal's own deploy script asserts the file is present before zipping, which is worth copying.”
  • “This is .NET's equivalent of Python's manylinux wheels and Go's GOARCH.”
  • “Two discriminators: the same credentials work from a local Worker…”

Several remain in sdk-dotnet.md and its diagnostic section.

Please retain the actionable, corroborated facts and remove the narrative around discovering or interpreting them.

3. .NET SDK correctness

The central APIs—TemporalLambdaWorkerOptions and config.ApplyOpenTelemetryDefaults()—match the current SDK source. A few correctness problems remain:

  • TemporalLambdaWorker.LoadClientConnectOptions is described as public, but it is internal in the current SDK implementation. ShutdownHooks is likewise internal and should not be presented as user-accessible configuration.
  • The logging example requires Microsoft.Extensions.Logging.Console and using Microsoft.Extensions.Logging; neither is included. The maintained sample declares those logging dependencies.
  • The OpenTelemetry example needs using Temporalio.Extensions.Aws.Lambda.OpenTelemetry; for the extension method to resolve. See the official extension example.
  • The packaging example calls both configuration files optional and then unconditionally copies both. A deployment that does not use one of them will fail before creating the zip.
  • “The timeout only has to clear startup” in the deployment guidance is incorrect. It must also accommodate task processing, Activities, and graceful shutdown.
  • The categorical statement that a portable publish omits the native library is not corroborated. The SDK documentation says the native library is automatically included on modern common platforms. Keep the explicit Lambda RID guidance and output-file check, but remove the unsupported causal assertion.

4. Namespace scope creep in SKILL.md

The additions around Namespace creation, mandatory “create a new one” options, region selection, and device-code login materially change the skill’s control-plane workflow. See SKILL.md lines 94–123.

Those changes are unrelated to adding .NET SDK support and should be removed from this PR. The associated exception added under “Out of Scope” should also be reverted. If that behavior is desirable, it should be reviewed independently in a dedicated PR.

Similarly, the broader changes to the Java reference should be excluded unless they are strictly required for .NET routing.

@starfleeth

Copy link
Copy Markdown
Collaborator

The above comment was written (ofc) by an agent. 1 and 2 are blockers in my view. 3 I'll you and the team decide if valid. 4- unless you and the team feels strongly we should suggest creating a new namespace, I suggest we remove this change.

@harish-narayanappa-10

Copy link
Copy Markdown
Contributor Author

Thanks for the detailed review. I’ve addressed all four sections:

  1. Ownership - Removed the build-toolchain enumeration and .NET-only SSL_CERT_FILE entry from setup.md; removed shared telemetry IAM/X-Ray instructions from sdk-dotnet.md and kept diagnostics.md SDK-neutral
  2. Prose - Removed research-diary comments and authorial narration while retaining the actionable guidance and adding stable source references
  3. .NET specifics - Removed internal APIs from the public configuration guidance, added the logging dependency/import and OTel extension import, made optional configuration-file copying conditional, corrected the timeout guidance, and removed the unsupported portable-publish assertion while retaining explicit Lambda RID guidance and the native-library check.
  4. Scope - Removed the namespace creation / control-plane additions and restored the original out-of-scope boundary.

The Java SDK that were present earlier have been removed and will be handled later

Please take another look when you have a chance

@starfleeth
starfleeth merged commit 139108b into codex/refactor-sdk-references Sep 3, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants