feat(interceptors): added Interceptor page for .NET#4603
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📖 Docs PR preview links
|
brianmacdonald-temporal
left a comment
brianmacdonald-temporal
left a comment
There was a problem hiding this comment.
Just a couple of small notes
flippedcoder
force-pushed
the
mm/dotnet-interceptors
branch
from
afe9d24 to
1e042d8
Compare
|
|
||
| Interceptors are SDK hooks that let you intercept inbound and outbound Temporal calls. You use them to apply shared | ||
| behavior across many calls, such as tracing and authorization, before calls reach the application code and after they return. | ||
| This is similar to middleware in other frameworks. |
There was a problem hiding this comment.
I like this line. I think it helps people immediately reify the idea.
| Pass interceptors in the `Interceptors` argument of `TemporalClient.ConnectAsync`. Client interceptors modify outbound calls such | ||
| as starting and signaling Workflows. | ||
|
|
||
| ```dotnet |
|
|
||
| Interceptors are SDK hooks that let you intercept inbound and outbound Temporal calls. You use them to apply shared | ||
| behavior across many calls, such as tracing and authorization, before calls reach the application code and after they return. | ||
| This is similar to middleware in other frameworks. |
There was a problem hiding this comment.
Python calls out some specific middleware examples. Analogous example for .NET would be https://learn.microsoft.com/en-us/aspnet/core/fundamentals/middleware
| * Outbound interceptors wrap network calls, running before they reach the network and after they return. | ||
| * Inbound interceptors run after the network hop, wrapping application code and running before it starts and after it returns. | ||
|
|
||
| Those further break down into different interceptor types. |
There was a problem hiding this comment.
Should we include a table or list of the interceptor types, what they are used for, where they run, and examples of things that call them?
|
|
||
| ### Register on the Client | ||
|
|
||
| Pass interceptors in the `Interceptors` argument of `TemporalClient.ConnectAsync`. Client interceptors modify outbound calls such |
There was a problem hiding this comment.
Technically not correct. Interceptors is a property on TemporalClientConnectOptions (which is what the new() is creating in the following example).
|
|
||
| ### Register on the Worker only | ||
|
|
||
| If your interceptor doesn't affect the Client, you can pass interceptors in the `Interceptors` argument of `TemporalWorker()`. |
There was a problem hiding this comment.
Same as https://github.com/temporalio/documentation/pull/4603/changes#r3284706388, but the options type is TemporalWorkerOptions. The sample below shows it correctly.
|
|
||
| ### Implementing Worker call Interceptors | ||
|
|
||
| To modify inbound Workflow and Activity calls, define a class implementing [`IWorkerInterceptor`](https://dotnet.temporal.io/api/Temporalio.Worker.Interceptors.IWorkerInterceptor.html). It provides `InterceptActivity()`, `InterceptWorkflow()`, and `InterceptNexusOperation()` methods for Activity, Workflow, and Nexus interception. |
There was a problem hiding this comment.
InterceptNexusOperation should be added into the sample below, even if it just returns the next interceptor, just like InterceptWorkflow. Using snipsync would reveal this issue because the code would actually be built in the temporalio/features repo.
| var client = await TemporalClient.ConnectAsync(new() | ||
| { | ||
| TargetHost = "localhost:7233", | ||
| Interceptors = [interceptor], |
There was a problem hiding this comment.
Python sample uses TracingInterceptor as the example here, and this is available in the .NET SDK as well. Consider doing the same and maybe refer to the observability doc.
| client, | ||
| new TemporalWorkerOptions("my-task-queue") | ||
| { | ||
| Interceptors = new IWorkerInterceptor[] |
There was a problem hiding this comment.
Can we use collection syntax (e.g. [interceptor]) instead of the explicit array syntax, just like the above example?
| @@ -0,0 +1,204 @@ | |||
| --- | |||
There was a problem hiding this comment.
Is there a page in the encyclopedia that needs to be updated to link to this new page?
|
|
||
| Workflow inbound and outbound interceptor methods also execute during [replay](/develop/dotnet/best-practices/testing-suite#replay). Use replay-safe APIs for logging, randomness, and time in these interceptors. | ||
| See [Develop Workflow logic](/develop/dotnet/workflows/basics#workflow-logic-requirements) for details. | ||
|
|
There was a problem hiding this comment.
The Python interceptors doc has some more information about writing generic code... The same can be written here and I think the check would be Workflow.Unsafe.IsReplaying
4 participants
What does this PR do?
Addresses #3875. .NET didn't have a page for interceptors and it's a request that's been brought up in the community a few times.
Notes to reviewers
┆Attachments: EDU-6406 feat(interceptors): added Interceptor page for .NET