From dfb67a6f1eb61c3e8cf2759b5b04352cc721c667 Mon Sep 17 00:00:00 2001 From: Ryan Cartwright Date: Thu, 6 Mar 2025 22:58:28 +1100 Subject: [PATCH 01/14] add csharp reference docs --- docs/reference/csharp/api/api-delete.mdx | 121 ++++++++++++++ docs/reference/csharp/api/api-get.mdx | 104 ++++++++++++ docs/reference/csharp/api/api-patch.mdx | 121 ++++++++++++++ docs/reference/csharp/api/api-post.mdx | 121 ++++++++++++++ docs/reference/csharp/api/api-put.mdx | 121 ++++++++++++++ docs/reference/csharp/api/api-route-all.mdx | 130 ++++++++++++++ .../reference/csharp/api/api-route-delete.mdx | 115 +++++++++++++ docs/reference/csharp/api/api-route-get.mdx | 98 +++++++++++ docs/reference/csharp/api/api-route-patch.mdx | 117 +++++++++++++ docs/reference/csharp/api/api-route-post.mdx | 115 +++++++++++++ docs/reference/csharp/api/api-route-put.mdx | 115 +++++++++++++ docs/reference/csharp/api/api-route.mdx | 91 ++++++++++ docs/reference/csharp/api/api.mdx | 126 ++++++++++++++ docs/reference/csharp/batch/job-handler.mdx | 89 ++++++++++ docs/reference/csharp/batch/job-submit.mdx | 43 +++++ docs/reference/csharp/batch/job.mdx | 50 ++++++ docs/reference/csharp/index.mdx | 33 ++++ .../csharp/keyvalue/keyvalue-delete.mdx | 53 ++++++ .../csharp/keyvalue/keyvalue-get.mdx | 53 ++++++ .../csharp/keyvalue/keyvalue-keys.mdx | 90 ++++++++++ .../csharp/keyvalue/keyvalue-set.mdx | 56 +++++++ docs/reference/csharp/keyvalue/keyvalue.mdx | 158 ++++++++++++++++++ .../reference/csharp/queues/queue-dequeue.mdx | 96 +++++++++++ .../reference/csharp/queues/queue-enqueue.mdx | 99 +++++++++++ docs/reference/csharp/queues/queue.mdx | 98 +++++++++++ .../csharp/schedule/schedule-cron.mdx | 54 ++++++ .../csharp/schedule/schedule-every.mdx | 79 +++++++++ docs/reference/csharp/schedule/schedule.mdx | 74 ++++++++ .../csharp/secrets/secret-latest.mdx | 56 +++++++ docs/reference/csharp/secrets/secret-put.mdx | 62 +++++++ .../csharp/secrets/secret-version-access.mdx | 52 ++++++ .../csharp/secrets/secret-version.mdx | 60 +++++++ docs/reference/csharp/secrets/secret.mdx | 64 +++++++ .../csharp/sql/sql-connection-string.mdx | 31 ++++ docs/reference/csharp/sql/sql.mdx | 63 +++++++ .../csharp/storage/bucket-file-delete.mdx | 37 ++++ .../storage/bucket-file-downloadurl.mdx | 69 ++++++++ .../csharp/storage/bucket-file-read.mdx | 37 ++++ .../csharp/storage/bucket-file-uploadurl.mdx | 47 ++++++ .../csharp/storage/bucket-file-write.mdx | 45 +++++ docs/reference/csharp/storage/bucket-file.mdx | 38 +++++ .../reference/csharp/storage/bucket-files.mdx | 39 +++++ docs/reference/csharp/storage/bucket-on.mdx | 87 ++++++++++ docs/reference/csharp/storage/bucket.mdx | 62 +++++++ docs/reference/csharp/topic/topic-publish.mdx | 55 ++++++ .../csharp/topic/topic-subscribe.mdx | 98 +++++++++++ docs/reference/csharp/topic/topic.mdx | 50 ++++++ .../csharp/websocket/connection-close.mdx | 47 ++++++ .../csharp/websocket/connection-send.mdx | 78 +++++++++ .../csharp/websocket/websocket-connection.mdx | 30 ++++ .../csharp/websocket/websocket-on.mdx | 137 +++++++++++++++ docs/reference/csharp/websocket/websocket.mdx | 43 +++++ 52 files changed, 4007 insertions(+) create mode 100644 docs/reference/csharp/api/api-delete.mdx create mode 100644 docs/reference/csharp/api/api-get.mdx create mode 100644 docs/reference/csharp/api/api-patch.mdx create mode 100644 docs/reference/csharp/api/api-post.mdx create mode 100644 docs/reference/csharp/api/api-put.mdx create mode 100644 docs/reference/csharp/api/api-route-all.mdx create mode 100644 docs/reference/csharp/api/api-route-delete.mdx create mode 100644 docs/reference/csharp/api/api-route-get.mdx create mode 100644 docs/reference/csharp/api/api-route-patch.mdx create mode 100644 docs/reference/csharp/api/api-route-post.mdx create mode 100644 docs/reference/csharp/api/api-route-put.mdx create mode 100644 docs/reference/csharp/api/api-route.mdx create mode 100644 docs/reference/csharp/api/api.mdx create mode 100644 docs/reference/csharp/batch/job-handler.mdx create mode 100644 docs/reference/csharp/batch/job-submit.mdx create mode 100644 docs/reference/csharp/batch/job.mdx create mode 100644 docs/reference/csharp/index.mdx create mode 100644 docs/reference/csharp/keyvalue/keyvalue-delete.mdx create mode 100644 docs/reference/csharp/keyvalue/keyvalue-get.mdx create mode 100644 docs/reference/csharp/keyvalue/keyvalue-keys.mdx create mode 100644 docs/reference/csharp/keyvalue/keyvalue-set.mdx create mode 100644 docs/reference/csharp/keyvalue/keyvalue.mdx create mode 100644 docs/reference/csharp/queues/queue-dequeue.mdx create mode 100644 docs/reference/csharp/queues/queue-enqueue.mdx create mode 100644 docs/reference/csharp/queues/queue.mdx create mode 100644 docs/reference/csharp/schedule/schedule-cron.mdx create mode 100644 docs/reference/csharp/schedule/schedule-every.mdx create mode 100644 docs/reference/csharp/schedule/schedule.mdx create mode 100644 docs/reference/csharp/secrets/secret-latest.mdx create mode 100644 docs/reference/csharp/secrets/secret-put.mdx create mode 100644 docs/reference/csharp/secrets/secret-version-access.mdx create mode 100644 docs/reference/csharp/secrets/secret-version.mdx create mode 100644 docs/reference/csharp/secrets/secret.mdx create mode 100644 docs/reference/csharp/sql/sql-connection-string.mdx create mode 100644 docs/reference/csharp/sql/sql.mdx create mode 100644 docs/reference/csharp/storage/bucket-file-delete.mdx create mode 100644 docs/reference/csharp/storage/bucket-file-downloadurl.mdx create mode 100644 docs/reference/csharp/storage/bucket-file-read.mdx create mode 100644 docs/reference/csharp/storage/bucket-file-uploadurl.mdx create mode 100644 docs/reference/csharp/storage/bucket-file-write.mdx create mode 100644 docs/reference/csharp/storage/bucket-file.mdx create mode 100644 docs/reference/csharp/storage/bucket-files.mdx create mode 100644 docs/reference/csharp/storage/bucket-on.mdx create mode 100644 docs/reference/csharp/storage/bucket.mdx create mode 100644 docs/reference/csharp/topic/topic-publish.mdx create mode 100644 docs/reference/csharp/topic/topic-subscribe.mdx create mode 100644 docs/reference/csharp/topic/topic.mdx create mode 100644 docs/reference/csharp/websocket/connection-close.mdx create mode 100644 docs/reference/csharp/websocket/connection-send.mdx create mode 100644 docs/reference/csharp/websocket/websocket-connection.mdx create mode 100644 docs/reference/csharp/websocket/websocket-on.mdx create mode 100644 docs/reference/csharp/websocket/websocket.mdx diff --git a/docs/reference/csharp/api/api-delete.mdx b/docs/reference/csharp/api/api-delete.mdx new file mode 100644 index 000000000..0d8eb808e --- /dev/null +++ b/docs/reference/csharp/api/api-delete.mdx @@ -0,0 +1,121 @@ +--- +description: "Reference for Nitric's .NET library - Register an API route and set a specific HTTP DELETE handler on that route." +--- + +# .NET - Api.Delete() + +Register an API route and set a specific HTTP DELETE handler on that route. + + + This method is a convenient short version of + [Api().Route().Delete()](./api-route-delete) + + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Delete("/hello/:name", context => { + var name = context.Req.PathParams.get("name"); + + context.Res.Text($"Deleting {name}!"); + + return context; +}); + +Application.Run(); +``` + +## Parameters + + + + The path matcher to use for the route. Matchers accept path parameters in + the form of a colon prefixed string. The string provided will be used as + that path parameter's name when calling middleware and handlers. See [create + a route with path params](#create-a-route-with-path-params) + + + One or more middleware functions to use as the handler for HTTP requests. + Handlers can be sync or async. + + + +## Examples + +### Register a handler for DELETE requests + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Delete("/hello/:name", context => { + var name = context.Req.PathParams.get("name"); + + context.Res.Text($"Deleting {name}!"); + + return context; +}); + +Application.Run(); +``` + +### Chain functions as a single method handler + +When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. + +```csharp +using Nitric.Sdk; + +var api = Nitric.Api("main"); + +api.Delete("/hello/:userId", + (context, next) => { + var user = context.Req.PathParams["userId"]; + + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; + + // Return prematurely to end the middleware chain. + return context; + } + + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; + + context.Res.Text($"Deleting {user}"); + + return next(context); + } +); + +Nitric.Run(); +``` + +### Access the request body + +The DELETE request body is accessible from the `context.Req` object. + +```csharp +using Nitric.Sdk; + +var api = Nitric.Api("main"); + +api.Delete("/hello/:name", context => { + var body = context.Req.Json>(); + // parse, validate and store the request payload... +}); + +Nitric.Run(); +``` diff --git a/docs/reference/csharp/api/api-get.mdx b/docs/reference/csharp/api/api-get.mdx new file mode 100644 index 000000000..bf7c263c2 --- /dev/null +++ b/docs/reference/csharp/api/api-get.mdx @@ -0,0 +1,104 @@ +--- +description: "Reference for Nitric's .NET library - Register an API route and set a specific HTTP GET handler on that route." +--- + +# .NET - Api.Get() + +Register an API route and set a specific HTTP GET handler on that route. + + + This method is a convenient short version of + [Api().Route().Get()](./api-route-get) + + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Get("/hello/:name", context => { + var name = context.Req.PathParams.get("name"); + + context.Res.Text($"Getting {name}!"); + + return context; +}); + +Application.Run(); +``` + +## Parameters + + + + The path matcher to use for the route. Matchers accept path parameters in + the form of a colon prefixed string. The string provided will be used as + that path parameter's name when calling middleware and handlers. See [create + a route with path params](#create-a-route-with-path-params) + + + One or more middleware functions to use as the handler for HTTP requests. + Handlers can be sync or async. + + + +## Examples + +### Register a handler for GET requests + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Get("/hello/:name", context => { + var name = context.Req.PathParams.get("name"); + + context.Res.Text($"Getting {name}!"); + + return context; +}); + +Application.Run(); +``` + +### Chain functions as a single method handler + +When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Get("/hello/:userId", + (context, next) => { + var user = context.Req.PathParams["userId"]; + + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; + + // Return prematurely to end the middleware chain. + return context; + } + + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; + + context.Res.Text($"Getting {user}"); + + return next(context); + } +); + +Application.Run(); +``` diff --git a/docs/reference/csharp/api/api-patch.mdx b/docs/reference/csharp/api/api-patch.mdx new file mode 100644 index 000000000..3dfbc1365 --- /dev/null +++ b/docs/reference/csharp/api/api-patch.mdx @@ -0,0 +1,121 @@ +--- +description: "Reference for Nitric's .NET library - Register an API route and set a specific HTTP PATCH handler on that route." +--- + +# .NET - Api.Patch() + +Register an API route and set a specific HTTP PATCH handler on that route. + + + This method is a convenient short version of + [Api().Route().Patch()](./api-route-patch) + + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Patch("/hello/:name", context => { + var name = context.Req.PathParams.get("name"); + + context.Res.Text($"Patching {name}!"); + + return context; +}); + +Application.Run(); +``` + +## Parameters + + + + The path matcher to use for the route. Matchers accept path parameters in + the form of a colon prefixed string. The string provided will be used as + that path parameter's name when calling middleware and handlers. See [create + a route with path params](#create-a-route-with-path-params) + + + One or more middleware functions to use as the handler for HTTP requests. + Handlers can be sync or async. + + + +## Examples + +### Register a handler for PATCH requests + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Patch("/hello/:name", context => { + var name = context.Req.PathParams.get("name"); + + context.Res.Text($"Patching {name}!"); + + return context; +}); + +Application.Run(); +``` + +### Chain functions as a single method handler + +When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Patch("/hello/:userId", + (context, next) => { + var user = context.Req.PathParams["userId"]; + + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; + + // Return prematurely to end the middleware chain. + return context; + } + + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; + + context.Res.Text($"Patching {user}"); + + return next(context); + } +); + +Application.Run(); +``` + +### Access the request body + +The PATCH request body is accessible from the `context.Req` object. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Patch("/hello/:name", context => { + var body = context.Req.Json>(); + // parse, validate and store the request payload... +}); + +Application.Run(); +``` diff --git a/docs/reference/csharp/api/api-post.mdx b/docs/reference/csharp/api/api-post.mdx new file mode 100644 index 000000000..bdf483aab --- /dev/null +++ b/docs/reference/csharp/api/api-post.mdx @@ -0,0 +1,121 @@ +--- +description: "Reference for Nitric's .NET library - Register an API route and set a specific HTTP POST handler on that route." +--- + +# .NET - Api.Post() + +Register an API route and set a specific HTTP POST handler on that route. + + + This method is a convenient short version of + [Api().Route().Post()](./api-route-post) + + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Post("/hello/:name", context => { + var name = context.Req.PathParams.get("name"); + + context.Res.Text($"Creating {name}!"); + + return context; +}); + +Application.Run(); +``` + +## Parameters + + + + The path matcher to use for the route. Matchers accept path parameters in + the form of a colon prefixed string. The string provided will be used as + that path parameter's name when calling middleware and handlers. See [create + a route with path params](#create-a-route-with-path-params) + + + One or more middleware functions to use as the handler for HTTP requests. + Handlers can be sync or async. + + + +## Examples + +### Register a handler for POST requests + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Post("/hello/:name", context => { + var name = context.Req.PathParams.get("name"); + + context.Res.Text($"Creating {name}!"); + + return context; +}); + +Application.Run(); +``` + +### Chain functions as a single method handler + +When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Post("/hello/:userId", + (context, next) => { + var user = context.Req.PathParams["userId"]; + + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; + + // Return prematurely to end the middleware chain. + return context; + } + + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; + + context.Res.Text($"Creating {user}"); + + return next(context); + } +); + +Application.Run(); +``` + +### Access the request body + +The POST request body is accessible from the `ctx.req` object. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Post("/hello/:name", context => { + var body = context.Req.Json>(); + // parse, validate and store the request payload... +}); + +Application.Run(); +``` diff --git a/docs/reference/csharp/api/api-put.mdx b/docs/reference/csharp/api/api-put.mdx new file mode 100644 index 000000000..ca1aaa572 --- /dev/null +++ b/docs/reference/csharp/api/api-put.mdx @@ -0,0 +1,121 @@ +--- +description: "Reference for Nitric's .NET library - Register an API route and set a specific HTTP PUT handler on that route." +--- + +# .NET - Api.Put() + +Register an API route and set a specific HTTP PUT handler on that route. + + + This method is a convenient short version of + [Api().Route().Put()](./api-route-put) + + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Put("/hello/:name", context => { + var name = context.Req.PathParams.get("name"); + + context.Res.Text($"Updating {name}!"); + + return context; +}); + +Application.Run(); +``` + +## Parameters + + + + The path matcher to use for the route. Matchers accept path parameters in + the form of a colon prefixed string. The string provided will be used as + that path parameter's name when calling middleware and handlers. See [create + a route with path params](#create-a-route-with-path-params) + + + One or more middleware functions to use as the handler for HTTP requests. + Handlers can be sync or async. + + + +## Examples + +### Register a handler for PUT requests + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Put("/hello/:name", context => { + var name = context.Req.PathParams.get("name"); + + context.Res.Text($"Updating {name}!"); + + return context; +}); + +Application.Run(); +``` + +### Chain functions as a single method handler + +When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Put("/hello/:userId", + (context, next) => { + var user = context.Req.PathParams["userId"]; + + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; + + // Return prematurely to end the middleware chain. + return context; + } + + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; + + context.Res.Text($"Updating {user}"); + + return next(context); + } +); + +Application.Run(); +``` + +### Access the request body + +The PUT request body is accessible from the `ctx.req` object. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +api.Put("/hello/:name", context => { + var body = context.Req.Json>(); + // parse, validate and store the request payload... +}); + +Application.Run(); +``` diff --git a/docs/reference/csharp/api/api-route-all.mdx b/docs/reference/csharp/api/api-route-all.mdx new file mode 100644 index 000000000..748bb1572 --- /dev/null +++ b/docs/reference/csharp/api/api-route-all.mdx @@ -0,0 +1,130 @@ +--- +description: "Reference for Nitric's .NET library - Register a single handler for all HTTP Methods (GET, POST, PUT, DELETE, PATCH) on the route." +--- + +# .NET - Api.Route.All() + +Register a single handler for all HTTP Methods (GET, POST, PUT, DELETE, PATCH) on the route. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.All(context => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + context.Res.Json(responseBody); + + return context; +}); + +Application.Run(); +``` + +## Parameters + + + + One or more middleware functions to use as the handler for HTTP requests. + Handlers can be sync or async. + + + +## Notes + +When using the `All()` method to register a single function as the handler for all HTTP methods, none of the other methods should be defined on that route. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.All(context => { + /* handle all requests */ +}); + +// Don't call `Get()`, `Post()`, etc., they're already handled by `all()` +route.Get(context => { + // This handler won't work +}) + +Application.Run(); +``` + +## Examples + +### Register a method handler function + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.All(context => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + context.Res.Json(responseBody); + + return context; +}); + +Application.Run(); +``` + +### Chain functions as a single method handler + +When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.All((context, next) => { + var user = context.Req.PathParams["userId"]; + + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; + + // Return prematurely to end the middleware chain. + return context; + } + + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; + + context.Res.Text($"Handling {user}"); + + return next(context); + } +); + +Application.Run(); +``` + +### Access the request body + +For methods that include a request body, such as `POST` and `PUT`, you can access the body from the `ctx.req` object. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.All(context => { + var body = context.Req.Json>(); + // parse, validate and store the request payload... +}); + +Application.Run(); +``` diff --git a/docs/reference/csharp/api/api-route-delete.mdx b/docs/reference/csharp/api/api-route-delete.mdx new file mode 100644 index 000000000..dfc100a37 --- /dev/null +++ b/docs/reference/csharp/api/api-route-delete.mdx @@ -0,0 +1,115 @@ +--- +description: "Reference for Nitric's v0 .NET library - Register a handler for HTTP DELETE requests to the route." +--- + +# .NET - api.route.delete() + +Register a handler for HTTP DELETE requests to the route. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.Delete(context => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + context.Res.Json(responseBody); + + return context; +}); + +Application.Run(); +``` + +## Parameters + + + + The path matcher to use for the route. Matchers accept path parameters in + the form of a colon prefixed string. The string provided will be used as + that path parameter's name when calling middleware and handlers. See [create + a route with path params](#create-a-route-with-path-params) + + + One or more middleware functions to use as the handler for HTTP requests. + Handlers can be sync or async. + + + +## Examples + +### Register a handler for DELETE requests + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.Delete(context => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + context.Res.Json(responseBody); + + return context; +}); + +Application.Run(); +``` + +### Chain functions as a single method handler + +When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Nitric.Api("main").Route("/customers/:userId"); + +route.Delete((context, next) => { + var user = context.Req.PathParams["userId"]; + + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; + + // Return prematurely to end the middleware chain. + return context; + } + + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; + + context.Res.Text($"Deleting {user}"); + + return next(context); + } +); + +Application.Run(); +``` + +### Access the request body + +The DELETE request body is accessible from the `ctx.req` object. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.Delete(context => { + var body = context.Req.Json>(); + // parse, validate and store the request payload... +}); + +Application.Run(); +``` diff --git a/docs/reference/csharp/api/api-route-get.mdx b/docs/reference/csharp/api/api-route-get.mdx new file mode 100644 index 000000000..b30fc94ad --- /dev/null +++ b/docs/reference/csharp/api/api-route-get.mdx @@ -0,0 +1,98 @@ +--- +description: "Reference for Nitric's .NET library - Register a handler for HTTP GET requests to the route." +--- + +# .NET - Api.Route.Get() + +Register a handler for HTTP GET requests to the route. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.Get(context => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + context.Res.Json(responseBody); + + return context; +}); + +Application.Run(); +``` + +## Parameters + + + + The path matcher to use for the route. Matchers accept path parameters in + the form of a colon prefixed string. The string provided will be used as + that path parameter's name when calling middleware and handlers. See [create + a route with path params](#create-a-route-with-path-params) + + + One or more middleware functions to use as the handler for HTTP requests. + Handlers can be sync or async. + + + +## Examples + +### Register a handler for GET requests + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.Get(context => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + context.Res.Json(responseBody); + + return context; +}); + +Application.Run(); +``` + +### Chain functions as a single method handler + +When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.Get((context, next) => { + var user = context.Req.PathParams["userId"]; + + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; + + // Return prematurely to end the middleware chain. + return context; + } + + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; + + context.Res.Text($"Getting {user}"); + + return next(context); + } +); + +Application.Run(); +``` diff --git a/docs/reference/csharp/api/api-route-patch.mdx b/docs/reference/csharp/api/api-route-patch.mdx new file mode 100644 index 000000000..ec507dc4a --- /dev/null +++ b/docs/reference/csharp/api/api-route-patch.mdx @@ -0,0 +1,117 @@ +--- +description: "Reference for Nitric's .NET library - Register a handler for HTTP PATCH requests to the route." +--- + +# .NET - Api.Route.Patch() + +Register a handler for HTTP PATCH requests to the route. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers/:userId"); + +route.Patch(context => { + var user = context.Req.PathParams["userId"]; + + context.Res.Text($"Patching {user}"); + + return next(context); + } +); + +Application.Run(); +``` + +## Parameters + + + + The path matcher to use for the route. Matchers accept path parameters in + the form of a colon prefixed string. The string provided will be used as + that path parameter's name when calling middleware and handlers. See [create + a route with path params](#create-a-route-with-path-params) + + + One or more middleware functions to use as the handler for HTTP requests. + Handlers can be sync or async. + + + +## Examples + +### Register a handler for PATCH requests + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers/:userId"); + +route.Patch(context => { + var user = context.Req.PathParams["userId"]; + + context.Res.Text($"Patching {user}"); + + return next(context); + } +); + +Application.Run(); +``` + +### Chain functions as a single method handler + +When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. + +```csharp +using Application = Nitric.Sdk.Application; + +var route = Application.Api("main").Route("/customers/:userId"); + +route.Patch((context, next) => { + var user = context.Req.PathParams["userId"]; + + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; + + // Return prematurely to end the middleware chain. + return context; + } + + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; + + context.Res.Text($"Patching {user}"); + + return next(context); + } +); + +Application.Run(); +``` + +### Access the request body + +The PATCH request body is accessible from the `context.Req` object. + +```csharp +using Application = Nitric.Sdk.Application; + +var api = Application.Api("main").Route("/customers"); + +route.Patch(context => { + var body = context.Req.Json>(); + // parse, validate and store the request payload... +}); + +Application.Run(); +``` diff --git a/docs/reference/csharp/api/api-route-post.mdx b/docs/reference/csharp/api/api-route-post.mdx new file mode 100644 index 000000000..1c9e59370 --- /dev/null +++ b/docs/reference/csharp/api/api-route-post.mdx @@ -0,0 +1,115 @@ +--- +description: "Reference for Nitric's .NET library - Register a handler for HTTP POST requests to the route." +--- + +# .NET - Api.Route.Post() + +Register a handler for HTTP POST requests to the route. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.Post(context => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + context.Res.Json(responseBody); + + return context; +}); + +Application.Run(); +``` + +## Parameters + + + + The path matcher to use for the route. Matchers accept path parameters in + the form of a colon prefixed string. The string provided will be used as + that path parameter's name when calling middleware and handlers. See [create + a route with path params](#create-a-route-with-path-params) + + + One or more middleware functions to use as the handler for HTTP requests. + Handlers can be sync or async. + + + +## Examples + +### Register a handler for POST requests + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.Post(context => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + context.Res.Json(responseBody); + + return context; +}); + +Application.Run(); +``` + +### Chain functions as a single method handler + +When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. + +```csharp +using Application = Nitric.Sdk.Application; + +var route = Application.Api("main").Route("/customers/:userId"); + +route.Post((context, next) => { + var user = context.Req.PathParams["userId"]; + + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; + + // Return prematurely to end the middleware chain. + return context; + } + + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; + + context.Res.Text($"Creating {user}"); + + return next(context); + } +); + +Application.Run(); +``` + +### Access the request body + +The POST request body is accessible from the `ctx.req` object. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.Post(context => { + var body = context.Req.Json>(); + // parse, validate and store the request payload... +}); + +Application.Run(); +``` diff --git a/docs/reference/csharp/api/api-route-put.mdx b/docs/reference/csharp/api/api-route-put.mdx new file mode 100644 index 000000000..1b5498404 --- /dev/null +++ b/docs/reference/csharp/api/api-route-put.mdx @@ -0,0 +1,115 @@ +--- +description: "Reference for Nitric's .NET library - Register a handler for HTTP PUT requests to the route." +--- + +# .NET - Api.Route.Put() + +Register a handler for HTTP PUT requests to the route. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.Put(context => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + context.Res.Json(responseBody); + + return context; +}); + +Application.Run(); +``` + +## Parameters + + + + The path matcher to use for the route. Matchers accept path parameters in + the form of a colon prefixed string. The string provided will be used as + that path parameter's name when calling middleware and handlers. See [create + a route with path params](#create-a-route-with-path-params) + + + One or more middleware functions to use as the handler for HTTP requests. + Handlers can be sync or async. + + + +## Examples + +### Register a handler for PUT requests + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.Put(context => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + context.Res.Json(responseBody); + + return context; +}); + +Application.Run(); +``` + +### Chain functions as a single method handler + +When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers/:userId"); + +route.Put((context, next) => { + var user = context.Req.PathParams["userId"]; + + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; + + // Return prematurely to end the middleware chain. + return context; + } + + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; + + context.Res.Text($"Updating {user}"); + + return next(context); + } +); + +Application.Run(); +``` + +### Access the request body + +The PUT request body is accessible from the `ctx.req` object. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +route.Put(context => { + var body = context.Req.Json>(); + // parse, validate and store the request payload... +}); + +Application.Run(); +``` diff --git a/docs/reference/csharp/api/api-route.mdx b/docs/reference/csharp/api/api-route.mdx new file mode 100644 index 000000000..987cac523 --- /dev/null +++ b/docs/reference/csharp/api/api-route.mdx @@ -0,0 +1,91 @@ +--- +description: "Reference for Nitric's .NET library - Creates a new route (path) within an API." +--- + +# .NET - Api.Route() + +Creates a new route (path) within an API. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +Application.Run(); +``` + +## Parameters + + + + The path matcher to use for this route. Calling `route` on the same API more + than once with the same matcher will return the same route object. Matchers + accept path parameters in the form of a colon prefixed string. The string + provided will be used as that path parameter's name when calling middleware + and handlers. See [create a route with path + params](#create-a-route-with-path-params) + + + Additional options when creating the route. + + + Middleware to apply to all methods on this route. + + + + + +## Notes + +The `middleware` property on the `options` param is useful for applying universal middleware such as CORS headers or Auth, across an entire route. However, if methods aren't registered, the route won't be deployed. If you need to run the same handler for all methods on a route, you should use [route.all()](./api-route-all) + +## Examples + +### Create a route + +```csharp +using Application = Nitric.Sdk.Nitric; + +var route = Application.Api("main").Route("/customers"); + +Application.Run(); +``` + +### Create a route with path params + +Route paths can include dynamic parameters. These values will automatically be parsed and provided in the context object for your middleware and handlers as a `string`. + +For example, if you have a customers path and you want to include a `customerId` param you would define the route like this. + +```csharp +using Application = Nitric.Sdk.Application; + +var route = Application.Api("main").Route("/customers/:customerId"); + +Application.Run(); +``` + +### Create a route with middleware + +```csharp +using Application = Nitric.Sdk.Application; + +var route = Application.Api("main").Route("/customers", (context, next) => { + var user = context.Req.PathParams["userId"]; + + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; + + // Return prematurely to end the middleware chain. + return context; + } + + // Call next to continue the middleware chain. + return next(context); +}); + +Application.Run(); +``` diff --git a/docs/reference/csharp/api/api.mdx b/docs/reference/csharp/api/api.mdx new file mode 100644 index 000000000..82369eb3e --- /dev/null +++ b/docs/reference/csharp/api/api.mdx @@ -0,0 +1,126 @@ +--- +description: "Reference for Nitric's .NET library - Create APIs with the Nitric C# SDK" +--- + +# .NET - Api() + +Creates a new HTTP API. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +Application.Run(); +``` + +## Parameters + + + + The unique name of this API within the app. Subsequent calls to `api` with + the same name will return the same object. + + + Security definitions defined by this API. + + + Security rules to apply with scopes to the entire API. Keys must match a + `securityDefinition`. + + + A `SecurityDefinition` object is one of the following: + + + The issuer for the JWT tokens e.g. `https://account.region.auth0.com`. + + + The `aud` that will be applied to JWT tokens from the issuer. + + + + + +## Notes + +The `middleware` property on the `options` param is useful for applying universal middleware such as CORS headers or Auth, across an entire API from a single place. + +## Examples + +### Create an API + +```csharp +using Application = Nitric.Sdk.Nitric; + +var api = Application.Api("main"); + +Application.Run(); +``` + +### Create an API with universal middleware + +```csharp +using Application = Nitric.Sdk.Application; + +private HttpContext ValidateRequest(HttpContext ctx, Func next) +{ + // Validation logic + return next(ctx); +} + +var api = Application.Api("main", new ApiOptions( + Middleware: new Middleware[] { ValidateRequest } +)); + +Application.Run(); +``` + +### Create an API with a base path + +If you need to put all the routes in your api below a shared base path, you can do that with the `BaseRoute` option. In this example we ensure all routes start with `/api/v1/` before the route specific path. + +```csharp +using Application = Nitric.Sdk.Application; + +var api = Application.Api("main", new ApiOptions( + BaseRoute: "/api/v1" +)); + +Application.Run(); +``` + +### Apply JWT authentication to an API + +```csharp +using Application = Nitric.Sdk.Nitric; + +var secureApi = Application.Api("main", new ApiOptions( + // You can optionally apply security rules to the entire API + Security: new Dictionary + { + // apply the 'user security definition the whole API' + { + "user", + // Optionally apply required scopes to this api + // in this case users will require the products:read scope to access the API + new string[] { "products:read" } + }, + }, + // security requirements for your API are defined here + SecurityDefinitions: new Dictionary + { + // define a security definition called 'user' + { "user", + new JwtSecurityDefinition( + 'https://example-issuer.com', + new string[] { "YOUR_AUDIENCES" } + ) + } + } +)); + +Application.Run(); +``` diff --git a/docs/reference/csharp/batch/job-handler.mdx b/docs/reference/csharp/batch/job-handler.mdx new file mode 100644 index 000000000..8e8867768 --- /dev/null +++ b/docs/reference/csharp/batch/job-handler.mdx @@ -0,0 +1,89 @@ +--- +description: "Reference for Nitric's .NET library - Register a job handler" +--- + +# .NET - Job.Handler() + +Job handlers are the code that is run when a job request is submitted. These handlers should be written in a separate file to your services. + +```csharp +using Nitric.Sdk.Resource; +using System.Collections.Generic; +using Application = Nitric.Sdk.Nitric; + +var analyze = Application.Job>("analyze"); + +analyze.Handler((ctx) => +{ + // Do some work + return ctx; +}, new JobResourceRequirements(cpus: 1, memory: 1024, gpus: 1)); + +Application.Run(); +``` + +## Defining Batches + +Batches are defined in different files to services and referenced in a project's `nitric.yaml` file. For example: + +```yaml +batch-services: + - match: ./batch/**/*.csproj + start: dotnet run --project $SERVICE_PATH +``` + +## Parameters + + + + One or more middleware services to use as the handler which will run on the + defined frequency. + + + + The number of CPUs to allocate to the handler + + + The number of GPUs to allocate to the handler + + + The amount of memory (MB) to allocate to the handler + + + + +## Examples + +### Define a job handler with default resource requirements + +```csharp +using System.Collections.Generic; +using Application = Nitric.Sdk.Nitric; + +var analyze = Application.Job>('analyze'); + +analyze.Handler((ctx) => { + // Do some work + return ctx +}); + +Application.Run(); +``` + +### Create a job handler with custom resource requirements + +```csharp +using Nitric.Sdk.Resource; +using System.Collections.Generic; +using Application = Nitric.Sdk.Nitric; + +var analyze = Application.Job>("analyze"); + +analyze.Handler((ctx) => +{ + // Do some work + return ctx; +}, new JobResourceRequirements(cpus: 1, memory: 1024, gpus: 1)); + +Application.Run(); +``` diff --git a/docs/reference/csharp/batch/job-submit.mdx b/docs/reference/csharp/batch/job-submit.mdx new file mode 100644 index 000000000..3109e2c9a --- /dev/null +++ b/docs/reference/csharp/batch/job-submit.mdx @@ -0,0 +1,43 @@ +--- +description: "Reference for Nitric's .NET library - Submit a batch job request with custom resource requirements" +--- + +# .NET - Job.Submit() + +Jobs may be submitted from Nitric `services` or other `batches` using the `Submit` method on the job reference. When submitting a job you can provide a payload that will be passed to the job handler function. + +```csharp +using Nitric.Sdk.Resource; +using System.Collections.Generic; +using Application = Nitric.Sdk.Nitric; + +var analyze = Application.Job>("analyze").Allow(JobPermission.Submit); + +analyze.Submit(new Dictionary() { { "message", "message contents" } }); + +Application.Run(); +``` + +## Parameters + + + + The data that will be sent to the submit + + + +## Examples + +### Submit a job request + +```csharp +using Nitric.Sdk.Resource; +using System.Collections.Generic; +using Application = Nitric.Sdk.Nitric; + +var analyze = Application.Job>("analyze").Allow(JobPermission.Submit); + +analyze.Submit(new Dictionary() { { "message", "message contents" } }); + +Application.Run(); +``` diff --git a/docs/reference/csharp/batch/job.mdx b/docs/reference/csharp/batch/job.mdx new file mode 100644 index 000000000..18b9da835 --- /dev/null +++ b/docs/reference/csharp/batch/job.mdx @@ -0,0 +1,50 @@ +--- +description: "Reference for Nitric's .NET library - Create Batch Jobs" +--- + +# .NET - Job() + +Creates a new Batch Job. + +```csharp +using System.Collections.Generic; +using Application = Nitric.Sdk.Nitric; + +var analyze = Application.Job>("analyze"); + +Application.Run(); +``` + +## Parameters + + + + The unique name of this Batch Job within the app. Subsequent calls to `Job` + with the same name will return the same object. + + + +## Examples + +### Create a Job + +```csharp +using System.Collections.Generic; +using Application = Nitric.Sdk.Nitric; + +var analyze = Application.Job>("analyze"); + +Application.Run(); +``` + +### Create a Job with permissions to submit jobs + +```csharp +using Nitric.Sdk.Resource; +using System.Collections.Generic; +using Application = Nitric.Sdk.Nitric; + +var analyze = Application.Job>("analyze").Allow(JobPermission.Submit); + +Application.Run(); +``` diff --git a/docs/reference/csharp/index.mdx b/docs/reference/csharp/index.mdx new file mode 100644 index 000000000..ecf8c69e7 --- /dev/null +++ b/docs/reference/csharp/index.mdx @@ -0,0 +1,33 @@ +--- +description: "Reference for Nitric's .NET library - Using Nitric with .NET" +--- + +# Nitric\'s .NET SDK + +This SDK reference provides documentation for the functions and methods in Nitric\'s .NET library. + +The library provides the ability to define and interact with cloud resources, as well as build application logic like functions/handlers. + +## Installation + +If you used a Nitric starter template for .NET to scaffold your project, then the `Nitric.Sdk` package will already be included in the dependencies in your `.csproj` file. Using starter templates is the recommended installation option since it ensures the other files and configuration needed are also set up. + +However, you can also install the SDK. + +```bash +dotnet add package Nitric.Sdk +``` + +## Custom runtime + +To successfully run and deploy .NET applications using the Nitric framework, it is necessary to use a custom runtime Dockerfile. This Dockerfile ensures that your .NET application is built and executed within an appropriate environment, taking into account all dependencies and configurations required by Nitric. + +### Default Dockerfile + +For your convenience, Nitric provides a default Dockerfile specifically tailored for .NET applications. This default Dockerfile is included with the [.NET starter template](https://github.com/nitrictech/examples/tree/main/v1/csharp-starter) available through the Nitric CLI. By using this template, you can quickly set up your development environment and focus on building your application without worrying about Docker configuration. + +This Dockerfile provides a solid starting point for deploying .NET applications with Nitric. Feel free to customize it according to your application's needs. + +## Source + +The source for the SDK is available on [GitHub](https://github.com/nitrictech/dotnet-sdk). diff --git a/docs/reference/csharp/keyvalue/keyvalue-delete.mdx b/docs/reference/csharp/keyvalue/keyvalue-delete.mdx new file mode 100644 index 000000000..d82ef3a96 --- /dev/null +++ b/docs/reference/csharp/keyvalue/keyvalue-delete.mdx @@ -0,0 +1,53 @@ +--- +description: "Reference for Nitric's .NET library - Delete key from a key value store." +--- + +# .NET - Kv.Delete() + +Delete key from a key value store. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class Profile +{ + public string Name; + public int Age; +} + +var profiles = Application.KV("profiles").Allow(KeyValueStorePermission.Delete); + +profiles.Delete("profile-1a2b3c"); + +Application.Run(); +``` + +## Parameters + + + + The key that references the key value pair that should be deleted. + + + +## Examples + +### Delete a key + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class Profile +{ + public string Name; + public int Age; +} + +var profiles = Application.KV("profiles").Allow(KeyValueStorePermission.Delete); + +profiles.Delete("profile-1a2b3c"); + +Application.Run(); +``` diff --git a/docs/reference/csharp/keyvalue/keyvalue-get.mdx b/docs/reference/csharp/keyvalue/keyvalue-get.mdx new file mode 100644 index 000000000..b89f365df --- /dev/null +++ b/docs/reference/csharp/keyvalue/keyvalue-get.mdx @@ -0,0 +1,53 @@ +--- +description: "Reference for Nitric's .NET library - Get a value from a key value store." +--- + +# .NET - Kv.Get() + +Get a value from a key value store. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class Profile +{ + public string Name; + public int Age; +} + +var profiles = Application.KV("profiles").Allow(KeyValueStorePermission.Get); + +var profile = profiles.Get("profile-1a2b3c"); + +Application.Run(); +``` + +## Parameters + + + + The key that references the key value pair that should be retrieved. + + + +## Examples + +### Get a key value pair + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class Profile +{ + public string Name; + public int Age; +} + +var profiles = Application.KV("profiles").Allow(KeyValueStorePermission.Get); + +var profile = profiles.Get("profile-1a2b3c"); + +Application.Run(); +``` diff --git a/docs/reference/csharp/keyvalue/keyvalue-keys.mdx b/docs/reference/csharp/keyvalue/keyvalue-keys.mdx new file mode 100644 index 000000000..7c1261c81 --- /dev/null +++ b/docs/reference/csharp/keyvalue/keyvalue-keys.mdx @@ -0,0 +1,90 @@ +--- +description: "Reference for Nitric's .NET library - Retrieve all or some of the keys from a value store." +--- + +# .NET - Kv.Keys() + +Return an async iterable of keys in the store. + +```csharp +using System; +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class Profile +{ + public string Name; + public int Age; +} + +var profiles = Application.KV("profiles").Allow(KeyValueStorePermission.Set, KeyValueStorePermission.Get, KeyValueStorePermission.Delete); + +var keys = profiles.Keys(); + +while (await keys.MoveNext()) +{ + Console.WriteLine(keys.Current); +} + +Application.Run(); +``` + +## Parameters + + + + The prefix to filter keys by, if not provided all keys will be returned. + + + +## Examples + +### Get all keys from a key value store + +```csharp +using System; +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class Profile +{ + public string Name; + public int Age; +} + +var profiles = Application.KV("profiles").Allow(KeyValueStorePermission.Set, KeyValueStorePermission.Get, KeyValueStorePermission.Delete); + +var keys = profiles.Keys(); + +while (await keys.MoveNext()) +{ + Console.WriteLine(keys.Current); +} + +Application.Run(); +``` + +### Get keys filtered by prefix from a key value store + +```csharp +using System; +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class Profile +{ + public string Name; + public int Age; +} + +var profiles = Application.KV("profiles").Allow(KeyValueStorePermission.Set, KeyValueStorePermission.Get, KeyValueStorePermission.Delete); + +var keys = profiles.Keys("profile-"); + +while (await keys.MoveNext()) +{ + Console.WriteLine(keys.Current); +} + +Application.Run(); +``` diff --git a/docs/reference/csharp/keyvalue/keyvalue-set.mdx b/docs/reference/csharp/keyvalue/keyvalue-set.mdx new file mode 100644 index 000000000..cac24b20e --- /dev/null +++ b/docs/reference/csharp/keyvalue/keyvalue-set.mdx @@ -0,0 +1,56 @@ +--- +description: "Reference for Nitric's .NET library - Store a key value pair in a key value store." +--- + +# .NET - Kv.Set() + +Store a key value pair in a key value store. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class Profile +{ + public string Name { get; set; } + public int Age { get; set; } +} + +var profiles = Application.KV("profiles").Allow(KeyValueStorePermission.Set); + +profiles.Set("profile-1a2b3c", new Profile() { Name = "John Smith", Age = 21 }); + +Application.Run(); +``` + +## Parameters + + + + The key that references value. + + + A json serializable object that is stored as the value. + + + +## Examples + +### Set a key value pair + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class Profile +{ + public string Name { get; set; } + public int Age { get; set; } +} + +var profiles = Application.KV("profiles").Allow(KeyValueStorePermission.Set); + +profiles.Set("profile-1a2b3c", new Profile() { Name = "John Smith", Age = 21 }); + +Application.Run(); +``` diff --git a/docs/reference/csharp/keyvalue/keyvalue.mdx b/docs/reference/csharp/keyvalue/keyvalue.mdx new file mode 100644 index 000000000..1b329b024 --- /dev/null +++ b/docs/reference/csharp/keyvalue/keyvalue.mdx @@ -0,0 +1,158 @@ +--- +description: "Reference for Nitric's .NET library - Creates a new key value store to get, set, and delete key value pairs." +--- + +# .NET - KV() + +Creates a new key value store to get, set, and delete key value pairs. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class Profile +{ + public string Name; + public int Age; +} + +var profiles = Application.KV("profiles").Allow(KeyValueStorePermission.Set, KeyValueStorePermission.Get, KeyValueStorePermission.Delete); + +Application.Run(); +``` + +## Parameters + + + + The unique name of this key value store within the service. Subsequent calls + to `kv` with the same name will return the same object. + + + +## Access + +All Nitric resources provide access permissions you can use to specify the level of access your service needs to the resource. See here for details about infrastructure [security](/get-started/foundations/infrastructure/security). + +### Available permissions: + +--- + +**KeyValueStorePermission.Get** + +This permission allows your service to get values from the key value store. + +--- + +**KeyValueStorePermission.Set** + +This permission allows your service to set key value pairs in the key value store. + +--- + +**KeyValueStorePermission.Delete** + +This permission allows your service to delete key value pairs in the key value store. + +--- + +## Examples + +### Create a key value store + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class Profile +{ + public string Name; + public int Age; +} + +var profiles = Application.KV("profiles").Allow(KeyValueStorePermission.Set, KeyValueStorePermission.Get, KeyValueStorePermission.Delete); + +Application.Run(); +``` + +### Get value from a key value store + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class Profile +{ + public string Name; + public int Age; +} + +var profiles = Application.KV("profiles").Allow(KeyValueStorePermission.Get); + +var profile = profiles.Get("profile-1a2b3c"); + +Application.Run(); +``` + +### Set a key in a key value store + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class Profile +{ + public string Name { get; set; } + public int Age { get; set; } +} + +var profiles = Application.KV("profiles").Allow(KeyValueStorePermission.Set); + +profiles.Set("profile-1a2b3c", new Profile() { Name = "John Smith", Age = 21 }); + +Application.Run(); +``` + +### Delete a key from a key value store + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class Profile +{ + public string Name; + public int Age; +} + +var profiles = Application.KV("profiles").Allow(KeyValueStorePermission.Delete); + +profiles.Delete("profile-1a2b3c"); + +Application.Run(); +``` + +### Get all keys from a key value store + +```csharp +using System; +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class Profile +{ + public string Name; + public int Age; +} + +var profiles = Application.KV("profiles").Allow(KeyValueStorePermission.Set, KeyValueStorePermission.Get, KeyValueStorePermission.Delete); + +var keys = profiles.Keys(); + +while (await keys.MoveNext()) +{ + Console.WriteLine(keys.Current); +} + +Application.Run(); +``` diff --git a/docs/reference/csharp/queues/queue-dequeue.mdx b/docs/reference/csharp/queues/queue-dequeue.mdx new file mode 100644 index 000000000..a6a4c87bd --- /dev/null +++ b/docs/reference/csharp/queues/queue-dequeue.mdx @@ -0,0 +1,96 @@ +--- +description: "Reference for Nitric's .NET library - Receive tasks from a queue." +--- + +# .NET - Queue.Receive() + +Receive tasks from a queue. + +```csharp +using System; +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class UserRequest +{ + public string UserId { get; set; } + public string Message { get; set; } +} + +var batchQueue = Application.Queue("batch").Allow(QueuePermission.Dequeue); + +var tasks = batchQueue.Dequeue(); + +tasks.ForEach(task => { + // Work on a task... + Console.WriteLine($"Request from user {task.Payload.UserId}: {task.Payload.Message}"); + + // Complete the task + task.Complete(); +}); + +Application.Run(); +``` + +## Parameters + + + + The maximum number of tasks to receive from the queue. Defaults to 1. + + + +## Notes + +### Completing tasks + +Since the process is async, the queue doesn't know when a task has been completed. So failed function/containers don't result in lost tasks, tasks are not removed from a queue when they're received. + +Instead, tasks are hidden and receivers are granted a temporary lease for each task they receive. + +When complete, the receiver must tell the queue the task was completed successfully, which will remove it from the queue and stop it being reprocessed. + + + Failing to complete a task before the lease expires will result in it being + re-queued. + + +To notify the queue that a task was completed call the `Complete()` method on the task reference. + +### Receive depth + +When calling `Receive()` a depth parameter can be provided, e.g. `Receive(5)`. This will _attempt_ to receive up to 5 tasks from the queue. + +However, if the queue is empty or less than 5 tasks are available on the queue, then the max available will be returned. + +This means calls to receive will return between 0 and _depth_ tasks. + +## Examples + +### Receive tasks from a queue + +```csharp +using System; +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class UserRequest +{ + public string UserId { get; set; } + public string Message { get; set; } +} + +var batchQueue = Application.Queue("batch").Allow(QueuePermission.Dequeue); + +var tasks = batchQueue.Dequeue(); + +tasks.ForEach(task => { + // Work on a task... + Console.WriteLine($"Request from user {task.Payload.UserId}: {task.Payload.Message}"); + + // Complete the task + task.Complete(); +}); + +Application.Run(); +``` diff --git a/docs/reference/csharp/queues/queue-enqueue.mdx b/docs/reference/csharp/queues/queue-enqueue.mdx new file mode 100644 index 000000000..1c4d6e072 --- /dev/null +++ b/docs/reference/csharp/queues/queue-enqueue.mdx @@ -0,0 +1,99 @@ +--- +description: "Reference for Nitric's v0 .NET library - Send tasks to a queue." +--- + +# .NET - Queue.Send() + +Send tasks to a queue. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class UserRequest +{ + public string UserId { get; set; } + public string Message { get; set; } +} + +var batchQueue = Application.Queue("batch").Allow(QueuePermission.Enqueue); + +batchQueue.Enqueue(new UserRequest +{ + UserId = "1234", + Message = "Hello!" +}); + +Application.Run(); +``` + +## Parameters + + + + The task or an array of tasks to send to the queue. + + + +## Examples + +### Enqueue a task onto a queue + +```csharp +using System.Collections.Generic; +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class UserRequest +{ + public string UserId { get; set; } + public string Message { get; set; } +} + +var batchQueue = Application.Queue("batch").Allow(QueuePermission.Enqueue); + +batchQueue.Enqueue(new UserRequest +{ + UserId = "user_1234", + Message = "Hello!" +}); + +Application.Run(); +``` + +### Enqueue multiple tasks onto a queue + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var batchQueue = Application.Queue("batch").Allow(QueuePermission.Enqueue); + +batchQueue.Enqueue( + new UserRequest + { + UserId = "user_1", + Message = "Batch Task 1" + }, new UserRequest + { + UserId = "user_2", + Message = "Batch Task 2" + } +); + +Application.Run(); +``` + +### Dealing with failures + +In rare cases when sending tasks to a queue some tasks might fail to be sent. The response from `send()` will include an array of any tasks that failed to send. You can process this array to retry or log the error. + +```csharp +var failedTasks = await batchQueue.Enqueue(tasks); + +failedTasks.ForEach(failedTask => { + Console.WriteLine(failedTask.ID); +}); + +Nitric.Run(); +``` diff --git a/docs/reference/csharp/queues/queue.mdx b/docs/reference/csharp/queues/queue.mdx new file mode 100644 index 000000000..2d2471bb4 --- /dev/null +++ b/docs/reference/csharp/queues/queue.mdx @@ -0,0 +1,98 @@ +--- +description: "Reference for Nitric's .NET library - Creates a new Queue to send and receive asynchronous tasks." +--- + +# .NET - Queue() + +Creates a new Queue to send and receive asynchronous tasks. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class UserRequest +{ + public string UserId { get; set; } + public string Message { get; set; } +} + +var batchQueue = Application.Queue("batchQueue").Allow(QueuePermission.Enqueue); + +Application.Run(); +``` + +## Parameters + + + + The unique name of this Queue within the app. Subsequent calls to `queue` + with the same name will return the same object. + + + +## Access + +All Nitric resources provide access permissions you can use to specify the level of access your code needs to the resource. See here for details about infrastructure [security](/get-started/foundations/infrastructure/security). + +### Available permissions: + +--- + +**QueuePermission.Enqueue** + +This permission allows your code to enqueue new tasks to the queue. + +--- + +**QueuePermission.Dequeue** + +This permission allows your code to dequeue tasks from the queue. + +--- + +### Notes + +In most instances, code should either enqueue to or dequeue from a queue, usually not both. + +## Examples + +### Create a Queue + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class UserRequest +{ + public string UserId { get; set; } + public string Message { get; set; } +} + +var batchQueue = Application.Queue("batchQueue"); + +Application.Run(); +``` + +### Dequeue tasks from a queue + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class UserRequest +{ + public string UserId { get; set; } + public string Message { get; set; } +} + +var batchQueue = Application.Queue("batchQueue").With(QueuePermission.Dequeue); + +var tasks = batchQueue.Dequeue(); + +Application.Run(); +``` + +### See also + +- [Queue.Dequeue()](./queue-dequeue) +- [Queue.Enqueue()](./queue-enqueue) diff --git a/docs/reference/csharp/schedule/schedule-cron.mdx b/docs/reference/csharp/schedule/schedule-cron.mdx new file mode 100644 index 000000000..5a6c4c624 --- /dev/null +++ b/docs/reference/csharp/schedule/schedule-cron.mdx @@ -0,0 +1,54 @@ +--- +description: "Reference for Nitric's .NET library - Sets the cron expression and one or many handlers to be triggered." +--- + +# .NET - Schedule.Cron() + +Sets the cron expressions that determines when the schedule triggers and a callback to be triggered. + +```csharp +using Application = Nitric.Sdk.Nitric; + +Application.Schedule("send-reminder").Cron("0 1 1 * *", ctx => { + // do some processing +}); + +Application.Run(); +``` + +## Parameters + + + + The expression that sets when the schedule will be triggered. This value + should be a standard 5 value Unix cron expression, e.g., '0 1 1 * *'. + + + One or more callback functions to use as the handler which will run on the + defined frequency. + + + +## Examples + +### Create a Schedule + +```csharp +using Application = Nitric.Sdk.Nitric; + +// every 15 minutes +Application.Schedule("check for updates").Cron("0/15 * * * *", ctx => { + Console.WriteLine("checking for updates"); +}); + +// at 1:00 am on the 1st of every month +Application.Schedules("delete stale data").Cron("0 1 1 * *", ctx => { + Console.WriteLine("clearing stale data"); +}); + +Application.Run(); +``` diff --git a/docs/reference/csharp/schedule/schedule-every.mdx b/docs/reference/csharp/schedule/schedule-every.mdx new file mode 100644 index 000000000..a90637243 --- /dev/null +++ b/docs/reference/csharp/schedule/schedule-every.mdx @@ -0,0 +1,79 @@ +--- +description: "Reference for Nitric's .NET library - Sets the frequency and one or many handlers to be triggered." +--- + +# .NET - Schedule.Every() + +Sets the frequency and one or many handlers to be triggered. + +```csharp +using Application = Nitric.Sdk.Nitric; + +Application.Schedule("send-reminder").Every("3 hours", context => +{ + // do some processing + return context; +}); + +Application.Run(); +``` + +## Parameters + + + + The rate to run the schedule, e.g. '7 days'. All rates accept a number and a + frequency. Valid frequencies are 'days', 'hours' or 'minutes'. + + + One or more middleware functions to use as the handler which will run on + defined frequency. + + + +## Examples + +### Create a Schedule to run every 3 minutes + +```csharp +using Application = Nitric.Sdk.Nitric; + +Application.Schedule("send-reminder").Every("3 minutes", context => +{ + // do some processing + return context; +}); + +Application.Run(); +``` + +### Create a Schedule with multiple middleware/handlers + +```csharp +using System; +using Nitric.Sdk.Service; +using Application = Nitric.Sdk.Nitric; + +// Create a middleware to handle report generation +private IntervalContext GenerateReport(IntervalContext ctx, Func next) +{ + // Code to generate a report + return next(ctx); +} + +// Create a middleware to handle notifications +private IntervalContext SendNotification(IntervalContext ctx, Func next) +{ + // Code to send a notification + return next(ctx); +} + +// Create a schedule that runs every 7 days +Application.Schedule("send-reminder").Every("7 days", GenerateReport, SendNotification); + +Application.Run(); +``` diff --git a/docs/reference/csharp/schedule/schedule.mdx b/docs/reference/csharp/schedule/schedule.mdx new file mode 100644 index 000000000..d86fe4ba7 --- /dev/null +++ b/docs/reference/csharp/schedule/schedule.mdx @@ -0,0 +1,74 @@ +--- +description: "Reference for Nitric's .NET library - Creates a new Schedule to run a function on a defined frequency." +--- + +# .NET - Schedule() + +Creates a new Schedule to run a function on a defined frequency. + +```csharp +using Application = Nitric.Sdk.Nitric; + +Application.Schedule("send-reminder").Every("3 hours", context => +{ + // do some processing + return context; +}); + +Application.Run(); +``` + +## Parameters + + + + The unique name of this Schedule within the app. Subsequent calls to + `Schedule` with the same name will return the same object. + + + +## Examples + +### Create a Schedule + +```csharp +using Application = Nitric.Sdk.Nitric; + +// Create a schedule that runs every 3 minutes +Application.Schedule("send-reminder").Every("3 minutes", context => +{ + // do some processing + return context; +}); + +// Create a schedule that runs every 3 hours +Application.Schedule("send-reminder").Every("3 hours", context => +{ + // do some processing + return context; +}); + +// Create a schedule that runs every 3 days +Application.Schedule("send-reminder").Every("3 days", context => +{ + // do some processing + return context; +}); + +Application.Run(); +``` + +### Create a Schedule using Cron expression + +```csharp +using Application = Nitric.Sdk.Nitric; + +// Create a schedule that runs every 3 minutes +Application.Schedule("send-reminder").Cron("3 * * * *", context => +{ + // do some processing + return context; +}); + +Application.Run(); +``` diff --git a/docs/reference/csharp/secrets/secret-latest.mdx b/docs/reference/csharp/secrets/secret-latest.mdx new file mode 100644 index 000000000..f445a6c91 --- /dev/null +++ b/docs/reference/csharp/secrets/secret-latest.mdx @@ -0,0 +1,56 @@ +--- +description: "Reference for Nitric's .NET library - Returns a reference to the latest version of a secret, regardless of that version's ID." +--- + +# .NET - Secret.Latest() + +Returns a reference to the `latest` version of a secret, regardless of that version's ID. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); + +var latestVersion = keyRef.Latest(); + +Application.Run(); +``` + +## Notes + +`Latest()` is most useful when you always want the most recent secret values from the secrets manager. Database credentials and API keys are good examples of secrets where the latest value is usually what you want. + +For symmetric encryption, you'll need to retrieve the version of the secret used to _encrypt_ a value when you try to _decrypt_ it again. In those cases `Latest()` isn't a good choice, use [version()](./secret-version) instead. + +## Examples + +### Get a reference to the latest secret version + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); + +var latestVersion = keyRef.Latest(); + +Application.Run(); +``` + +### Access the latest value of a secret + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); + +var latestVersion = keyRef.Latest().Access(); + +Application.Run(); +``` + + + See [Secret.Version().Access()](./secret-version-access) for more details. + diff --git a/docs/reference/csharp/secrets/secret-put.mdx b/docs/reference/csharp/secrets/secret-put.mdx new file mode 100644 index 000000000..89ee8b7d2 --- /dev/null +++ b/docs/reference/csharp/secrets/secret-put.mdx @@ -0,0 +1,62 @@ +--- +description: "Reference for Nitric's .NET library - Store a new secret value" +--- + +# .NET - Secret.Put() + +Store a new secret value, creating a new [version](./secret-version) to store the value. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Put); + +keyRef.Put("6c3199a3-094e-4797-bfc9-9ee2a7839286"); + +Application.Run(); +``` + +## Parameters + + + + The new secret value to store in the secrets manager. + + + +### Notes + +A new secret version is always created when calling `Put()`, the versions will automatically be provided a unique id. This behavior is dependent on the underlying secrets manager. + +## Examples + +### Store a new secret value + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Put); + +keyRef.Put("6c3199a3-094e-4797-bfc9-9ee2a7839286"); + +Application.Run(); +``` + +### Get the id of a new secret version + +Calling `Put()` returns a promise to a reference to the new secret version. Storing the ID of the new version can be useful if you need to retrieve that specific value again in future using [Version.Access()](./secret-version-access) + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Put); + +var newApiKeyVersionRef = keyRef.Put("6c3199a3-094e-4797-bfc9-9ee2a7839286"); + +var versionId = newApiKeyVersionRef.Id; + +Application.Run(); +``` diff --git a/docs/reference/csharp/secrets/secret-version-access.mdx b/docs/reference/csharp/secrets/secret-version-access.mdx new file mode 100644 index 000000000..66860114c --- /dev/null +++ b/docs/reference/csharp/secrets/secret-version-access.mdx @@ -0,0 +1,52 @@ +--- +description: "Reference for Nitric's .NET library - Retrieves the value from a version of a secret." +--- + +# .NET - Secret.Version.Access() + +Retrieves the value from a version of a secret. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); + +var keyValue = keyRef.Latest().Access(); + +keyValue.ValueText; + +Application.Run(); +``` + +## Examples + +### Access the latest version of a secret + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); + +var keyValue = keyRef.Latest().Access(); + +keyValue.ValueText; + +Application.Run(); +``` + +### Access a specific version of a secret + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); + +var keyValue = keyRef.Version("the-version-id").Access(); + +keyValue.ValueText; + +Application.Run(); +``` diff --git a/docs/reference/csharp/secrets/secret-version.mdx b/docs/reference/csharp/secrets/secret-version.mdx new file mode 100644 index 000000000..b138570ef --- /dev/null +++ b/docs/reference/csharp/secrets/secret-version.mdx @@ -0,0 +1,60 @@ +--- +description: "Reference for Nitric's .NET library - Returns a reference to a known version of a secret." +--- + +# .NET - Secret.Version() + +Returns a reference to a known version of a secret. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var keyRef = Application.Secret("encryptionKey").With(SecretPermission.Accessing); + +var keyVersionRef = keyRef.Version("the-version-id"); + +Application.Run(); +``` + +## Parameters + + + + The version ID. This value is returned from [secret.Put()](./secret-put). + + + +## Examples + +### Return a reference to a known secret version + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var keyRef = Application.Secret("encryptionKey").With(SecretPermission.Accessing); + +var keyVersionRef = keyRef.Version("the-version-id"); + +Application.Run(); +``` + +### Access the value of a known secret version + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var keyRef = Application.Secret("encryptionKey").With(SecretPermission.Accessing); + +var keyVersionRef = keyRef.Version("the-version-id").Access(); + +var keyValue = keyVersionRef.ValueText; + +Application.Run(); +``` + +### See also + +- [Secret.Version.Access()](./secret-version-access) diff --git a/docs/reference/csharp/secrets/secret.mdx b/docs/reference/csharp/secrets/secret.mdx new file mode 100644 index 000000000..a14b0c68a --- /dev/null +++ b/docs/reference/csharp/secrets/secret.mdx @@ -0,0 +1,64 @@ +--- +description: "Reference for Nitric's .NET library - Creates a reference to a secret in the secrets manager." +--- + +# .NET - Secret() + +Creates a reference to a secret in the secrets manager. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); + +Application.Run(); +``` + +## Parameters + + + + The unique name of this secret within the secrets manager. + + + +## Access + +All Nitric resources provide access permissions you can use to specify the level of access your code needs to the resource. See here for details about infrastructure [security](/get-started/foundations/infrastructure/security). + +### Available permissions: + +--- + +**SecretPermission.Put** + +This permission allows your code to set a new latest value for a secret. + +--- + +**SecretPermission.Access** + +This permission allows your code to retrieve secret values. + +--- + +## Examples + +### Create a reference to a secret + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); + +Application.Run(); +``` + +### See also + +- [Secret.Put()](./secret-put) +- [Secret.Version()](./secret-version) +- [Secret.Latest()](./secret-latest) +- [Secret.Version.Access()](./secret-version-access) diff --git a/docs/reference/csharp/sql/sql-connection-string.mdx b/docs/reference/csharp/sql/sql-connection-string.mdx new file mode 100644 index 000000000..83113cbec --- /dev/null +++ b/docs/reference/csharp/sql/sql-connection-string.mdx @@ -0,0 +1,31 @@ +--- +description: "Reference for Nitric's .NET library - Returns the connection string for a SQL database at runtime." +--- + +# .NET - Sql.ConnectionString() + +Returns the connection string for a SQL database at runtime. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var db = Application.Sql("my-database", "dockerfile://migrations.dockerfile"); + +var connStr = db.ConnectionString(); + +Application.Run(); +``` + +## Examples + +### Return a connection string + +```csharp +using Application = Nitric.Sdk.Nitric; + +var db = Application.Sql("my-database", "dockerfile://migrations.dockerfile"); + +var connStr = db.ConnectionString(); + +Application.Run(); +``` diff --git a/docs/reference/csharp/sql/sql.mdx b/docs/reference/csharp/sql/sql.mdx new file mode 100644 index 000000000..ef46ed376 --- /dev/null +++ b/docs/reference/csharp/sql/sql.mdx @@ -0,0 +1,63 @@ +--- +description: "Reference for Nitric's .NET library - Creates a reference to a SQL database." +--- + +# .NET - Sql() + +Creates a reference to a SQL database. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var db = Application.Sql("my-database"); + +Application.Run(); +``` + +## Parameters + + + + The unique name of this database within the project. + + + Points to the location of migration files, prefixed with `file://`, or a + migration dockerfile, prefixed with `dockerfile://`. + + + +## Examples + +### Create a reference to a database + +```csharp +using Application = Nitric.Sdk.Nitric; + +var db = Application.Sql("my-database"); + +Application.Run(); +``` + +### With a migrations directory + +```csharp +using Application = Nitric.Sdk.Nitric; + +var db = Application.Sql("my-database", "file://migrations/my-database"); + +Application.Run(); +``` + +### With a migrations dockerfile + +```csharp +using Application = Nitric.Sdk.Nitric; + +var db = Application.Sql("my-database", "dockerfile://migrations.dockerfile"); + +Application.Run(); +``` + +### See also + +- [Sql.ConnectionString()](./sql-connection-string) diff --git a/docs/reference/csharp/storage/bucket-file-delete.mdx b/docs/reference/csharp/storage/bucket-file-delete.mdx new file mode 100644 index 000000000..cfac77c3f --- /dev/null +++ b/docs/reference/csharp/storage/bucket-file-delete.mdx @@ -0,0 +1,37 @@ +--- +description: "Reference for Nitric's .NET library - Delete a file from a bucket." +--- + +# .NET - Bucket.File.Delete() + +Delete a file from a bucket. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var assets = Application.Bucket('assets').Allow(BucketPermission.Delete); + +var logo = assets.File('images/logo.png'); + +logo.Delete(); + +Application.Run(); +``` + +## Examples + +### Delete a file + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var assets = Application.Bucket('assets').Allow(BucketPermission.Delete); + +var logo = assets.File('images/logo.png'); + +logo.Delete(); + +Application.Run(); +``` diff --git a/docs/reference/csharp/storage/bucket-file-downloadurl.mdx b/docs/reference/csharp/storage/bucket-file-downloadurl.mdx new file mode 100644 index 000000000..4ee8f94ea --- /dev/null +++ b/docs/reference/csharp/storage/bucket-file-downloadurl.mdx @@ -0,0 +1,69 @@ +--- +description: "Reference for Nitric's .NET library - Get a download url for a file from a bucket." +--- + +# .NET - Bucket.File.GetDownloadUrl() + +Create a download url for a file within a bucket. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var assets = Application.Bucket('assets').Allow(BucketPermission.Read); + +var logo = assets.File('images/logo.png'); + +// Create a read-only signed url reference for downloading +var downloadUrl = logo.GetDownloadUrl(); + +Application.Run(); +``` + +## Parameters + + + + Seconds until link expiry. Defaults to `600`, Maximum of `604800` (7 days). + + + +## Examples + +### Create a readable link that is valid for the next 5 minutes + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var assets = Application.Bucket('assets').Allow(BucketPermission.Read); + +var logo = assets.File('images/logo.png'); + +// Create a read-only signed url reference for downloading +var downloadUrl = logo.GetDownloadUrl(); + +Application.Run(); +``` + +### Redirect response to an image url + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var images = Application.Bucket('images').Allow(BucketPermission.Read); +var mainApi = Application.Api("main"); + +mainApi.Get("/images/:id", context => { + var id = context.Req.PathParams["id"]; + var signedUrl = images.File(id).GetDownloadUrl(); + + context.Res.Status = 303; + context.Res.Headers["Location"] = new string[] { signedUrl }; + + return context; +}); + +Application.Run(); +``` diff --git a/docs/reference/csharp/storage/bucket-file-read.mdx b/docs/reference/csharp/storage/bucket-file-read.mdx new file mode 100644 index 000000000..779549690 --- /dev/null +++ b/docs/reference/csharp/storage/bucket-file-read.mdx @@ -0,0 +1,37 @@ +--- +description: "Reference for Nitric's .NET library - Read the contents of a file from a bucket." +--- + +# .NET - Bucket.File.Read() + +Read the contents of a file from a bucket. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var assets = Application.Bucket('assets').Allow(BucketPermission.Read); + +var logo = assets.File('images/logo.png'); + +var logoData = logo.Read(); + +Application.Run(); +``` + +## Examples + +### Read a file + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var assets = Application.Bucket('assets').Allow(BucketPermission.Read); + +var logo = assets.File('images/logo.png'); + +var logoData = logo.Read(); + +Application.Run(); +``` diff --git a/docs/reference/csharp/storage/bucket-file-uploadurl.mdx b/docs/reference/csharp/storage/bucket-file-uploadurl.mdx new file mode 100644 index 000000000..b4bcd4897 --- /dev/null +++ b/docs/reference/csharp/storage/bucket-file-uploadurl.mdx @@ -0,0 +1,47 @@ +--- +description: "Reference for Nitric's .NET library - Get a upload url for a file from a bucket." +--- + +# .NET - Bucket.File.GeUploadUrl() + +Create a upload url for a file within a bucket. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var assets = Application.Bucket('assets').Allow(BucketPermission.Write); + +var logo = assets.File('images/logo.png'); + +// Create a read-only signed url reference for uploading +var uploadUrl = logo.GetUploadUrl(); + +Application.Run(); +``` + +## Parameters + + + + Seconds until link expiry. Defaults to `600`, Maximum of `604800` (7 days). + + + +## Examples + +### Create a temporary file upload link for a user + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var assets = Application.Bucket('assets').Allow(BucketPermission.Write); + +var logo = assets.File('images/logo.png'); + +// Create a read-only signed url reference for uploading +var uploadUrl = logo.GetUploadUrl(); + +Application.Run(); +``` diff --git a/docs/reference/csharp/storage/bucket-file-write.mdx b/docs/reference/csharp/storage/bucket-file-write.mdx new file mode 100644 index 000000000..bbd7c2409 --- /dev/null +++ b/docs/reference/csharp/storage/bucket-file-write.mdx @@ -0,0 +1,45 @@ +--- +description: "Reference for Nitric's .NET library - Write a file to a bucket." +--- + +# .NET - Bucket.File.Write() + +Write a file to a bucket. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var assets = Application.Bucket('assets').Allow(BucketPermission.Read); + +var logo = assets.File('images/logo.png'); + +logo.Write(someImageData); + +Application.Run(); +``` + +## Parameters + + + + The data to write to the file. + + + +## Examples + +### Write a file + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var assets = Application.Bucket('assets').Allow(BucketPermission.Read); + +var logo = assets.File('images/logo.png'); + +logo.Write(someImageData); + +Application.Run(); +``` diff --git a/docs/reference/csharp/storage/bucket-file.mdx b/docs/reference/csharp/storage/bucket-file.mdx new file mode 100644 index 000000000..dfa066513 --- /dev/null +++ b/docs/reference/csharp/storage/bucket-file.mdx @@ -0,0 +1,38 @@ +--- +description: "Reference for Nitric's .NET library - Create a reference to a file within a bucket." +--- + +# .NET - Bucket.File() + +Create a reference to a file within a bucket. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var assets = Application.Bucket("assets").Allow(BucketPermission.Read); + +var logo = assets.File("images/logo.png"); + +Application.Run(); +``` + +## Parameters + + + + The unique name/reference to the file. + + + +## Notes + +The file does not need to exist, only a reference to that file is being created. + +## Available Operations + +- [File.Read()](./bucket-file-read) +- [File.Write()](./bucket-file-write) +- [File.Delete()](./bucket-file-delete) +- [File.GetDownloadUrl()](./bucket-file-downloadurl) +- [File.GetUploadUrl()](./bucket-file-uploadurl) diff --git a/docs/reference/csharp/storage/bucket-files.mdx b/docs/reference/csharp/storage/bucket-files.mdx new file mode 100644 index 000000000..ae6e30991 --- /dev/null +++ b/docs/reference/csharp/storage/bucket-files.mdx @@ -0,0 +1,39 @@ +--- +description: "Reference for Nitric's .NET library - Get a list of file references for files that exist in the bucket." +--- + +# .NET - Bucket.Files() + +Get a list of file references for files that exist in the bucket. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var assets = Application.Bucket("assets").Allow(BucketPermission.Read); + +var files = assets.Files(); + +Application.Run(); +``` + +## Examples + +Deleting all files in a bucket + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var assets = Application.Bucket("assets").Allow(BucketPermission.Read); + +var files = assets.Files(); + +files.ForEach(file => file.Delete()); + +Application.Run(); +``` + +## Notes + +This method returns a list of [File](./bucket-file) references that exist on the bucket. diff --git a/docs/reference/csharp/storage/bucket-on.mdx b/docs/reference/csharp/storage/bucket-on.mdx new file mode 100644 index 000000000..7c160542e --- /dev/null +++ b/docs/reference/csharp/storage/bucket-on.mdx @@ -0,0 +1,87 @@ +--- +description: "Reference for Nitric's .NET library - Create a new bucket notification trigger" +--- + +# .NET - Bucket.On() + +Create a new bucket notification trigger when certain files are created or deleted. + +```csharp +using System; +using Nitric.Sdk.Resource; +using Nitric.Sdk.Service; +using Application = Nitric.Sdk.Nitric; + +var assets = Application.Bucket("assets"); + +var accessibleAssets = Application.Bucket("assets").Allow(BucketPermission.Read); + +// The request will contain the name of the file `Key` and the type of event `NotificationType` +assets.On(BlobEventType.Delete, "*", context => { + Console.WriteLine("A file named " + context.Req.Key + "was deleted"); + + return context; +}); + +assets.On(BlobEventType.Write, "/images/cat", context => { + Console.WriteLine("A cat image was written"); + + return context; +}); + +// If `.On()` is called with a permissioned bucket, a file reference will also be provided with the request +accessibleAssets.On(BlobEventType.Write, "/images/dog", context => { + var dogImage = accessibleAssets.File(context.Req.Key).Read(); + + Console.WriteLine(dogImage.ToString()); + + return context; +}); + +Application.Run(); +``` + +## Parameters + + + + The unique name/reference to the file. + + + The notification type for a triggered event, either on a file write or a + file delete. + + + The file prefix filter that must match for a triggered event. If multiple + filters overlap across notifications then an error will be thrown when + registering the resource. + + + The middleware (code) to be triggered when a bucket event is triggered. + + + +## Available Trigger Types + +`BlobEventType.Write` + +Triggered when a file in the bucket is created using: `file.Write()` + +`BlobEventType.Delete` + +Triggered when a file in the bucket is deleted using: `file.Delete()` + +## Cloud Trigger Types + +| Permission | AWS | GCP | Azure | +| ----------------------------- | ------------------- | --------------- | ----------------------------- | +| BucketNotificationType.Write | s3:ObjectCreated:\* | OBJECT_FINALIZE | Microsoft.Storage.BlobCreated | +| BucketNotificationType.Delete | s3:ObjectRemoved:\* | OBJECT_DELETE | Microsoft.Storage.BlobDeleted | diff --git a/docs/reference/csharp/storage/bucket.mdx b/docs/reference/csharp/storage/bucket.mdx new file mode 100644 index 000000000..55a881e83 --- /dev/null +++ b/docs/reference/csharp/storage/bucket.mdx @@ -0,0 +1,62 @@ +--- +description: "Reference for Nitric's .NET library - Create a new bucket for storing and retrieving files." +--- + +# .NET - Bucket() + +Create a new bucket for storing and retrieving files. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var assets = Application.Bucket("assets").Allow(BucketPermission.Read, BucketPermission.Write, BucketPermission.Delete); + +Nitric.Run(); +``` + +## Parameters + + + + The unique name of this bucket within the app. Subsequent calls to `Bucket` + with the same name will return the same object. + + + +## Access + +All Nitric resources provide access permissions you can use to specify the level of access your code needs to the resource. See here for details about infrastructure [security](/get-started/foundations/infrastructure/security). + +### Available permissions: + +--- + +**BucketPermission.Read** + +This permission allows your function to read files from the bucket + +--- + +**BucketPermission.Write** + +This permission allows your function to write files to the bucket + +--- + +**BucketPermission.Delete** + +This permission allows your function to delete files from the bucket + +--- + +## Working with files + +See the following for examples on working with files in a bucket: + +- [File()](./bucket-file) +- [File().Read()](./bucket-file-read) +- [File().Write()](./bucket-file-write) +- [File().Delete()](./bucket-file-delete) +- [File.GetDownloadUrl()](./bucket-file-downloadurl) +- [File.GetUploadUrl()](./bucket-file-uploadurl) diff --git a/docs/reference/csharp/topic/topic-publish.mdx b/docs/reference/csharp/topic/topic-publish.mdx new file mode 100644 index 000000000..dce7a7899 --- /dev/null +++ b/docs/reference/csharp/topic/topic-publish.mdx @@ -0,0 +1,55 @@ +--- +description: "Reference for Nitric's .NET library - Publish new events to the topic." +--- + +# .NET - Topic.Publish() + +Publish an event (push based message) to a topic. + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class EventUpdate +{ + public string Message { get; set; } +} + +var updates = Application.Topic("updates").Allow(TopicPermission.Publish); + +updates.Publish(new EventUpdate { Message = "payload sent" }); + +Application.Run(); +``` + +## Parameters + + + + The event to publish to the topic + + + +## Examples + +### Publish a topic + +```csharp +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class EventUpdate +{ + public string Message { get; set; } +} + +var updates = Application.Topic("updates").Allow(TopicPermission.Publish); + +updates.Publish(new EventUpdate { Message = "payload sent" }); + +Application.Run(); +``` + +## Notes + +- A function may subscribe to OR publish to a topic but not both. diff --git a/docs/reference/csharp/topic/topic-subscribe.mdx b/docs/reference/csharp/topic/topic-subscribe.mdx new file mode 100644 index 000000000..fd35bf470 --- /dev/null +++ b/docs/reference/csharp/topic/topic-subscribe.mdx @@ -0,0 +1,98 @@ +--- +description: "Reference for Nitric's .NET library - Subscribe a handler to a topic and receive new events for processing." +--- + +# .NET - Topic.Subscribe() + +Subscribe a handler to a topic and receive new events for processing. + +```csharp +using System; +using Application = Nitric.Sdk.Nitric; + +class EventUpdate +{ + public string Message { get; set; } +} + +var updates = Application.Topic("updates"); + +updates.Subscribe(ctx => { + Console.WriteLine(ctx.Req.Message); + + return ctx; +}); + +Application.Run(); +``` + +## Parameters + + + + The middleware (code) to be triggered by the topic. + + + +## Examples + +### Subscribe to a topic + +```csharp +using System; +using Application = Nitric.Sdk.Nitric; + +class EventUpdate +{ + public string Message { get; set; } +} + +var updates = Application.Topic("updates"); + +updates.Subscribe(ctx => { + Console.WriteLine(ctx.Req.Message); + + return ctx; +}); + +Application.Run(); +``` + +### Subscibe to a topic with chained middleware + +```csharp +using Application = Nitric.Sdk.Nitric; + +class EventUpdate +{ + public string Message { get; set; } +} + +var updates = Application.Topic("updates"); + + +updates.Subscribe((ctx, next) => + { + // Validate request + if (invalidRequest(ctx)) + { + return ctx; + } + return next(ctx); + }, (ctx, next) => { + // Handle request + return next(ctx); + } +); + +Application.Run(); +``` + +## Notes + +- A function may only subscribe to a topic once, if multiple subscribers are required, create them in different functions. +- A function may subscribe to OR publish to a topic but not both diff --git a/docs/reference/csharp/topic/topic.mdx b/docs/reference/csharp/topic/topic.mdx new file mode 100644 index 000000000..edfae7422 --- /dev/null +++ b/docs/reference/csharp/topic/topic.mdx @@ -0,0 +1,50 @@ +--- +description: "Reference for Nitric's .NET library - Creates a new Topic." +--- + +# .NET - Topic() + +Creates a new Topic. + +```csharp +using Application = Nitric.Sdk.Nitric; + +class EventUpdate +{ + public string Message { get; set; } +} + +var updates = Application.Topic("updates"); + +Application.Run(); +``` + +## Parameters + + + + The name of the topic to create. + + + +## Examples + +### Create a new topic + +```csharp +using Application = Nitric.Sdk.Nitric; + +class EventUpdate +{ + public string Message { get; set; } +} + +var updates = Application.Topic("updates"); + +Application.Run(); +``` + +## See also + +- [Topic.Subscribe()](./topic-subscribe) +- [Topic.Publish()](./topic-publish) diff --git a/docs/reference/csharp/websocket/connection-close.mdx b/docs/reference/csharp/websocket/connection-close.mdx new file mode 100644 index 000000000..bc8ddb962 --- /dev/null +++ b/docs/reference/csharp/websocket/connection-close.mdx @@ -0,0 +1,47 @@ +--- +description: "Reference for Nitric's .NET library - Close a connection to a websocket" +--- + +# .NET - Connection.CloseConnection() + +Closes a connection to a websocket + +```csharp +using Application = Nitric.Sdk.Nitric; + +var websocket = Application.Websocket("public"); + +websocket.Connection("D28BA458-BFF4-404A").CloseConnection(); + +Application.Run(); +``` + +## Examples + +### Close a connection to the websocket on message + +```csharp +using Nitric.Sdk.Service; +using Application = Nitric.Sdk.Nitric; + +class WebsocketMessage +{ + public string Status { get; set; } +} + +var websocket = Application.Websocket("public"); + +// Broadcast message to all the registered websocket connections +websocket.On(WebsocketEventType.Message, ctx => { + var message = ctx.Req.Message(); + + if (message.Status == "close") + { + websocket.Connection(ctx.Req.ConnectionId).CloseConnection(); + } + + return ctx; +}); + +Application.Run(); +``` diff --git a/docs/reference/csharp/websocket/connection-send.mdx b/docs/reference/csharp/websocket/connection-send.mdx new file mode 100644 index 000000000..9a8e557e4 --- /dev/null +++ b/docs/reference/csharp/websocket/connection-send.mdx @@ -0,0 +1,78 @@ +--- +description: "Reference for Nitric's .NET library - Send a message to the websocket" +--- + +# .NET - Websocket.SendMessage() + +Send a message from the websocket to a connection. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var websocket = Application.Websocket("public"); + +websocket.Connection("D28BA458-BFF4-404A").SendMessage("Hello World"); + +Application.Run(); +``` + +## Parameters + + + + The message that should be sent to the connection. + + + +## Examples + +### Broadcasting a message to all connections. + + + Do not send messages to a connection during it's `connect` callback, if you + need to acknowledge connection, do so by using a [topic](../topic/topic) + + +```csharp +using Nitric.Sdk.Service; +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class OpenConnection +{ + public string Id { get; set; } +} + +var websocket = Application.Websocket("public"); + +var connections = Application.KV("connections").Allow( + KeyValueStorePermission.Set, KeyValueStorePermission.Get, KeyValueStorePermission.Delete +); + +websocket.On(WebsocketEventType.Connected, ctx => +{ + connections.Set(ctx.Req.ConnectionId, new OpenConnection { Id = ctx.Req.ConnectionId }); + return ctx; +}); + +websocket.On(WebsocketEventType.Disconnected, ctx => +{ + connections.Delete(ctx.Req.ConnectionId); + return ctx; +}); + +websocket.On(WebsocketEventType.Message, ctx => +{ + var keys = connections.Keys(); + + while (keys.MoveNext()) + { + var message = ctx.Req.Message(); + websocket.Connection(keys.Current).SendMessage(message); + } + + return ctx; +}); + +Application.Run(); +``` diff --git a/docs/reference/csharp/websocket/websocket-connection.mdx b/docs/reference/csharp/websocket/websocket-connection.mdx new file mode 100644 index 000000000..635109c01 --- /dev/null +++ b/docs/reference/csharp/websocket/websocket-connection.mdx @@ -0,0 +1,30 @@ +--- +description: "Reference for Nitric's .NET library - Get a reference to a websocket connection" +--- + +# .NET - Websocket.Connection() + +Get a reference to a websocket connection + +```csharp +using Application = Nitric.Sdk.Nitric; + +var websocket = Application.Websocket("public"); + +websocket.Connection("D28BA458-BFF4-404A"); + +Application.Run(); +``` + +## Parameters + + + + The ID of the connection. + + + +### See also + +- [Connection().Send()](./connection-send) +- [Connection().Close()](./connection-close) diff --git a/docs/reference/csharp/websocket/websocket-on.mdx b/docs/reference/csharp/websocket/websocket-on.mdx new file mode 100644 index 000000000..5f6d3996d --- /dev/null +++ b/docs/reference/csharp/websocket/websocket-on.mdx @@ -0,0 +1,137 @@ +--- +description: "Reference for Nitric's .NET library - Register a handler for connections, disconnections, or messages for the websocket." +--- + +# .NET - Websocket.On() + +Register a handler for connections, disconnections, or messages for the websocket. + +```csharp +using Nitric.Sdk.Service; +using Application = Nitric.Sdk.Nitric; + +var websocket = Application.Websocket("public"); + +websocket.On(WebsocketEventType.Connected, ctx => { + // handle connections + return ctx; +}); + +websocket.On(WebsocketEventType.Disconnected, ctx => { + // handle disconnections + return ctx; +}); + +websocket.On(WebsocketEventType.Message, ctx => { + // handle message + return ctx; +}); + +Application.Run(); +``` + +## Parameters + + + + The type of websocket event to listen for. Can be `Connected`, + `Disconnected`, or `Message`. + + + The middleware function to use as the handler for Websocket events. + + + +## Examples + +### Register a handler for message events + +Messages can be read as literal strings using `ctx.Req.Message()`. + +```csharp +websocket.On(WebsocketEventType.Message, ctx => { + var message = ctx.Req.Message(); + + Console.WriteLine($"New Message from {ctx.Req.ConnectionId}: {message}"); + + return ctx; +}); +``` + +Or they can be serialized to a class type using `ctx.Req.Message()`. + +```csharp +class EventUpdate +{ + public float Status { get; set; } + public string Content { get; set; } +} + +websocket.On(WebsocketEventType.Message, ctx => { + var message = ctx.Req.Message(); + + Console.WriteLine($"Status: {message.Status}, Message: {message.Content}") + + return ctx; +}); +``` + +### Manage Websocket connections + +To store Websocket connections you can use a Nitric collection. + +```csharp +using Nitric.Sdk.Service; +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +class OpenConnection +{ + public string Id { get; set; } +} + +var websocket = Application.Websocket("public"); + +var connections = Application.KV("connections").Allow( + KeyValueStorePermission.Set, KeyValueStorePermission.Get, KeyValueStorePermission.Delete +); + +websocket.On(WebsocketEventType.Connected, ctx => +{ + connections.Set(ctx.Req.ConnectionId, new OpenConnection { Id = ctx.Req.ConnectionId }); + return ctx; +}); + +websocket.On(WebsocketEventType.Disconnected, ctx => +{ + connections.Delete(ctx.Req.ConnectionId); + return ctx; +}); + +Application.Run(); +``` + +### Chain functions as a single method handler + +```csharp +using Nitric.Sdk.Service; +using Application = Nitric.Sdk.Nitric; + +private WebsocketContext ValidateRequest(WebsocketContext ctx, Func next) +{ + // Validate Request + return next(ctx); +} + +private WebsocketContext HandleRequest(WebsocketContext ctx, Func next) +{ + // Handle Request + return next(ctx); +} + +var websocket = Application.Websocket("public"); + +websocket.On(WebsocketNotificationType.Message, ValidateRequest, HandleRequest); + +Application.Run(); +``` diff --git a/docs/reference/csharp/websocket/websocket.mdx b/docs/reference/csharp/websocket/websocket.mdx new file mode 100644 index 000000000..948b2457a --- /dev/null +++ b/docs/reference/csharp/websocket/websocket.mdx @@ -0,0 +1,43 @@ +--- +description: "Reference for Nitric's .NET library - Create Websockets with the Nitric Go SDK" +--- + +# .NET - Websocket() + +Creates a new Websocket. + +```csharp +using Application = Nitric.Sdk.Nitric; + +var websocket = Application.Websocket("public"); + +Application.Run(); +``` + +## Parameters + + + + The unique name of this Websocket within the app. Subsequent calls to + `Websocket` with the same name will return the same object. + + + +## Examples + +### Create a Websocket + +```csharp +using Application = Nitric.Sdk.Nitric; + +var websocket = Application.Websocket("public"); + +Application.Run(); +``` + +### See also + +- [Websocket().On()](./websocket-on) +- [Websocket().Connection()](./websocket-connection) +- [Websocket().Connection().Send()](./connection-send) +- [Websocket().Connection().Close()](./connection-close) From fb656c39a069c534429b926549be9330c15ea726 Mon Sep 17 00:00:00 2001 From: Rak Date: Thu, 6 Mar 2025 14:32:14 -0700 Subject: [PATCH 02/14] Apply suggestions from code review --- docs/reference/csharp/api/api-delete.mdx | 5 +++-- docs/reference/csharp/api/api-get.mdx | 4 ++-- docs/reference/csharp/api/api-patch.mdx | 5 +++-- docs/reference/csharp/api/api-post.mdx | 5 +++-- docs/reference/csharp/api/api-put.mdx | 5 +++-- docs/reference/csharp/api/api-route-all.mdx | 3 +++ docs/reference/csharp/api/api-route-delete.mdx | 3 +++ docs/reference/csharp/api/api-route-get.mdx | 2 ++ docs/reference/csharp/api/api-route-patch.mdx | 1 + docs/reference/csharp/api/api-route-post.mdx | 3 +++ docs/reference/csharp/api/api-route-put.mdx | 2 ++ docs/reference/csharp/api/api.mdx | 1 + 12 files changed, 29 insertions(+), 10 deletions(-) diff --git a/docs/reference/csharp/api/api-delete.mdx b/docs/reference/csharp/api/api-delete.mdx index 0d8eb808e..a6a289f49 100644 --- a/docs/reference/csharp/api/api-delete.mdx +++ b/docs/reference/csharp/api/api-delete.mdx @@ -17,7 +17,7 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); api.Delete("/hello/:name", context => { - var name = context.Req.PathParams.get("name"); + var name = context.Req.PathParams["name"]; context.Res.Text($"Deleting {name}!"); @@ -56,7 +56,7 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); api.Delete("/hello/:name", context => { - var name = context.Req.PathParams.get("name"); + var name = context.Req.PathParams["name"]; context.Res.Text($"Deleting {name}!"); @@ -109,6 +109,7 @@ The DELETE request body is accessible from the `context.Req` object. ```csharp using Nitric.Sdk; +using System.Collections.Generic; var api = Nitric.Api("main"); diff --git a/docs/reference/csharp/api/api-get.mdx b/docs/reference/csharp/api/api-get.mdx index bf7c263c2..5909d4d56 100644 --- a/docs/reference/csharp/api/api-get.mdx +++ b/docs/reference/csharp/api/api-get.mdx @@ -17,7 +17,7 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); api.Get("/hello/:name", context => { - var name = context.Req.PathParams.get("name"); + var name = context.Req.PathParams["name"]; context.Res.Text($"Getting {name}!"); @@ -56,7 +56,7 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); api.Get("/hello/:name", context => { - var name = context.Req.PathParams.get("name"); + var name = context.Req.PathParams["name"]; context.Res.Text($"Getting {name}!"); diff --git a/docs/reference/csharp/api/api-patch.mdx b/docs/reference/csharp/api/api-patch.mdx index 3dfbc1365..bcda369be 100644 --- a/docs/reference/csharp/api/api-patch.mdx +++ b/docs/reference/csharp/api/api-patch.mdx @@ -17,7 +17,7 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); api.Patch("/hello/:name", context => { - var name = context.Req.PathParams.get("name"); + var name = context.Req.PathParams["name"]; context.Res.Text($"Patching {name}!"); @@ -56,7 +56,7 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); api.Patch("/hello/:name", context => { - var name = context.Req.PathParams.get("name"); + var name = context.Req.PathParams["name"]; context.Res.Text($"Patching {name}!"); @@ -109,6 +109,7 @@ The PATCH request body is accessible from the `context.Req` object. ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var api = Application.Api("main"); diff --git a/docs/reference/csharp/api/api-post.mdx b/docs/reference/csharp/api/api-post.mdx index bdf483aab..542765dd2 100644 --- a/docs/reference/csharp/api/api-post.mdx +++ b/docs/reference/csharp/api/api-post.mdx @@ -17,7 +17,7 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); api.Post("/hello/:name", context => { - var name = context.Req.PathParams.get("name"); + var name = context.Req.PathParams["name"]; context.Res.Text($"Creating {name}!"); @@ -56,7 +56,7 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); api.Post("/hello/:name", context => { - var name = context.Req.PathParams.get("name"); + var name = context.Req.PathParams["name"]; context.Res.Text($"Creating {name}!"); @@ -109,6 +109,7 @@ The POST request body is accessible from the `ctx.req` object. ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var api = Application.Api("main"); diff --git a/docs/reference/csharp/api/api-put.mdx b/docs/reference/csharp/api/api-put.mdx index ca1aaa572..9e413d7a1 100644 --- a/docs/reference/csharp/api/api-put.mdx +++ b/docs/reference/csharp/api/api-put.mdx @@ -17,7 +17,7 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); api.Put("/hello/:name", context => { - var name = context.Req.PathParams.get("name"); + var name = context.Req.PathParams["name"]; context.Res.Text($"Updating {name}!"); @@ -56,7 +56,7 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); api.Put("/hello/:name", context => { - var name = context.Req.PathParams.get("name"); + var name = context.Req.PathParams["name"]; context.Res.Text($"Updating {name}!"); @@ -109,6 +109,7 @@ The PUT request body is accessible from the `ctx.req` object. ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var api = Application.Api("main"); diff --git a/docs/reference/csharp/api/api-route-all.mdx b/docs/reference/csharp/api/api-route-all.mdx index 748bb1572..bc9c6981d 100644 --- a/docs/reference/csharp/api/api-route-all.mdx +++ b/docs/reference/csharp/api/api-route-all.mdx @@ -8,6 +8,7 @@ Register a single handler for all HTTP Methods (GET, POST, PUT, DELETE, PATCH) o ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); @@ -62,6 +63,7 @@ Application.Run(); ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); @@ -118,6 +120,7 @@ For methods that include a request body, such as `POST` and `PUT`, you can acces ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); diff --git a/docs/reference/csharp/api/api-route-delete.mdx b/docs/reference/csharp/api/api-route-delete.mdx index dfc100a37..10a747e5a 100644 --- a/docs/reference/csharp/api/api-route-delete.mdx +++ b/docs/reference/csharp/api/api-route-delete.mdx @@ -8,6 +8,7 @@ Register a handler for HTTP DELETE requests to the route. ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); @@ -47,6 +48,7 @@ Application.Run(); ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); @@ -103,6 +105,7 @@ The DELETE request body is accessible from the `ctx.req` object. ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); diff --git a/docs/reference/csharp/api/api-route-get.mdx b/docs/reference/csharp/api/api-route-get.mdx index b30fc94ad..3d451a425 100644 --- a/docs/reference/csharp/api/api-route-get.mdx +++ b/docs/reference/csharp/api/api-route-get.mdx @@ -8,6 +8,7 @@ Register a handler for HTTP GET requests to the route. ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); @@ -47,6 +48,7 @@ Application.Run(); ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); diff --git a/docs/reference/csharp/api/api-route-patch.mdx b/docs/reference/csharp/api/api-route-patch.mdx index ec507dc4a..76ad61ca0 100644 --- a/docs/reference/csharp/api/api-route-patch.mdx +++ b/docs/reference/csharp/api/api-route-patch.mdx @@ -105,6 +105,7 @@ The PATCH request body is accessible from the `context.Req` object. ```csharp using Application = Nitric.Sdk.Application; +using System.Collections.Generic; var api = Application.Api("main").Route("/customers"); diff --git a/docs/reference/csharp/api/api-route-post.mdx b/docs/reference/csharp/api/api-route-post.mdx index 1c9e59370..efa613542 100644 --- a/docs/reference/csharp/api/api-route-post.mdx +++ b/docs/reference/csharp/api/api-route-post.mdx @@ -8,6 +8,7 @@ Register a handler for HTTP POST requests to the route. ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); @@ -47,6 +48,7 @@ Application.Run(); ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); @@ -103,6 +105,7 @@ The POST request body is accessible from the `ctx.req` object. ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); diff --git a/docs/reference/csharp/api/api-route-put.mdx b/docs/reference/csharp/api/api-route-put.mdx index 1b5498404..588b845f9 100644 --- a/docs/reference/csharp/api/api-route-put.mdx +++ b/docs/reference/csharp/api/api-route-put.mdx @@ -8,6 +8,7 @@ Register a handler for HTTP PUT requests to the route. ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); @@ -103,6 +104,7 @@ The PUT request body is accessible from the `ctx.req` object. ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); diff --git a/docs/reference/csharp/api/api.mdx b/docs/reference/csharp/api/api.mdx index 82369eb3e..b2a6b3a11 100644 --- a/docs/reference/csharp/api/api.mdx +++ b/docs/reference/csharp/api/api.mdx @@ -96,6 +96,7 @@ Application.Run(); ```csharp using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; var secureApi = Application.Api("main", new ApiOptions( // You can optionally apply security rules to the entire API From 1ff48905fd5a6f88953fbc6082c8e402a2e7a3fa Mon Sep 17 00:00:00 2001 From: Rak Siva Date: Thu, 6 Mar 2025 15:24:52 -0700 Subject: [PATCH 03/14] Add index/reference to menu --- src/config/index.ts | 2 + src/config/reference/csharp.ts | 198 +++++++++++++++++++++++++++++++++ 2 files changed, 200 insertions(+) create mode 100644 src/config/reference/csharp.ts diff --git a/src/config/index.ts b/src/config/index.ts index 2d3cfebb3..4f8d126ba 100644 --- a/src/config/index.ts +++ b/src/config/index.ts @@ -20,6 +20,7 @@ import { PyReference } from './reference/python' import { DartReference } from './reference/dart' import { GoReference } from './reference/go' import { FaSitemap } from 'react-icons/fa' +import { CSharpReference } from './reference/csharp' export const navigation: NavEntry[] = [ { @@ -446,6 +447,7 @@ export const navigation: NavEntry[] = [ PyReference, GoReference, DartReference, + CSharpReference, ], }, { diff --git a/src/config/reference/csharp.ts b/src/config/reference/csharp.ts new file mode 100644 index 000000000..0568fc57a --- /dev/null +++ b/src/config/reference/csharp.ts @@ -0,0 +1,198 @@ +import { FaMicrosoft } from 'react-icons/fa6' +import { NavGroup } from '../types' + +export const CSharpReference: NavGroup = { + title: 'CSharp', + icon: FaMicrosoft, + items: [ + { title: 'Overview', href: '/reference/csharp', breadcrumbRoot: true }, + { + title: 'APIs', + items: [ + { title: 'api()', href: '/reference/csharp/api/api' }, + { title: 'api.get()', href: '/reference/csharp/api/api-get' }, + { title: 'api.post()', href: '/reference/csharp/api/api-post' }, + { title: 'api.put()', href: '/reference/csharp/api/api-put' }, + { title: 'api.delete()', href: '/reference/csharp/api/api-delete' }, + { title: 'api.patch()', href: '/reference/csharp/api/api-patch' }, + { title: 'api.route()', href: '/reference/csharp/api/api-route' }, + { + title: 'api.route.all()', + href: '/reference/csharp/api/api-route-all', + }, + { + title: 'api.route.get()', + href: '/reference/csharp/api/api-route-get', + }, + { + title: 'api.route.post()', + href: '/reference/csharp/api/api-route-post', + }, + { + title: 'api.route.put()', + href: '/reference/csharp/api/api-route-put', + }, + { + title: 'api.route.delete()', + href: '/reference/csharp/api/api-route-delete', + }, + { + title: 'api.route.patch()', + href: '/reference/csharp/api/api-route-patch', + }, + ], + }, + { + title: 'Batch', + items: [ + { title: 'job()', href: '/reference/csharp/batch/job' }, + { title: 'job.handler()', href: '/reference/csharp/batch/job-handler' }, + { title: 'job.submit()', href: '/reference/csharp/batch/job-submit' }, + ], + }, + { + title: 'Key Value Stores', + items: [ + { title: 'kv()', href: '/reference/csharp/keyvalue/keyvalue' }, + { title: 'kv.get()', href: '/reference/csharp/keyvalue/keyvalue-get' }, + { title: 'kv.set()', href: '/reference/csharp/keyvalue/keyvalue-set' }, + { + title: 'kv.delete()', + href: '/reference/csharp/keyvalue/keyvalue-delete', + }, + { + title: 'kv.keys()', + href: '/reference/csharp/keyvalue/keyvalue-keys', + }, + ], + }, + { + title: 'Topics', + items: [ + { title: 'topic()', href: '/reference/csharp/topic/topic' }, + { + title: 'topic.publish()', + href: '/reference/csharp/topic/topic-publish', + }, + { + title: 'topic.subscribe()', + href: '/reference/csharp/topic/topic-subscribe', + }, + ], + }, + { + title: 'Queues', + items: [ + { title: 'queue()', href: '/reference/csharp/queues/queue' }, + { + title: 'queue.enqueue()', + href: '/reference/csharp/queues/queue-enqueue', + }, + { + title: 'queue.dequeue()', + href: '/reference/csharp/queues/queue-dequeue', + }, + ], + }, + { + title: 'Secrets', + items: [ + { title: 'secret()', href: '/reference/csharp/secrets/secret' }, + { title: 'secret.put()', href: '/reference/csharp/secrets/secret-put' }, + { + title: 'secret.version()', + href: '/reference/csharp/secrets/secret-version', + }, + { + title: 'secret.latest()', + href: '/reference/csharp/secrets/secret-latest', + }, + { + title: 'secret.version.access()', + href: '/reference/csharp/secrets/secret-version-access', + }, + ], + }, + { + title: 'Storage', + items: [ + { title: 'bucket()', href: '/reference/csharp/storage/bucket' }, + { title: 'bucket.on()', href: '/reference/csharp/storage/bucket-on' }, + { + title: 'bucket.file()', + href: '/reference/csharp/storage/bucket-file', + }, + { + title: 'bucket.files()', + href: '/reference/csharp/storage/bucket-files', + }, + { + title: 'file.read()', + href: '/reference/csharp/storage/bucket-file-read', + }, + { + title: 'file.write()', + href: '/reference/csharp/storage/bucket-file-write', + }, + { + title: 'file.delete()', + href: '/reference/csharp/storage/bucket-file-delete', + }, + { + title: 'file.getDownloadUrl()', + href: '/reference/csharp/storage/bucket-file-downloadurl', + }, + { + title: 'file.getUploadUrl()', + href: '/reference/csharp/storage/bucket-file-uploadurl', + }, + ], + }, + { + title: 'SQL', + items: [ + { title: 'sql()', href: '/reference/csharp/sql/sql' }, + { + title: 'sql.connectionString()', + href: '/reference/csharp/sql/sql-connection-string', + }, + ], + }, + { + title: 'Schedules', + items: [ + { title: 'schedule()', href: '/reference/csharp/schedule/schedule' }, + { + title: 'schedule.every()', + href: '/reference/csharp/schedule/schedule-every', + }, + { + title: 'schedule.cron()', + href: '/reference/csharp/schedule/schedule-cron', + }, + ], + }, + { + title: 'Websockets', + items: [ + { title: 'websocket()', href: '/reference/csharp/websocket/websocket' }, + { + title: 'websocket.on()', + href: '/reference/csharp/websocket/websocket-on', + }, + { + title: 'websocket.connection()', + href: '/reference/csharp/websocket/websocket-connection', + }, + { + title: 'connection.send()', + href: '/reference/csharp/websocket/connection-send', + }, + { + title: 'connection.close()', + href: '/reference/csharp/websocket/connection-close', + }, + ], + }, + ], +} From 3917bda885f5060c4a724f00b0fe09c9ad2b86bd Mon Sep 17 00:00:00 2001 From: Rak Siva Date: Thu, 6 Mar 2025 15:25:21 -0700 Subject: [PATCH 04/14] Add return statement to examples --- docs/reference/csharp/api/api-delete.mdx | 1 + docs/reference/csharp/api/api-patch.mdx | 1 + docs/reference/csharp/api/api-post.mdx | 1 + docs/reference/csharp/api/api-put.mdx | 1 + docs/reference/csharp/api/api-route-all.mdx | 1 + docs/reference/csharp/api/api-route-delete.mdx | 1 + docs/reference/csharp/api/api-route-patch.mdx | 1 + docs/reference/csharp/api/api-route-post.mdx | 1 + docs/reference/csharp/api/api-route-put.mdx | 1 + 9 files changed, 9 insertions(+) diff --git a/docs/reference/csharp/api/api-delete.mdx b/docs/reference/csharp/api/api-delete.mdx index a6a289f49..02c4fb9fe 100644 --- a/docs/reference/csharp/api/api-delete.mdx +++ b/docs/reference/csharp/api/api-delete.mdx @@ -116,6 +116,7 @@ var api = Nitric.Api("main"); api.Delete("/hello/:name", context => { var body = context.Req.Json>(); // parse, validate and store the request payload... + return context; }); Nitric.Run(); diff --git a/docs/reference/csharp/api/api-patch.mdx b/docs/reference/csharp/api/api-patch.mdx index bcda369be..178b6bb74 100644 --- a/docs/reference/csharp/api/api-patch.mdx +++ b/docs/reference/csharp/api/api-patch.mdx @@ -116,6 +116,7 @@ var api = Application.Api("main"); api.Patch("/hello/:name", context => { var body = context.Req.Json>(); // parse, validate and store the request payload... + return context; }); Application.Run(); diff --git a/docs/reference/csharp/api/api-post.mdx b/docs/reference/csharp/api/api-post.mdx index 542765dd2..bc5aede41 100644 --- a/docs/reference/csharp/api/api-post.mdx +++ b/docs/reference/csharp/api/api-post.mdx @@ -116,6 +116,7 @@ var api = Application.Api("main"); api.Post("/hello/:name", context => { var body = context.Req.Json>(); // parse, validate and store the request payload... + return context; }); Application.Run(); diff --git a/docs/reference/csharp/api/api-put.mdx b/docs/reference/csharp/api/api-put.mdx index 9e413d7a1..dab69c304 100644 --- a/docs/reference/csharp/api/api-put.mdx +++ b/docs/reference/csharp/api/api-put.mdx @@ -116,6 +116,7 @@ var api = Application.Api("main"); api.Put("/hello/:name", context => { var body = context.Req.Json>(); // parse, validate and store the request payload... + return context; }); Application.Run(); diff --git a/docs/reference/csharp/api/api-route-all.mdx b/docs/reference/csharp/api/api-route-all.mdx index bc9c6981d..7a065d305 100644 --- a/docs/reference/csharp/api/api-route-all.mdx +++ b/docs/reference/csharp/api/api-route-all.mdx @@ -127,6 +127,7 @@ var route = Application.Api("main").Route("/customers"); route.All(context => { var body = context.Req.Json>(); // parse, validate and store the request payload... + return context; }); Application.Run(); diff --git a/docs/reference/csharp/api/api-route-delete.mdx b/docs/reference/csharp/api/api-route-delete.mdx index 10a747e5a..7670dceb5 100644 --- a/docs/reference/csharp/api/api-route-delete.mdx +++ b/docs/reference/csharp/api/api-route-delete.mdx @@ -112,6 +112,7 @@ var route = Application.Api("main").Route("/customers"); route.Delete(context => { var body = context.Req.Json>(); // parse, validate and store the request payload... + return context; }); Application.Run(); diff --git a/docs/reference/csharp/api/api-route-patch.mdx b/docs/reference/csharp/api/api-route-patch.mdx index 76ad61ca0..198441510 100644 --- a/docs/reference/csharp/api/api-route-patch.mdx +++ b/docs/reference/csharp/api/api-route-patch.mdx @@ -112,6 +112,7 @@ var api = Application.Api("main").Route("/customers"); route.Patch(context => { var body = context.Req.Json>(); // parse, validate and store the request payload... + return context; }); Application.Run(); diff --git a/docs/reference/csharp/api/api-route-post.mdx b/docs/reference/csharp/api/api-route-post.mdx index efa613542..0b9cb2d1f 100644 --- a/docs/reference/csharp/api/api-route-post.mdx +++ b/docs/reference/csharp/api/api-route-post.mdx @@ -112,6 +112,7 @@ var route = Application.Api("main").Route("/customers"); route.Post(context => { var body = context.Req.Json>(); // parse, validate and store the request payload... + return context; }); Application.Run(); diff --git a/docs/reference/csharp/api/api-route-put.mdx b/docs/reference/csharp/api/api-route-put.mdx index 588b845f9..885353e15 100644 --- a/docs/reference/csharp/api/api-route-put.mdx +++ b/docs/reference/csharp/api/api-route-put.mdx @@ -111,6 +111,7 @@ var route = Application.Api("main").Route("/customers"); route.Put(context => { var body = context.Req.Json>(); // parse, validate and store the request payload... + return context; }); Application.Run(); From 6c39bb2fbe56b38456c0d7d41667c50e9fc3982b Mon Sep 17 00:00:00 2001 From: Ryan Cartwright Date: Fri, 7 Mar 2025 15:09:49 +1100 Subject: [PATCH 05/14] fix references to middleware --- docs/reference/csharp/api/api-delete.mdx | 47 ++++++++++--------- docs/reference/csharp/api/api-get.mdx | 35 +++++++------- docs/reference/csharp/api/api-patch.mdx | 35 +++++++------- docs/reference/csharp/api/api-post.mdx | 35 +++++++------- docs/reference/csharp/api/api-put.mdx | 35 +++++++------- docs/reference/csharp/api/api-route-all.mdx | 6 ++- .../reference/csharp/api/api-route-delete.mdx | 8 ++-- docs/reference/csharp/api/api-route-get.mdx | 6 ++- docs/reference/csharp/api/api-route-patch.mdx | 6 ++- docs/reference/csharp/api/api-route-post.mdx | 6 ++- docs/reference/csharp/api/api-route-put.mdx | 6 ++- docs/reference/csharp/api/api-route.mdx | 21 ++++++--- .../reference/csharp/queues/queue-enqueue.mdx | 2 +- docs/reference/csharp/storage/bucket.mdx | 2 +- .../csharp/websocket/websocket-on.mdx | 2 +- 15 files changed, 143 insertions(+), 109 deletions(-) diff --git a/docs/reference/csharp/api/api-delete.mdx b/docs/reference/csharp/api/api-delete.mdx index 02c4fb9fe..41c0d99c1 100644 --- a/docs/reference/csharp/api/api-delete.mdx +++ b/docs/reference/csharp/api/api-delete.mdx @@ -71,36 +71,39 @@ Application.Run(); When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. ```csharp -using Nitric.Sdk; +using Nitric.Sdk.Service; +using Application = Nitric.Sdk.Nitric; -var api = Nitric.Api("main"); +var api = Application.Api("main"); api.Delete("/hello/:userId", - (context, next) => { - var user = context.Req.PathParams["userId"]; + new Middleware[] { + (context, next) => { + var user = context.Req.PathParams["userId"]; - // Validate the user identity - if (user != "1234") - { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; - // Return prematurely to end the middleware chain. - return context; - } + // Return prematurely to end the middleware chain. + return context; + } - // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; - context.Res.Text($"Deleting {user}"); + context.Res.Text($"Deleting {user}"); - return next(context); + return next(context); + } } ); -Nitric.Run(); +Application.Run(); ``` ### Access the request body @@ -108,10 +111,10 @@ Nitric.Run(); The DELETE request body is accessible from the `context.Req` object. ```csharp -using Nitric.Sdk; using System.Collections.Generic; +using Application = Nitric.Sdk.Nitric; -var api = Nitric.Api("main"); +var api = Application.Api("main"); api.Delete("/hello/:name", context => { var body = context.Req.Json>(); @@ -119,5 +122,5 @@ api.Delete("/hello/:name", context => { return context; }); -Nitric.Run(); +Application.Run(); ``` diff --git a/docs/reference/csharp/api/api-get.mdx b/docs/reference/csharp/api/api-get.mdx index 5909d4d56..14c7c4727 100644 --- a/docs/reference/csharp/api/api-get.mdx +++ b/docs/reference/csharp/api/api-get.mdx @@ -71,32 +71,35 @@ Application.Run(); When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. ```csharp +using Nitric.Sdk.Service; using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); api.Get("/hello/:userId", - (context, next) => { - var user = context.Req.PathParams["userId"]; + new Middleware[] { + (context, next) => { + var user = context.Req.PathParams["userId"]; - // Validate the user identity - if (user != "1234") - { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; - // Return prematurely to end the middleware chain. - return context; - } + // Return prematurely to end the middleware chain. + return context; + } - // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; - context.Res.Text($"Getting {user}"); + context.Res.Text($"Getting {user}"); - return next(context); + return next(context); + } } ); diff --git a/docs/reference/csharp/api/api-patch.mdx b/docs/reference/csharp/api/api-patch.mdx index 178b6bb74..bee2b15a5 100644 --- a/docs/reference/csharp/api/api-patch.mdx +++ b/docs/reference/csharp/api/api-patch.mdx @@ -71,32 +71,35 @@ Application.Run(); When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. ```csharp +using Nitric.Sdk.Service; using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); api.Patch("/hello/:userId", - (context, next) => { - var user = context.Req.PathParams["userId"]; + new Middleware[] { + (context, next) => { + var user = context.Req.PathParams["userId"]; - // Validate the user identity - if (user != "1234") - { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; - // Return prematurely to end the middleware chain. - return context; - } + // Return prematurely to end the middleware chain. + return context; + } - // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; - context.Res.Text($"Patching {user}"); + context.Res.Text($"Patching {user}"); - return next(context); + return next(context); + } } ); diff --git a/docs/reference/csharp/api/api-post.mdx b/docs/reference/csharp/api/api-post.mdx index bc5aede41..69038184a 100644 --- a/docs/reference/csharp/api/api-post.mdx +++ b/docs/reference/csharp/api/api-post.mdx @@ -71,32 +71,35 @@ Application.Run(); When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. ```csharp +using Nitric.Sdk.Service; using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); api.Post("/hello/:userId", - (context, next) => { - var user = context.Req.PathParams["userId"]; + new Middleware[] { + (context, next) => { + var user = context.Req.PathParams["userId"]; - // Validate the user identity - if (user != "1234") - { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; - // Return prematurely to end the middleware chain. - return context; - } + // Return prematurely to end the middleware chain. + return context; + } - // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; - context.Res.Text($"Creating {user}"); + context.Res.Text($"Creating {user}"); - return next(context); + return next(context); + } } ); diff --git a/docs/reference/csharp/api/api-put.mdx b/docs/reference/csharp/api/api-put.mdx index dab69c304..c89cdfd2c 100644 --- a/docs/reference/csharp/api/api-put.mdx +++ b/docs/reference/csharp/api/api-put.mdx @@ -71,32 +71,35 @@ Application.Run(); When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. ```csharp +using Nitric.Sdk.Service; using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); api.Put("/hello/:userId", - (context, next) => { - var user = context.Req.PathParams["userId"]; + new Middleware[] { + (context, next) => { + var user = context.Req.PathParams["userId"]; - // Validate the user identity - if (user != "1234") - { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + // Validate the user identity + if (user != "1234") + { + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; - // Return prematurely to end the middleware chain. - return context; - } + // Return prematurely to end the middleware chain. + return context; + } - // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + // Call next to continue the middleware chain. + return next(context); + }, (context, next) => { + var user = context.Req.PathParams["userId"]; - context.Res.Text($"Updating {user}"); + context.Res.Text($"Updating {user}"); - return next(context); + return next(context); + } } ); diff --git a/docs/reference/csharp/api/api-route-all.mdx b/docs/reference/csharp/api/api-route-all.mdx index 7a065d305..028d8fe5b 100644 --- a/docs/reference/csharp/api/api-route-all.mdx +++ b/docs/reference/csharp/api/api-route-all.mdx @@ -83,11 +83,13 @@ Application.Run(); When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. ```csharp +using Nitric.Sdk.Service; using Application = Nitric.Sdk.Nitric; var route = Application.Api("main").Route("/customers"); -route.All((context, next) => { +route.All(new Middleware[] { + (context, next) => { var user = context.Req.PathParams["userId"]; // Validate the user identity @@ -109,7 +111,7 @@ route.All((context, next) => { return next(context); } -); +}); Application.Run(); ``` diff --git a/docs/reference/csharp/api/api-route-delete.mdx b/docs/reference/csharp/api/api-route-delete.mdx index 7670dceb5..2ae54d34c 100644 --- a/docs/reference/csharp/api/api-route-delete.mdx +++ b/docs/reference/csharp/api/api-route-delete.mdx @@ -68,11 +68,13 @@ Application.Run(); When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. ```csharp +using Nitric.Sdk.Service; using Application = Nitric.Sdk.Nitric; -var route = Nitric.Api("main").Route("/customers/:userId"); +var route = Application.Api("main").Route("/customers/:userId"); -route.Delete((context, next) => { +route.Delete(new Middleware[] { + (context, next) => { var user = context.Req.PathParams["userId"]; // Validate the user identity @@ -94,7 +96,7 @@ route.Delete((context, next) => { return next(context); } -); +}); Application.Run(); ``` diff --git a/docs/reference/csharp/api/api-route-get.mdx b/docs/reference/csharp/api/api-route-get.mdx index 3d451a425..2b3c2f50c 100644 --- a/docs/reference/csharp/api/api-route-get.mdx +++ b/docs/reference/csharp/api/api-route-get.mdx @@ -68,11 +68,13 @@ Application.Run(); When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. ```csharp +using Nitric.Sdk.Service; using Application = Nitric.Sdk.Nitric; var route = Application.Api("main").Route("/customers"); -route.Get((context, next) => { +route.Get(new Middleware[] { + (context, next) => { var user = context.Req.PathParams["userId"]; // Validate the user identity @@ -94,7 +96,7 @@ route.Get((context, next) => { return next(context); } -); +}); Application.Run(); ``` diff --git a/docs/reference/csharp/api/api-route-patch.mdx b/docs/reference/csharp/api/api-route-patch.mdx index 198441510..406cddef6 100644 --- a/docs/reference/csharp/api/api-route-patch.mdx +++ b/docs/reference/csharp/api/api-route-patch.mdx @@ -68,11 +68,13 @@ Application.Run(); When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. ```csharp +using Nitric.Sdk.Service; using Application = Nitric.Sdk.Application; var route = Application.Api("main").Route("/customers/:userId"); -route.Patch((context, next) => { +route.Patch(new Middleware[] { + (context, next) => { var user = context.Req.PathParams["userId"]; // Validate the user identity @@ -94,7 +96,7 @@ route.Patch((context, next) => { return next(context); } -); +}); Application.Run(); ``` diff --git a/docs/reference/csharp/api/api-route-post.mdx b/docs/reference/csharp/api/api-route-post.mdx index 0b9cb2d1f..ae56d4ff4 100644 --- a/docs/reference/csharp/api/api-route-post.mdx +++ b/docs/reference/csharp/api/api-route-post.mdx @@ -68,11 +68,13 @@ Application.Run(); When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. ```csharp +using Nitric.Sdk.Service; using Application = Nitric.Sdk.Application; var route = Application.Api("main").Route("/customers/:userId"); -route.Post((context, next) => { +route.Post(new Middleware[] { + (context, next) => { var user = context.Req.PathParams["userId"]; // Validate the user identity @@ -94,7 +96,7 @@ route.Post((context, next) => { return next(context); } -); +}); Application.Run(); ``` diff --git a/docs/reference/csharp/api/api-route-put.mdx b/docs/reference/csharp/api/api-route-put.mdx index 885353e15..f12912cb8 100644 --- a/docs/reference/csharp/api/api-route-put.mdx +++ b/docs/reference/csharp/api/api-route-put.mdx @@ -67,11 +67,13 @@ Application.Run(); When multiple functions are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. ```csharp +using Nitric.Sdk.Service; using Application = Nitric.Sdk.Nitric; var route = Application.Api("main").Route("/customers/:userId"); -route.Put((context, next) => { +route.Put(new Middleware[] { + (context, next) => { var user = context.Req.PathParams["userId"]; // Validate the user identity @@ -93,7 +95,7 @@ route.Put((context, next) => { return next(context); } -); +}); Application.Run(); ``` diff --git a/docs/reference/csharp/api/api-route.mdx b/docs/reference/csharp/api/api-route.mdx index 987cac523..51a29bef1 100644 --- a/docs/reference/csharp/api/api-route.mdx +++ b/docs/reference/csharp/api/api-route.mdx @@ -68,24 +68,31 @@ Application.Run(); ### Create a route with middleware ```csharp -using Application = Nitric.Sdk.Application; +using Nitric.Sdk.Service; +using Nitric.Sdk.Resource; +using Application = Nitric.Sdk.Nitric; + +var main = Application.Api("main"); -var route = Application.Api("main").Route("/customers", (context, next) => { +var route = main.Route("/customers", new RouteOptions(middleware: new Middleware[] { + (context, next) => + { var user = context.Req.PathParams["userId"]; // Validate the user identity if (user != "1234") { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + context.Res.Text($"User {user} is unauthorised"); + context.Res.Status = 403; - // Return prematurely to end the middleware chain. - return context; + // Return prematurely to end the middleware chain. + return context; } // Call next to continue the middleware chain. return next(context); -}); + } +})); Application.Run(); ``` diff --git a/docs/reference/csharp/queues/queue-enqueue.mdx b/docs/reference/csharp/queues/queue-enqueue.mdx index 1c4d6e072..8284d3146 100644 --- a/docs/reference/csharp/queues/queue-enqueue.mdx +++ b/docs/reference/csharp/queues/queue-enqueue.mdx @@ -95,5 +95,5 @@ failedTasks.ForEach(failedTask => { Console.WriteLine(failedTask.ID); }); -Nitric.Run(); +Application.Run(); ``` diff --git a/docs/reference/csharp/storage/bucket.mdx b/docs/reference/csharp/storage/bucket.mdx index 55a881e83..c100684f6 100644 --- a/docs/reference/csharp/storage/bucket.mdx +++ b/docs/reference/csharp/storage/bucket.mdx @@ -12,7 +12,7 @@ using Application = Nitric.Sdk.Nitric; var assets = Application.Bucket("assets").Allow(BucketPermission.Read, BucketPermission.Write, BucketPermission.Delete); -Nitric.Run(); +Application.Run(); ``` ## Parameters diff --git a/docs/reference/csharp/websocket/websocket-on.mdx b/docs/reference/csharp/websocket/websocket-on.mdx index 5f6d3996d..c9218140d 100644 --- a/docs/reference/csharp/websocket/websocket-on.mdx +++ b/docs/reference/csharp/websocket/websocket-on.mdx @@ -131,7 +131,7 @@ private WebsocketContext HandleRequest(WebsocketContext ctx, Func Date: Mon, 10 Mar 2025 11:48:03 -0600 Subject: [PATCH 06/14] fix ApiOptions import --- docs/reference/csharp/api/api.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/reference/csharp/api/api.mdx b/docs/reference/csharp/api/api.mdx index b2a6b3a11..0fd3af08b 100644 --- a/docs/reference/csharp/api/api.mdx +++ b/docs/reference/csharp/api/api.mdx @@ -64,6 +64,7 @@ Application.Run(); ```csharp using Application = Nitric.Sdk.Application; +using Nitric.Sdk.Resource; private HttpContext ValidateRequest(HttpContext ctx, Func next) { @@ -84,6 +85,7 @@ If you need to put all the routes in your api below a shared base path, you can ```csharp using Application = Nitric.Sdk.Application; +using Nitric.Sdk.Resource; var api = Application.Api("main", new ApiOptions( BaseRoute: "/api/v1" @@ -97,6 +99,7 @@ Application.Run(); ```csharp using Application = Nitric.Sdk.Nitric; using System.Collections.Generic; +using Nitric.Sdk.Resource; var secureApi = Application.Api("main", new ApiOptions( // You can optionally apply security rules to the entire API From 7640d76c99d9700ce736c49cc942502d81f69b55 Mon Sep 17 00:00:00 2001 From: Rak Siva Date: Tue, 11 Mar 2025 11:37:24 -0600 Subject: [PATCH 07/14] Fix API reference examples for middleware, basepath and security. --- docs/reference/csharp/api/api.mdx | 77 ++++++++++++++++++------------- 1 file changed, 44 insertions(+), 33 deletions(-) diff --git a/docs/reference/csharp/api/api.mdx b/docs/reference/csharp/api/api.mdx index 0fd3af08b..5fb42aebb 100644 --- a/docs/reference/csharp/api/api.mdx +++ b/docs/reference/csharp/api/api.mdx @@ -63,19 +63,24 @@ Application.Run(); ### Create an API with universal middleware ```csharp -using Application = Nitric.Sdk.Application; +using Application = Nitric.Sdk.Nitric; using Nitric.Sdk.Resource; - -private HttpContext ValidateRequest(HttpContext ctx, Func next) -{ - // Validation logic - return next(ctx); -} +using Nitric.Sdk.Service; var api = Application.Api("main", new ApiOptions( - Middleware: new Middleware[] { ValidateRequest } + middleware: new Middleware[] { + (context, next) => { + return next(context); + } + } )); +api.Get("/example", (ctx) => +{ + ctx.Res.Text("Hello World!"); + return ctx; +}); + Application.Run(); ``` @@ -84,13 +89,20 @@ Application.Run(); If you need to put all the routes in your api below a shared base path, you can do that with the `BaseRoute` option. In this example we ensure all routes start with `/api/v1/` before the route specific path. ```csharp -using Application = Nitric.Sdk.Application; +using Application = Nitric.Sdk.Nitric; using Nitric.Sdk.Resource; var api = Application.Api("main", new ApiOptions( - BaseRoute: "/api/v1" + basePath: "/api/v1" )); +// Define API routes +api.Get("/example", (ctx) => +{ + ctx.Res.Text("Hello World!"); + return ctx; +}); + Application.Run(); ``` @@ -98,33 +110,32 @@ Application.Run(); ```csharp using Application = Nitric.Sdk.Nitric; -using System.Collections.Generic; using Nitric.Sdk.Resource; +using System.Collections.Generic; + +// Define security configuration +var securityOptions = new OidcOptions[] +{ + new OidcOptions( + name: "user", + audiences: ["YOUR_AUDIENCES"], + issuer: "https://example-issuer.com", + // Optionally apply required scopes to this api + // in this case users will require the products:read scope to access the API + scopes: new string[] { "products:read" } + ) +}; var secureApi = Application.Api("main", new ApiOptions( - // You can optionally apply security rules to the entire API - Security: new Dictionary - { - // apply the 'user security definition the whole API' - { - "user", - // Optionally apply required scopes to this api - // in this case users will require the products:read scope to access the API - new string[] { "products:read" } - }, - }, - // security requirements for your API are defined here - SecurityDefinitions: new Dictionary - { - // define a security definition called 'user' - { "user", - new JwtSecurityDefinition( - 'https://example-issuer.com', - new string[] { "YOUR_AUDIENCES" } - ) - } - } + security: securityOptions )); +// Define API routes +api.Get("/example", (ctx) => +{ + ctx.Res.Text("Hello, Secure World!"); + return ctx; +}); + Application.Run(); ``` From fa19cacd92d703024555754879542412daeceab0 Mon Sep 17 00:00:00 2001 From: Rak Siva Date: Tue, 11 Mar 2025 11:59:01 -0600 Subject: [PATCH 08/14] Fix API parameters to match SDK --- docs/reference/csharp/api/api.mdx | 48 ++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 17 deletions(-) diff --git a/docs/reference/csharp/api/api.mdx b/docs/reference/csharp/api/api.mdx index 5fb42aebb..6ba879ac5 100644 --- a/docs/reference/csharp/api/api.mdx +++ b/docs/reference/csharp/api/api.mdx @@ -17,33 +17,47 @@ Application.Run(); ## Parameters - + The unique name of this API within the app. Subsequent calls to `api` with the same name will return the same object. - - Security definitions defined by this API. - - - Security rules to apply with scopes to the entire API. Keys must match a - `securityDefinition`. - - - A `SecurityDefinition` object is one of the following: + + Additional options when creating the API. - - The issuer for the JWT tokens e.g. `https://account.region.auth0.com`. + + Base path for all routes in the API. + + + Middleware to apply to all routes and methods of the API. - - The `aud` that will be applied to JWT tokens from the issuer. + + Security rules to apply with scopes to the entire API. +### OidcOptions Parameters + + + + the name of the security definition + + + the issuer for the JWT tokens e.g.{' '} + https://account.region.auth0.com + + + the aud that will be applied to JWT tokens from the issuer. + + + the scopes that will be required to authenticate. + + + ## Notes The `middleware` property on the `options` param is useful for applying universal middleware such as CORS headers or Auth, across an entire API from a single place. From 404e3ec998434f1e3039ff0148fd4de6e7a8eeb3 Mon Sep 17 00:00:00 2001 From: Rak Siva Date: Tue, 11 Mar 2025 13:28:09 -0600 Subject: [PATCH 09/14] Fix dequeue examples --- docs/reference/csharp/queues/queue-dequeue.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/csharp/queues/queue-dequeue.mdx b/docs/reference/csharp/queues/queue-dequeue.mdx index a6a4c87bd..e3bf6c6f9 100644 --- a/docs/reference/csharp/queues/queue-dequeue.mdx +++ b/docs/reference/csharp/queues/queue-dequeue.mdx @@ -23,7 +23,7 @@ var tasks = batchQueue.Dequeue(); tasks.ForEach(task => { // Work on a task... - Console.WriteLine($"Request from user {task.Payload.UserId}: {task.Payload.Message}"); + Console.WriteLine($"Request from user {task.Message.UserId}: {task.Message.Message}"); // Complete the task task.Complete(); @@ -86,7 +86,7 @@ var tasks = batchQueue.Dequeue(); tasks.ForEach(task => { // Work on a task... - Console.WriteLine($"Request from user {task.Payload.UserId}: {task.Payload.Message}"); + Console.WriteLine($"Request from user {task.Message.UserId}: {task.Message.Message}"); // Complete the task task.Complete(); From 623cd64e2289e65630b117b2c3d5099af6efe3bf Mon Sep 17 00:00:00 2001 From: Rak Siva Date: Tue, 11 Mar 2025 13:41:16 -0600 Subject: [PATCH 10/14] fix secret examples that cause warnings for uppercase name --- docs/reference/csharp/secrets/secret-latest.mdx | 6 +++--- docs/reference/csharp/secrets/secret-put.mdx | 10 +++++----- .../reference/csharp/secrets/secret-version-access.mdx | 6 +++--- docs/reference/csharp/secrets/secret.mdx | 4 ++-- 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/reference/csharp/secrets/secret-latest.mdx b/docs/reference/csharp/secrets/secret-latest.mdx index f445a6c91..102fa24af 100644 --- a/docs/reference/csharp/secrets/secret-latest.mdx +++ b/docs/reference/csharp/secrets/secret-latest.mdx @@ -10,7 +10,7 @@ Returns a reference to the `latest` version of a secret, regardless of that vers using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); +var keyRef = Application.Secret("apikey").Allow(SecretPermission.Access); var latestVersion = keyRef.Latest(); @@ -31,7 +31,7 @@ For symmetric encryption, you'll need to retrieve the version of the secret used using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); +var keyRef = Application.Secret("apikey").Allow(SecretPermission.Access); var latestVersion = keyRef.Latest(); @@ -44,7 +44,7 @@ Application.Run(); using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); +var keyRef = Application.Secret("apikey").Allow(SecretPermission.Access); var latestVersion = keyRef.Latest().Access(); diff --git a/docs/reference/csharp/secrets/secret-put.mdx b/docs/reference/csharp/secrets/secret-put.mdx index 89ee8b7d2..bdef9c69f 100644 --- a/docs/reference/csharp/secrets/secret-put.mdx +++ b/docs/reference/csharp/secrets/secret-put.mdx @@ -10,7 +10,7 @@ Store a new secret value, creating a new [version](./secret-version) to store th using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Put); +var keyRef = Application.Secret("apikey").Allow(SecretPermission.Put); keyRef.Put("6c3199a3-094e-4797-bfc9-9ee2a7839286"); @@ -37,7 +37,7 @@ A new secret version is always created when calling `Put()`, the versions will a using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Put); +var keyRef = Application.Secret("apikey").Allow(SecretPermission.Put); keyRef.Put("6c3199a3-094e-4797-bfc9-9ee2a7839286"); @@ -52,11 +52,11 @@ Calling `Put()` returns a promise to a reference to the new secret version. Stor using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Put); +var keyRef = Application.Secret("apikey").Allow(SecretPermission.Put); -var newApiKeyVersionRef = keyRef.Put("6c3199a3-094e-4797-bfc9-9ee2a7839286"); +var newapikeyVersionRef = keyRef.Put("6c3199a3-094e-4797-bfc9-9ee2a7839286"); -var versionId = newApiKeyVersionRef.Id; +var versionId = newapikeyVersionRef.Id; Application.Run(); ``` diff --git a/docs/reference/csharp/secrets/secret-version-access.mdx b/docs/reference/csharp/secrets/secret-version-access.mdx index 66860114c..bb1ebb1dc 100644 --- a/docs/reference/csharp/secrets/secret-version-access.mdx +++ b/docs/reference/csharp/secrets/secret-version-access.mdx @@ -10,7 +10,7 @@ Retrieves the value from a version of a secret. using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); +var keyRef = Application.Secret("apikey").Allow(SecretPermission.Access); var keyValue = keyRef.Latest().Access(); @@ -27,7 +27,7 @@ Application.Run(); using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); +var keyRef = Application.Secret("apikey").Allow(SecretPermission.Access); var keyValue = keyRef.Latest().Access(); @@ -42,7 +42,7 @@ Application.Run(); using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); +var keyRef = Application.Secret("apikey").Allow(SecretPermission.Access); var keyValue = keyRef.Version("the-version-id").Access(); diff --git a/docs/reference/csharp/secrets/secret.mdx b/docs/reference/csharp/secrets/secret.mdx index a14b0c68a..9aa8759f5 100644 --- a/docs/reference/csharp/secrets/secret.mdx +++ b/docs/reference/csharp/secrets/secret.mdx @@ -10,7 +10,7 @@ Creates a reference to a secret in the secrets manager. using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); +var keyRef = Application.Secret("apikey").Allow(SecretPermission.Access); Application.Run(); ``` @@ -51,7 +51,7 @@ This permission allows your code to retrieve secret values. using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var keyRef = Application.Secret("apiKey").Allow(SecretPermission.Access); +var keyRef = Application.Secret("apikey").Allow(SecretPermission.Access); Application.Run(); ``` From 7695199f35b0562fcca57bd2b8d4b53cd98edc99 Mon Sep 17 00:00:00 2001 From: Rak Siva Date: Tue, 11 Mar 2025 13:54:44 -0600 Subject: [PATCH 11/14] fix secrets value access example --- docs/reference/csharp/secrets/secret-version-access.mdx | 6 +++--- docs/reference/csharp/secrets/secret-version.mdx | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/csharp/secrets/secret-version-access.mdx b/docs/reference/csharp/secrets/secret-version-access.mdx index bb1ebb1dc..29f31f21a 100644 --- a/docs/reference/csharp/secrets/secret-version-access.mdx +++ b/docs/reference/csharp/secrets/secret-version-access.mdx @@ -14,7 +14,7 @@ var keyRef = Application.Secret("apikey").Allow(SecretPermission.Access); var keyValue = keyRef.Latest().Access(); -keyValue.ValueText; +keyValue.Value; Application.Run(); ``` @@ -31,7 +31,7 @@ var keyRef = Application.Secret("apikey").Allow(SecretPermission.Access); var keyValue = keyRef.Latest().Access(); -keyValue.ValueText; +keyValue.Value; Application.Run(); ``` @@ -46,7 +46,7 @@ var keyRef = Application.Secret("apikey").Allow(SecretPermission.Access); var keyValue = keyRef.Version("the-version-id").Access(); -keyValue.ValueText; +keyValue.Value; Application.Run(); ``` diff --git a/docs/reference/csharp/secrets/secret-version.mdx b/docs/reference/csharp/secrets/secret-version.mdx index b138570ef..171e164bd 100644 --- a/docs/reference/csharp/secrets/secret-version.mdx +++ b/docs/reference/csharp/secrets/secret-version.mdx @@ -50,7 +50,7 @@ var keyRef = Application.Secret("encryptionKey").With(SecretPermission.Accessing var keyVersionRef = keyRef.Version("the-version-id").Access(); -var keyValue = keyVersionRef.ValueText; +var keyValue = keyVersionRef.Value; Application.Run(); ``` From 53e82c9fb67ba4cc3077c663baf6fdbb5ce2ee8f Mon Sep 17 00:00:00 2001 From: Rak Siva Date: Tue, 11 Mar 2025 14:03:58 -0600 Subject: [PATCH 12/14] fix string literal issue with bucket example --- docs/reference/csharp/storage/bucket-file-delete.mdx | 8 ++++---- .../csharp/storage/bucket-file-downloadurl.mdx | 10 +++++----- docs/reference/csharp/storage/bucket-file-read.mdx | 8 ++++---- .../reference/csharp/storage/bucket-file-uploadurl.mdx | 8 ++++---- docs/reference/csharp/storage/bucket-file-write.mdx | 8 ++++---- 5 files changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/reference/csharp/storage/bucket-file-delete.mdx b/docs/reference/csharp/storage/bucket-file-delete.mdx index cfac77c3f..8738e69b4 100644 --- a/docs/reference/csharp/storage/bucket-file-delete.mdx +++ b/docs/reference/csharp/storage/bucket-file-delete.mdx @@ -10,9 +10,9 @@ Delete a file from a bucket. using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var assets = Application.Bucket('assets').Allow(BucketPermission.Delete); +var assets = Application.Bucket("assets").Allow(BucketPermission.Delete); -var logo = assets.File('images/logo.png'); +var logo = assets.File("images/logo.png"); logo.Delete(); @@ -27,9 +27,9 @@ Application.Run(); using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var assets = Application.Bucket('assets').Allow(BucketPermission.Delete); +var assets = Application.Bucket("assets").Allow(BucketPermission.Delete); -var logo = assets.File('images/logo.png'); +var logo = assets.File("images/logo.png"); logo.Delete(); diff --git a/docs/reference/csharp/storage/bucket-file-downloadurl.mdx b/docs/reference/csharp/storage/bucket-file-downloadurl.mdx index 4ee8f94ea..b864fef75 100644 --- a/docs/reference/csharp/storage/bucket-file-downloadurl.mdx +++ b/docs/reference/csharp/storage/bucket-file-downloadurl.mdx @@ -10,9 +10,9 @@ Create a download url for a file within a bucket. using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var assets = Application.Bucket('assets').Allow(BucketPermission.Read); +var assets = Application.Bucket("assets").Allow(BucketPermission.Read); -var logo = assets.File('images/logo.png'); +var logo = assets.File("images/logo.png"); // Create a read-only signed url reference for downloading var downloadUrl = logo.GetDownloadUrl(); @@ -36,9 +36,9 @@ Application.Run(); using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var assets = Application.Bucket('assets').Allow(BucketPermission.Read); +var assets = Application.Bucket("assets").Allow(BucketPermission.Read); -var logo = assets.File('images/logo.png'); +var logo = assets.File("images/logo.png"); // Create a read-only signed url reference for downloading var downloadUrl = logo.GetDownloadUrl(); @@ -52,7 +52,7 @@ Application.Run(); using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var images = Application.Bucket('images').Allow(BucketPermission.Read); +var images = Application.Bucket("images").Allow(BucketPermission.Read); var mainApi = Application.Api("main"); mainApi.Get("/images/:id", context => { diff --git a/docs/reference/csharp/storage/bucket-file-read.mdx b/docs/reference/csharp/storage/bucket-file-read.mdx index 779549690..8d50c1d5f 100644 --- a/docs/reference/csharp/storage/bucket-file-read.mdx +++ b/docs/reference/csharp/storage/bucket-file-read.mdx @@ -10,9 +10,9 @@ Read the contents of a file from a bucket. using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var assets = Application.Bucket('assets').Allow(BucketPermission.Read); +var assets = Application.Bucket("assets").Allow(BucketPermission.Read); -var logo = assets.File('images/logo.png'); +var logo = assets.File("images/logo.png"); var logoData = logo.Read(); @@ -27,9 +27,9 @@ Application.Run(); using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var assets = Application.Bucket('assets').Allow(BucketPermission.Read); +var assets = Application.Bucket("assets").Allow(BucketPermission.Read); -var logo = assets.File('images/logo.png'); +var logo = assets.File("images/logo.png"); var logoData = logo.Read(); diff --git a/docs/reference/csharp/storage/bucket-file-uploadurl.mdx b/docs/reference/csharp/storage/bucket-file-uploadurl.mdx index b4bcd4897..c99a8e845 100644 --- a/docs/reference/csharp/storage/bucket-file-uploadurl.mdx +++ b/docs/reference/csharp/storage/bucket-file-uploadurl.mdx @@ -10,9 +10,9 @@ Create a upload url for a file within a bucket. using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var assets = Application.Bucket('assets').Allow(BucketPermission.Write); +var assets = Application.Bucket("assets").Allow(BucketPermission.Write); -var logo = assets.File('images/logo.png'); +var logo = assets.File("images/logo.png"); // Create a read-only signed url reference for uploading var uploadUrl = logo.GetUploadUrl(); @@ -36,9 +36,9 @@ Application.Run(); using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var assets = Application.Bucket('assets').Allow(BucketPermission.Write); +var assets = Application.Bucket("assets").Allow(BucketPermission.Write); -var logo = assets.File('images/logo.png'); +var logo = assets.File("images/logo.png"); // Create a read-only signed url reference for uploading var uploadUrl = logo.GetUploadUrl(); diff --git a/docs/reference/csharp/storage/bucket-file-write.mdx b/docs/reference/csharp/storage/bucket-file-write.mdx index bbd7c2409..678baa49d 100644 --- a/docs/reference/csharp/storage/bucket-file-write.mdx +++ b/docs/reference/csharp/storage/bucket-file-write.mdx @@ -10,9 +10,9 @@ Write a file to a bucket. using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var assets = Application.Bucket('assets').Allow(BucketPermission.Read); +var assets = Application.Bucket("assets").Allow(BucketPermission.Read); -var logo = assets.File('images/logo.png'); +var logo = assets.File("images/logo.png"); logo.Write(someImageData); @@ -35,9 +35,9 @@ Application.Run(); using Nitric.Sdk.Resource; using Application = Nitric.Sdk.Nitric; -var assets = Application.Bucket('assets').Allow(BucketPermission.Read); +var assets = Application.Bucket("assets").Allow(BucketPermission.Read); -var logo = assets.File('images/logo.png'); +var logo = assets.File("images/logo.png"); logo.Write(someImageData); From 737f5631cc2e3768e2ceeeac9cfdbb79a15341dc Mon Sep 17 00:00:00 2001 From: Rak Siva Date: Thu, 20 Mar 2025 07:52:43 -0600 Subject: [PATCH 13/14] add sdk docs back links --- docs/reference/csharp/api/api-delete.mdx | 5 +++++ docs/reference/csharp/api/api-get.mdx | 5 +++++ docs/reference/csharp/api/api-patch.mdx | 5 +++++ docs/reference/csharp/api/api-post.mdx | 5 +++++ docs/reference/csharp/api/api-put.mdx | 5 +++++ docs/reference/csharp/api/api-route-all.mdx | 5 +++++ docs/reference/csharp/api/api-route-delete.mdx | 5 +++++ docs/reference/csharp/api/api-route-get.mdx | 5 +++++ docs/reference/csharp/api/api-route-patch.mdx | 5 +++++ docs/reference/csharp/api/api-route-post.mdx | 5 +++++ docs/reference/csharp/api/api-route-put.mdx | 5 +++++ docs/reference/csharp/api/api-route.mdx | 5 +++++ docs/reference/csharp/api/api.mdx | 5 +++++ docs/reference/csharp/batch/job-handler.mdx | 5 +++++ docs/reference/csharp/batch/job-submit.mdx | 5 +++++ docs/reference/csharp/batch/job.mdx | 5 +++++ docs/reference/csharp/index.mdx | 6 ++++++ docs/reference/csharp/keyvalue/keyvalue-delete.mdx | 5 +++++ docs/reference/csharp/keyvalue/keyvalue-get.mdx | 5 +++++ docs/reference/csharp/keyvalue/keyvalue-keys.mdx | 5 +++++ docs/reference/csharp/keyvalue/keyvalue-set.mdx | 5 +++++ docs/reference/csharp/keyvalue/keyvalue.mdx | 5 +++++ docs/reference/csharp/queues/queue-dequeue.mdx | 5 +++++ docs/reference/csharp/queues/queue-enqueue.mdx | 5 +++++ docs/reference/csharp/queues/queue.mdx | 5 +++++ docs/reference/csharp/secrets/secret-latest.mdx | 5 +++++ docs/reference/csharp/secrets/secret-put.mdx | 5 +++++ docs/reference/csharp/secrets/secret-version-access.mdx | 5 +++++ docs/reference/csharp/secrets/secret-version.mdx | 5 +++++ docs/reference/csharp/secrets/secret.mdx | 5 +++++ docs/reference/csharp/sql/sql-connection-string.mdx | 5 +++++ docs/reference/csharp/sql/sql.mdx | 5 +++++ docs/reference/csharp/storage/bucket-file-delete.mdx | 5 +++++ docs/reference/csharp/storage/bucket-file-downloadurl.mdx | 5 +++++ docs/reference/csharp/storage/bucket-file-read.mdx | 5 +++++ docs/reference/csharp/storage/bucket-file-uploadurl.mdx | 5 +++++ docs/reference/csharp/storage/bucket-file-write.mdx | 5 +++++ docs/reference/csharp/storage/bucket-file.mdx | 5 +++++ docs/reference/csharp/storage/bucket-files.mdx | 5 +++++ docs/reference/csharp/storage/bucket-on.mdx | 5 +++++ docs/reference/csharp/storage/bucket.mdx | 5 +++++ docs/reference/csharp/topic/topic-publish.mdx | 6 ++++++ docs/reference/csharp/topic/topic-subscribe.mdx | 6 ++++++ docs/reference/csharp/topic/topic.mdx | 6 ++++++ docs/reference/csharp/websocket/connection-close.mdx | 5 +++++ docs/reference/csharp/websocket/connection-send.mdx | 5 +++++ docs/reference/csharp/websocket/websocket-connection.mdx | 5 +++++ docs/reference/csharp/websocket/websocket-on.mdx | 5 +++++ docs/reference/csharp/websocket/websocket.mdx | 5 +++++ 49 files changed, 249 insertions(+) diff --git a/docs/reference/csharp/api/api-delete.mdx b/docs/reference/csharp/api/api-delete.mdx index 41c0d99c1..7ce022f86 100644 --- a/docs/reference/csharp/api/api-delete.mdx +++ b/docs/reference/csharp/api/api-delete.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Register an API route and se # .NET - Api.Delete() + + This is reference documentation for the Nitric .NET SDK. To learn about APIs + in Nitric start with the [API docs](/api). + + Register an API route and set a specific HTTP DELETE handler on that route. diff --git a/docs/reference/csharp/api/api-get.mdx b/docs/reference/csharp/api/api-get.mdx index 14c7c4727..25911066d 100644 --- a/docs/reference/csharp/api/api-get.mdx +++ b/docs/reference/csharp/api/api-get.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Register an API route and se # .NET - Api.Get() + + This is reference documentation for the Nitric .NET SDK. To learn about APIs + in Nitric start with the [API docs](/api). + + Register an API route and set a specific HTTP GET handler on that route. diff --git a/docs/reference/csharp/api/api-patch.mdx b/docs/reference/csharp/api/api-patch.mdx index bee2b15a5..dbccdda69 100644 --- a/docs/reference/csharp/api/api-patch.mdx +++ b/docs/reference/csharp/api/api-patch.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Register an API route and se # .NET - Api.Patch() + + This is reference documentation for the Nitric .NET SDK. To learn about APIs + in Nitric start with the [API docs](/api). + + Register an API route and set a specific HTTP PATCH handler on that route. diff --git a/docs/reference/csharp/api/api-post.mdx b/docs/reference/csharp/api/api-post.mdx index 69038184a..055897f55 100644 --- a/docs/reference/csharp/api/api-post.mdx +++ b/docs/reference/csharp/api/api-post.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Register an API route and se # .NET - Api.Post() + + This is reference documentation for the Nitric .NET SDK. To learn about APIs + in Nitric start with the [API docs](/api). + + Register an API route and set a specific HTTP POST handler on that route. diff --git a/docs/reference/csharp/api/api-put.mdx b/docs/reference/csharp/api/api-put.mdx index c89cdfd2c..a024daef8 100644 --- a/docs/reference/csharp/api/api-put.mdx +++ b/docs/reference/csharp/api/api-put.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Register an API route and se # .NET - Api.Put() + + This is reference documentation for the Nitric .NET SDK. To learn about APIs + in Nitric start with the [API docs](/api). + + Register an API route and set a specific HTTP PUT handler on that route. diff --git a/docs/reference/csharp/api/api-route-all.mdx b/docs/reference/csharp/api/api-route-all.mdx index 028d8fe5b..03242d80f 100644 --- a/docs/reference/csharp/api/api-route-all.mdx +++ b/docs/reference/csharp/api/api-route-all.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Register a single handler fo # .NET - Api.Route.All() + + This is reference documentation for the Nitric .NET SDK. To learn about APIs + in Nitric start with the [API docs](/api). + + Register a single handler for all HTTP Methods (GET, POST, PUT, DELETE, PATCH) on the route. ```csharp diff --git a/docs/reference/csharp/api/api-route-delete.mdx b/docs/reference/csharp/api/api-route-delete.mdx index 2ae54d34c..a68db1f93 100644 --- a/docs/reference/csharp/api/api-route-delete.mdx +++ b/docs/reference/csharp/api/api-route-delete.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's v0 .NET library - Register a handler for HT # .NET - api.route.delete() + + This is reference documentation for the Nitric .NET SDK. To learn about APIs + in Nitric start with the [API docs](/api). + + Register a handler for HTTP DELETE requests to the route. ```csharp diff --git a/docs/reference/csharp/api/api-route-get.mdx b/docs/reference/csharp/api/api-route-get.mdx index 2b3c2f50c..c67de3c1c 100644 --- a/docs/reference/csharp/api/api-route-get.mdx +++ b/docs/reference/csharp/api/api-route-get.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Register a handler for HTTP # .NET - Api.Route.Get() + + This is reference documentation for the Nitric .NET SDK. To learn about APIs + in Nitric start with the [API docs](/api). + + Register a handler for HTTP GET requests to the route. ```csharp diff --git a/docs/reference/csharp/api/api-route-patch.mdx b/docs/reference/csharp/api/api-route-patch.mdx index 406cddef6..203bacb8b 100644 --- a/docs/reference/csharp/api/api-route-patch.mdx +++ b/docs/reference/csharp/api/api-route-patch.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Register a handler for HTTP # .NET - Api.Route.Patch() + + This is reference documentation for the Nitric .NET SDK. To learn about APIs + in Nitric start with the [API docs](/api). + + Register a handler for HTTP PATCH requests to the route. ```csharp diff --git a/docs/reference/csharp/api/api-route-post.mdx b/docs/reference/csharp/api/api-route-post.mdx index ae56d4ff4..873489d40 100644 --- a/docs/reference/csharp/api/api-route-post.mdx +++ b/docs/reference/csharp/api/api-route-post.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Register a handler for HTTP # .NET - Api.Route.Post() + + This is reference documentation for the Nitric .NET SDK. To learn about APIs + in Nitric start with the [API docs](/api). + + Register a handler for HTTP POST requests to the route. ```csharp diff --git a/docs/reference/csharp/api/api-route-put.mdx b/docs/reference/csharp/api/api-route-put.mdx index f12912cb8..270455742 100644 --- a/docs/reference/csharp/api/api-route-put.mdx +++ b/docs/reference/csharp/api/api-route-put.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Register a handler for HTTP # .NET - Api.Route.Put() + + This is reference documentation for the Nitric .NET SDK. To learn about APIs + in Nitric start with the [API docs](/api). + + Register a handler for HTTP PUT requests to the route. ```csharp diff --git a/docs/reference/csharp/api/api-route.mdx b/docs/reference/csharp/api/api-route.mdx index 51a29bef1..9ae846a08 100644 --- a/docs/reference/csharp/api/api-route.mdx +++ b/docs/reference/csharp/api/api-route.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Creates a new route (path) w # .NET - Api.Route() + + This is reference documentation for the Nitric .NET SDK. To learn about APIs + in Nitric start with the [API docs](/api). + + Creates a new route (path) within an API. ```csharp diff --git a/docs/reference/csharp/api/api.mdx b/docs/reference/csharp/api/api.mdx index 6ba879ac5..d6c8c1af6 100644 --- a/docs/reference/csharp/api/api.mdx +++ b/docs/reference/csharp/api/api.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Create APIs with the Nitric # .NET - Api() + + This is reference documentation for the Nitric .NET SDK. To learn about APIs + in Nitric start with the [API docs](/api). + + Creates a new HTTP API. ```csharp diff --git a/docs/reference/csharp/batch/job-handler.mdx b/docs/reference/csharp/batch/job-handler.mdx index 8e8867768..18784e9c9 100644 --- a/docs/reference/csharp/batch/job-handler.mdx +++ b/docs/reference/csharp/batch/job-handler.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Register a job handler" # .NET - Job.Handler() + + This is reference documentation for the Nitric .NET SDK. To learn about Batch + Services in Nitric start with the [Batch docs](/batch). + + Job handlers are the code that is run when a job request is submitted. These handlers should be written in a separate file to your services. ```csharp diff --git a/docs/reference/csharp/batch/job-submit.mdx b/docs/reference/csharp/batch/job-submit.mdx index 3109e2c9a..2261cc92c 100644 --- a/docs/reference/csharp/batch/job-submit.mdx +++ b/docs/reference/csharp/batch/job-submit.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Submit a batch job request w # .NET - Job.Submit() + + This is reference documentation for the Nitric .NET SDK. To learn about Batch + Services in Nitric start with the [Batch docs](/batch). + + Jobs may be submitted from Nitric `services` or other `batches` using the `Submit` method on the job reference. When submitting a job you can provide a payload that will be passed to the job handler function. ```csharp diff --git a/docs/reference/csharp/batch/job.mdx b/docs/reference/csharp/batch/job.mdx index 18b9da835..757a4de27 100644 --- a/docs/reference/csharp/batch/job.mdx +++ b/docs/reference/csharp/batch/job.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Create Batch Jobs" # .NET - Job() + + This is reference documentation for the Nitric .NET SDK. To learn about Batch + Services in Nitric start with the [Batch docs](/batch). + + Creates a new Batch Job. ```csharp diff --git a/docs/reference/csharp/index.mdx b/docs/reference/csharp/index.mdx index ecf8c69e7..f55dbdc0d 100644 --- a/docs/reference/csharp/index.mdx +++ b/docs/reference/csharp/index.mdx @@ -8,6 +8,12 @@ This SDK reference provides documentation for the functions and methods in Nitri The library provides the ability to define and interact with cloud resources, as well as build application logic like functions/handlers. + + This is reference documentation for the Nitric .NET SDK. If you're just + learning Nitric, we recommend starting with the + [Quickstart](/get-started/quickstart) guide. + + ## Installation If you used a Nitric starter template for .NET to scaffold your project, then the `Nitric.Sdk` package will already be included in the dependencies in your `.csproj` file. Using starter templates is the recommended installation option since it ensures the other files and configuration needed are also set up. diff --git a/docs/reference/csharp/keyvalue/keyvalue-delete.mdx b/docs/reference/csharp/keyvalue/keyvalue-delete.mdx index d82ef3a96..e506e6287 100644 --- a/docs/reference/csharp/keyvalue/keyvalue-delete.mdx +++ b/docs/reference/csharp/keyvalue/keyvalue-delete.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Delete key from a key value # .NET - Kv.Delete() + + This is reference documentation for the Nitric .NET SDK. To learn about + Key/Value Stores in Nitric start with the [Key/Value Store docs](/keyvalue). + + Delete key from a key value store. ```csharp diff --git a/docs/reference/csharp/keyvalue/keyvalue-get.mdx b/docs/reference/csharp/keyvalue/keyvalue-get.mdx index b89f365df..fec8c24b7 100644 --- a/docs/reference/csharp/keyvalue/keyvalue-get.mdx +++ b/docs/reference/csharp/keyvalue/keyvalue-get.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Get a value from a key value # .NET - Kv.Get() + + This is reference documentation for the Nitric .NET SDK. To learn about + Key/Value Stores in Nitric start with the [Key/Value Store docs](/keyvalue). + + Get a value from a key value store. ```csharp diff --git a/docs/reference/csharp/keyvalue/keyvalue-keys.mdx b/docs/reference/csharp/keyvalue/keyvalue-keys.mdx index 7c1261c81..78321331f 100644 --- a/docs/reference/csharp/keyvalue/keyvalue-keys.mdx +++ b/docs/reference/csharp/keyvalue/keyvalue-keys.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Retrieve all or some of the # .NET - Kv.Keys() + + This is reference documentation for the Nitric .NET SDK. To learn about + Key/Value Stores in Nitric start with the [Key/Value Store docs](/keyvalue). + + Return an async iterable of keys in the store. ```csharp diff --git a/docs/reference/csharp/keyvalue/keyvalue-set.mdx b/docs/reference/csharp/keyvalue/keyvalue-set.mdx index cac24b20e..a8739d6bc 100644 --- a/docs/reference/csharp/keyvalue/keyvalue-set.mdx +++ b/docs/reference/csharp/keyvalue/keyvalue-set.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Store a key value pair in a # .NET - Kv.Set() + + This is reference documentation for the Nitric .NET SDK. To learn about + Key/Value Stores in Nitric start with the [Key/Value Store docs](/keyvalue). + + Store a key value pair in a key value store. ```csharp diff --git a/docs/reference/csharp/keyvalue/keyvalue.mdx b/docs/reference/csharp/keyvalue/keyvalue.mdx index 1b329b024..c30838703 100644 --- a/docs/reference/csharp/keyvalue/keyvalue.mdx +++ b/docs/reference/csharp/keyvalue/keyvalue.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Creates a new key value stor # .NET - KV() + + This is reference documentation for the Nitric .NET SDK. To learn about + Key/Value Stores in Nitric start with the [Key/Value Store docs](/keyvalue). + + Creates a new key value store to get, set, and delete key value pairs. ```csharp diff --git a/docs/reference/csharp/queues/queue-dequeue.mdx b/docs/reference/csharp/queues/queue-dequeue.mdx index e3bf6c6f9..99170a3ef 100644 --- a/docs/reference/csharp/queues/queue-dequeue.mdx +++ b/docs/reference/csharp/queues/queue-dequeue.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Receive tasks from a queue." # .NET - Queue.Receive() + + This is reference documentation for the Nitric .NET SDK. To learn about Queues + in Nitric start with the [Async Messaging docs](/messaging#queues). + + Receive tasks from a queue. ```csharp diff --git a/docs/reference/csharp/queues/queue-enqueue.mdx b/docs/reference/csharp/queues/queue-enqueue.mdx index 8284d3146..42df37d2f 100644 --- a/docs/reference/csharp/queues/queue-enqueue.mdx +++ b/docs/reference/csharp/queues/queue-enqueue.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's v0 .NET library - Send tasks to a queue." # .NET - Queue.Send() + + This is reference documentation for the Nitric .NET SDK. To learn about Queues + in Nitric start with the [Async Messaging docs](/messaging#queues). + + Send tasks to a queue. ```csharp diff --git a/docs/reference/csharp/queues/queue.mdx b/docs/reference/csharp/queues/queue.mdx index 2d2471bb4..022997886 100644 --- a/docs/reference/csharp/queues/queue.mdx +++ b/docs/reference/csharp/queues/queue.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Creates a new Queue to send # .NET - Queue() + + This is reference documentation for the Nitric .NET SDK. To learn about Queues + in Nitric start with the [Async Messaging docs](/messaging#queues). + + Creates a new Queue to send and receive asynchronous tasks. ```csharp diff --git a/docs/reference/csharp/secrets/secret-latest.mdx b/docs/reference/csharp/secrets/secret-latest.mdx index 102fa24af..8767818b8 100644 --- a/docs/reference/csharp/secrets/secret-latest.mdx +++ b/docs/reference/csharp/secrets/secret-latest.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Returns a reference to the l # .NET - Secret.Latest() + + This is reference documentation for the Nitric .NET SDK. To learn about + Secrets in Nitric start with the [Secrets docs](/secrets). + + Returns a reference to the `latest` version of a secret, regardless of that version's ID. ```csharp diff --git a/docs/reference/csharp/secrets/secret-put.mdx b/docs/reference/csharp/secrets/secret-put.mdx index bdef9c69f..dcd6cb13d 100644 --- a/docs/reference/csharp/secrets/secret-put.mdx +++ b/docs/reference/csharp/secrets/secret-put.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Store a new secret value" # .NET - Secret.Put() + + This is reference documentation for the Nitric .NET SDK. To learn about + Secrets in Nitric start with the [Secrets docs](/secrets). + + Store a new secret value, creating a new [version](./secret-version) to store the value. ```csharp diff --git a/docs/reference/csharp/secrets/secret-version-access.mdx b/docs/reference/csharp/secrets/secret-version-access.mdx index 29f31f21a..524835629 100644 --- a/docs/reference/csharp/secrets/secret-version-access.mdx +++ b/docs/reference/csharp/secrets/secret-version-access.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Retrieves the value from a v # .NET - Secret.Version.Access() + + This is reference documentation for the Nitric .NET SDK. To learn about + Secrets in Nitric start with the [Secrets docs](/secrets). + + Retrieves the value from a version of a secret. ```csharp diff --git a/docs/reference/csharp/secrets/secret-version.mdx b/docs/reference/csharp/secrets/secret-version.mdx index 171e164bd..72926de70 100644 --- a/docs/reference/csharp/secrets/secret-version.mdx +++ b/docs/reference/csharp/secrets/secret-version.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Returns a reference to a kno # .NET - Secret.Version() + + This is reference documentation for the Nitric .NET SDK. To learn about + Secrets in Nitric start with the [Secrets docs](/secrets). + + Returns a reference to a known version of a secret. ```csharp diff --git a/docs/reference/csharp/secrets/secret.mdx b/docs/reference/csharp/secrets/secret.mdx index 9aa8759f5..5ab5efc43 100644 --- a/docs/reference/csharp/secrets/secret.mdx +++ b/docs/reference/csharp/secrets/secret.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Creates a reference to a sec # .NET - Secret() + + This is reference documentation for the Nitric .NET SDK. To learn about + Secrets in Nitric start with the [Secrets docs](/secrets). + + Creates a reference to a secret in the secrets manager. ```csharp diff --git a/docs/reference/csharp/sql/sql-connection-string.mdx b/docs/reference/csharp/sql/sql-connection-string.mdx index 83113cbec..2375d504e 100644 --- a/docs/reference/csharp/sql/sql-connection-string.mdx +++ b/docs/reference/csharp/sql/sql-connection-string.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Returns the connection strin # .NET - Sql.ConnectionString() + + This is reference documentation for the Nitric .NET SDK. To learn about SQL + Databases in Nitric start with the [SQL docs](/sql). + + Returns the connection string for a SQL database at runtime. ```csharp diff --git a/docs/reference/csharp/sql/sql.mdx b/docs/reference/csharp/sql/sql.mdx index ef46ed376..d1185c209 100644 --- a/docs/reference/csharp/sql/sql.mdx +++ b/docs/reference/csharp/sql/sql.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Creates a reference to a SQL # .NET - Sql() + + This is reference documentation for the Nitric .NET SDK. To learn about SQL + Databases in Nitric start with the [SQL docs](/sql). + + Creates a reference to a SQL database. ```csharp diff --git a/docs/reference/csharp/storage/bucket-file-delete.mdx b/docs/reference/csharp/storage/bucket-file-delete.mdx index 8738e69b4..1d75cf4e6 100644 --- a/docs/reference/csharp/storage/bucket-file-delete.mdx +++ b/docs/reference/csharp/storage/bucket-file-delete.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Delete a file from a bucket. # .NET - Bucket.File.Delete() + + This is reference documentation for the Nitric .NET SDK. To learn about + Buckets and Storage in Nitric start with the [Storage docs](/storage). + + Delete a file from a bucket. ```csharp diff --git a/docs/reference/csharp/storage/bucket-file-downloadurl.mdx b/docs/reference/csharp/storage/bucket-file-downloadurl.mdx index b864fef75..b40b3612e 100644 --- a/docs/reference/csharp/storage/bucket-file-downloadurl.mdx +++ b/docs/reference/csharp/storage/bucket-file-downloadurl.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Get a download url for a fil # .NET - Bucket.File.GetDownloadUrl() + + This is reference documentation for the Nitric .NET SDK. To learn about + Buckets and Storage in Nitric start with the [Storage docs](/storage). + + Create a download url for a file within a bucket. ```csharp diff --git a/docs/reference/csharp/storage/bucket-file-read.mdx b/docs/reference/csharp/storage/bucket-file-read.mdx index 8d50c1d5f..98b036e61 100644 --- a/docs/reference/csharp/storage/bucket-file-read.mdx +++ b/docs/reference/csharp/storage/bucket-file-read.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Read the contents of a file # .NET - Bucket.File.Read() + + This is reference documentation for the Nitric .NET SDK. To learn about + Buckets and Storage in Nitric start with the [Storage docs](/storage). + + Read the contents of a file from a bucket. ```csharp diff --git a/docs/reference/csharp/storage/bucket-file-uploadurl.mdx b/docs/reference/csharp/storage/bucket-file-uploadurl.mdx index c99a8e845..8487603e7 100644 --- a/docs/reference/csharp/storage/bucket-file-uploadurl.mdx +++ b/docs/reference/csharp/storage/bucket-file-uploadurl.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Get a upload url for a file # .NET - Bucket.File.GeUploadUrl() + + This is reference documentation for the Nitric .NET SDK. To learn about + Buckets and Storage in Nitric start with the [Storage docs](/storage). + + Create a upload url for a file within a bucket. ```csharp diff --git a/docs/reference/csharp/storage/bucket-file-write.mdx b/docs/reference/csharp/storage/bucket-file-write.mdx index 678baa49d..4f8ba68bc 100644 --- a/docs/reference/csharp/storage/bucket-file-write.mdx +++ b/docs/reference/csharp/storage/bucket-file-write.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Write a file to a bucket." # .NET - Bucket.File.Write() + + This is reference documentation for the Nitric .NET SDK. To learn about + Buckets and Storage in Nitric start with the [Storage docs](/storage). + + Write a file to a bucket. ```csharp diff --git a/docs/reference/csharp/storage/bucket-file.mdx b/docs/reference/csharp/storage/bucket-file.mdx index dfa066513..daa6c230a 100644 --- a/docs/reference/csharp/storage/bucket-file.mdx +++ b/docs/reference/csharp/storage/bucket-file.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Create a reference to a file # .NET - Bucket.File() + + This is reference documentation for the Nitric .NET SDK. To learn about + Buckets and Storage in Nitric start with the [Storage docs](/storage). + + Create a reference to a file within a bucket. ```csharp diff --git a/docs/reference/csharp/storage/bucket-files.mdx b/docs/reference/csharp/storage/bucket-files.mdx index ae6e30991..fc9c8d0ce 100644 --- a/docs/reference/csharp/storage/bucket-files.mdx +++ b/docs/reference/csharp/storage/bucket-files.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Get a list of file reference # .NET - Bucket.Files() + + This is reference documentation for the Nitric .NET SDK. To learn about + Buckets and Storage in Nitric start with the [Storage docs](/storage). + + Get a list of file references for files that exist in the bucket. ```csharp diff --git a/docs/reference/csharp/storage/bucket-on.mdx b/docs/reference/csharp/storage/bucket-on.mdx index 7c160542e..a61f2de9e 100644 --- a/docs/reference/csharp/storage/bucket-on.mdx +++ b/docs/reference/csharp/storage/bucket-on.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Create a new bucket notifica # .NET - Bucket.On() + + This is reference documentation for the Nitric .NET SDK. To learn about + Buckets and Storage in Nitric start with the [Storage docs](/storage). + + Create a new bucket notification trigger when certain files are created or deleted. ```csharp diff --git a/docs/reference/csharp/storage/bucket.mdx b/docs/reference/csharp/storage/bucket.mdx index c100684f6..9e7bf77d1 100644 --- a/docs/reference/csharp/storage/bucket.mdx +++ b/docs/reference/csharp/storage/bucket.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Create a new bucket for stor # .NET - Bucket() + + This is reference documentation for the Nitric .NET SDK. To learn about + Buckets and Storage in Nitric start with the [Storage docs](/storage). + + Create a new bucket for storing and retrieving files. ```csharp diff --git a/docs/reference/csharp/topic/topic-publish.mdx b/docs/reference/csharp/topic/topic-publish.mdx index dce7a7899..fa7e8fb3f 100644 --- a/docs/reference/csharp/topic/topic-publish.mdx +++ b/docs/reference/csharp/topic/topic-publish.mdx @@ -4,6 +4,12 @@ description: "Reference for Nitric's .NET library - Publish new events to the to # .NET - Topic.Publish() + + This is reference documentation for the Nitric .NET SDK. To learn about Topics + and Pub/Sub in Nitric start with the [Async Messaging + docs](/messaging#topics). + + Publish an event (push based message) to a topic. ```csharp diff --git a/docs/reference/csharp/topic/topic-subscribe.mdx b/docs/reference/csharp/topic/topic-subscribe.mdx index fd35bf470..02cb9a331 100644 --- a/docs/reference/csharp/topic/topic-subscribe.mdx +++ b/docs/reference/csharp/topic/topic-subscribe.mdx @@ -4,6 +4,12 @@ description: "Reference for Nitric's .NET library - Subscribe a handler to a top # .NET - Topic.Subscribe() + + This is reference documentation for the Nitric .NET SDK. To learn about Topics + and Pub/Sub in Nitric start with the [Async Messaging + docs](/messaging#topics). + + Subscribe a handler to a topic and receive new events for processing. ```csharp diff --git a/docs/reference/csharp/topic/topic.mdx b/docs/reference/csharp/topic/topic.mdx index edfae7422..f6c92b71c 100644 --- a/docs/reference/csharp/topic/topic.mdx +++ b/docs/reference/csharp/topic/topic.mdx @@ -4,6 +4,12 @@ description: "Reference for Nitric's .NET library - Creates a new Topic." # .NET - Topic() + + This is reference documentation for the Nitric .NET SDK. To learn about Topics + and Pub/Sub in Nitric start with the [Async Messaging + docs](/messaging#topics). + + Creates a new Topic. ```csharp diff --git a/docs/reference/csharp/websocket/connection-close.mdx b/docs/reference/csharp/websocket/connection-close.mdx index bc8ddb962..e537ba9d2 100644 --- a/docs/reference/csharp/websocket/connection-close.mdx +++ b/docs/reference/csharp/websocket/connection-close.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Close a connection to a webs # .NET - Connection.CloseConnection() + + This is reference documentation for the Nitric .NET SDK. To learn about + Websockets in Nitric start with the [Websockets docs](/websockets). + + Closes a connection to a websocket ```csharp diff --git a/docs/reference/csharp/websocket/connection-send.mdx b/docs/reference/csharp/websocket/connection-send.mdx index 9a8e557e4..88931e3ed 100644 --- a/docs/reference/csharp/websocket/connection-send.mdx +++ b/docs/reference/csharp/websocket/connection-send.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Send a message to the websoc # .NET - Websocket.SendMessage() + + This is reference documentation for the Nitric .NET SDK. To learn about + Websockets in Nitric start with the [Websockets docs](/websockets). + + Send a message from the websocket to a connection. ```csharp diff --git a/docs/reference/csharp/websocket/websocket-connection.mdx b/docs/reference/csharp/websocket/websocket-connection.mdx index 635109c01..6f79b4c6b 100644 --- a/docs/reference/csharp/websocket/websocket-connection.mdx +++ b/docs/reference/csharp/websocket/websocket-connection.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Get a reference to a websock # .NET - Websocket.Connection() + + This is reference documentation for the Nitric .NET SDK. To learn about + Websockets in Nitric start with the [Websockets docs](/websockets). + + Get a reference to a websocket connection ```csharp diff --git a/docs/reference/csharp/websocket/websocket-on.mdx b/docs/reference/csharp/websocket/websocket-on.mdx index c9218140d..170df73ff 100644 --- a/docs/reference/csharp/websocket/websocket-on.mdx +++ b/docs/reference/csharp/websocket/websocket-on.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Register a handler for conne # .NET - Websocket.On() + + This is reference documentation for the Nitric .NET SDK. To learn about + Websockets in Nitric start with the [Websockets docs](/websockets). + + Register a handler for connections, disconnections, or messages for the websocket. ```csharp diff --git a/docs/reference/csharp/websocket/websocket.mdx b/docs/reference/csharp/websocket/websocket.mdx index 948b2457a..6de31e739 100644 --- a/docs/reference/csharp/websocket/websocket.mdx +++ b/docs/reference/csharp/websocket/websocket.mdx @@ -4,6 +4,11 @@ description: "Reference for Nitric's .NET library - Create Websockets with the N # .NET - Websocket() + + This is reference documentation for the Nitric .NET SDK. To learn about + Websockets in Nitric start with the [Websockets docs](/websockets). + + Creates a new Websocket. ```csharp From e25161127c853dadf23e6f458c0b39b2b2630602 Mon Sep 17 00:00:00 2001 From: Ryan Cartwright Date: Tue, 8 Apr 2025 20:11:50 +1000 Subject: [PATCH 14/14] change to use async handlers and format --- docs/reference/csharp/api/api-delete.mdx | 42 +++++------ docs/reference/csharp/api/api-get.mdx | 36 +++++----- docs/reference/csharp/api/api-patch.mdx | 42 +++++------ docs/reference/csharp/api/api-post.mdx | 44 ++++++------ docs/reference/csharp/api/api-put.mdx | 42 +++++------ docs/reference/csharp/api/api-route-all.mdx | 71 ++++++++++++------- .../reference/csharp/api/api-route-delete.mdx | 52 +++++++------- docs/reference/csharp/api/api-route-get.mdx | 42 +++++------ docs/reference/csharp/api/api-route-patch.mdx | 56 +++++++-------- docs/reference/csharp/api/api-route-post.mdx | 50 ++++++------- docs/reference/csharp/api/api-route-put.mdx | 48 ++++++------- docs/reference/csharp/api/api-route.mdx | 16 ++--- docs/reference/csharp/api/api.mdx | 44 ++++++------ docs/reference/csharp/batch/job-handler.mdx | 6 +- docs/reference/csharp/batch/job-submit.mdx | 4 +- docs/reference/csharp/index.mdx | 2 +- .../csharp/keyvalue/keyvalue-delete.mdx | 2 +- .../csharp/keyvalue/keyvalue-get.mdx | 2 +- .../csharp/keyvalue/keyvalue-keys.mdx | 2 +- .../csharp/keyvalue/keyvalue-set.mdx | 2 +- .../reference/csharp/queues/queue-dequeue.mdx | 26 +++---- .../reference/csharp/queues/queue-enqueue.mdx | 4 +- docs/reference/csharp/queues/queue.mdx | 12 ++-- .../csharp/schedule/schedule-cron.mdx | 12 ++-- .../csharp/schedule/schedule-every.mdx | 47 +++++++----- docs/reference/csharp/schedule/schedule.mdx | 20 +++--- .../storage/bucket-file-downloadurl.mdx | 10 +-- docs/reference/csharp/storage/bucket-on.mdx | 16 ++--- .../csharp/topic/topic-subscribe.mdx | 8 +-- .../csharp/websocket/connection-close.mdx | 2 +- .../csharp/websocket/connection-send.mdx | 30 ++++---- .../csharp/websocket/websocket-on.mdx | 34 +++++---- 32 files changed, 429 insertions(+), 397 deletions(-) diff --git a/docs/reference/csharp/api/api-delete.mdx b/docs/reference/csharp/api/api-delete.mdx index 7ce022f86..9bdef22af 100644 --- a/docs/reference/csharp/api/api-delete.mdx +++ b/docs/reference/csharp/api/api-delete.mdx @@ -21,12 +21,12 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); -api.Delete("/hello/:name", context => { - var name = context.Req.PathParams["name"]; +api.Delete("/hello/:name", async (ctx) => { + var name = ctx.Req.PathParams["name"]; - context.Res.Text($"Deleting {name}!"); + ctx.Res.Text($"Deleting {name}!"); - return context; + return ctx; }); Application.Run(); @@ -60,12 +60,12 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); -api.Delete("/hello/:name", context => { - var name = context.Req.PathParams["name"]; +api.Delete("/hello/:name", async (ctx) => { + var name = ctx.Req.PathParams["name"]; - context.Res.Text($"Deleting {name}!"); + ctx.Res.Text($"Deleting {name}!"); - return context; + return ctx; }); Application.Run(); @@ -83,27 +83,27 @@ var api = Application.Api("main"); api.Delete("/hello/:userId", new Middleware[] { - (context, next) => { - var user = context.Req.PathParams["userId"]; + async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; // Validate the user identity if (user != "1234") { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + ctx.Res.Text($"User {user} is unauthorised"); + ctx.Res.Status = 403; // Return prematurely to end the middleware chain. - return context; + return ctx; } // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + return await next(ctx); + }, async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; - context.Res.Text($"Deleting {user}"); + ctx.Res.Text($"Deleting {user}"); - return next(context); + return await next(ctx); } } ); @@ -121,10 +121,10 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); -api.Delete("/hello/:name", context => { - var body = context.Req.Json>(); +api.Delete("/hello/:name", async (ctx) => { + var body = ctx.Req.Json>(); // parse, validate and store the request payload... - return context; + return ctx; }); Application.Run(); diff --git a/docs/reference/csharp/api/api-get.mdx b/docs/reference/csharp/api/api-get.mdx index 25911066d..c719e02fc 100644 --- a/docs/reference/csharp/api/api-get.mdx +++ b/docs/reference/csharp/api/api-get.mdx @@ -21,12 +21,12 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); -api.Get("/hello/:name", context => { - var name = context.Req.PathParams["name"]; +api.Get("/hello/:name", async (ctx) => { + var name = ctx.Req.PathParams["name"]; - context.Res.Text($"Getting {name}!"); + ctx.Res.Text($"Getting {name}!"); - return context; + return ctx; }); Application.Run(); @@ -60,12 +60,12 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); -api.Get("/hello/:name", context => { - var name = context.Req.PathParams["name"]; +api.Get("/hello/:name", async (ctx) => { + var name = ctx.Req.PathParams["name"]; - context.Res.Text($"Getting {name}!"); + ctx.Res.Text($"Getting {name}!"); - return context; + return ctx; }); Application.Run(); @@ -83,27 +83,27 @@ var api = Application.Api("main"); api.Get("/hello/:userId", new Middleware[] { - (context, next) => { - var user = context.Req.PathParams["userId"]; + async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; // Validate the user identity if (user != "1234") { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + ctx.Res.Text($"User {user} is unauthorised"); + ctx.Res.Status = 403; // Return prematurely to end the middleware chain. - return context; + return ctx; } // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + return await next(ctx); + }, async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; - context.Res.Text($"Getting {user}"); + ctx.Res.Text($"Getting {user}"); - return next(context); + return await next(ctx); } } ); diff --git a/docs/reference/csharp/api/api-patch.mdx b/docs/reference/csharp/api/api-patch.mdx index dbccdda69..9e8abb28d 100644 --- a/docs/reference/csharp/api/api-patch.mdx +++ b/docs/reference/csharp/api/api-patch.mdx @@ -21,12 +21,12 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); -api.Patch("/hello/:name", context => { - var name = context.Req.PathParams["name"]; +api.Patch("/hello/:name", async (ctx) => { + var name = ctx.Req.PathParams["name"]; - context.Res.Text($"Patching {name}!"); + ctx.Res.Text($"Patching {name}!"); - return context; + return ctx; }); Application.Run(); @@ -60,12 +60,12 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); -api.Patch("/hello/:name", context => { - var name = context.Req.PathParams["name"]; +api.Patch("/hello/:name", async (ctx) => { + var name = ctx.Req.PathParams["name"]; - context.Res.Text($"Patching {name}!"); + ctx.Res.Text($"Patching {name}!"); - return context; + return ctx; }); Application.Run(); @@ -83,27 +83,27 @@ var api = Application.Api("main"); api.Patch("/hello/:userId", new Middleware[] { - (context, next) => { - var user = context.Req.PathParams["userId"]; + async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; // Validate the user identity if (user != "1234") { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + ctx.Res.Text($"User {user} is unauthorised"); + ctx.Res.Status = 403; // Return prematurely to end the middleware chain. - return context; + return ctx; } // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + return await next(ctx); + }, async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; - context.Res.Text($"Patching {user}"); + ctx.Res.Text($"Patching {user}"); - return next(context); + return await next(ctx); } } ); @@ -121,10 +121,10 @@ using System.Collections.Generic; var api = Application.Api("main"); -api.Patch("/hello/:name", context => { - var body = context.Req.Json>(); +api.Patch("/hello/:name", async (ctx) => { + var body = ctx.Req.Json>(); // parse, validate and store the request payload... - return context; + return ctx; }); Application.Run(); diff --git a/docs/reference/csharp/api/api-post.mdx b/docs/reference/csharp/api/api-post.mdx index 055897f55..7eaf41cfa 100644 --- a/docs/reference/csharp/api/api-post.mdx +++ b/docs/reference/csharp/api/api-post.mdx @@ -21,12 +21,12 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); -api.Post("/hello/:name", context => { - var name = context.Req.PathParams["name"]; +api.Post("/hello/:name", async (ctx) => { + var name = ctx.Req.PathParams["name"]; - context.Res.Text($"Creating {name}!"); + ctx.Res.Text($"Creating {name}!"); - return context; + return ctx; }); Application.Run(); @@ -60,12 +60,12 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); -api.Post("/hello/:name", context => { - var name = context.Req.PathParams["name"]; +api.Post("/hello/:name", async (ctx) => { + var name = ctx.Req.PathParams["name"]; - context.Res.Text($"Creating {name}!"); + ctx.Res.Text($"Creating {name}!"); - return context; + return ctx; }); Application.Run(); @@ -83,27 +83,27 @@ var api = Application.Api("main"); api.Post("/hello/:userId", new Middleware[] { - (context, next) => { - var user = context.Req.PathParams["userId"]; + async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; // Validate the user identity if (user != "1234") { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + ctx.Res.Text($"User {user} is unauthorised"); + ctx.Res.Status = 403; - // Return prematurely to end the middleware chain. - return context; + // Return prematurely to end the middleware chain. + return ctx; } // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + return await next(ctx); + }, async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; - context.Res.Text($"Creating {user}"); + ctx.Res.Text($"Creating {user}"); - return next(context); + return await next(ctx); } } ); @@ -121,10 +121,10 @@ using System.Collections.Generic; var api = Application.Api("main"); -api.Post("/hello/:name", context => { - var body = context.Req.Json>(); +api.Post("/hello/:name", async (ctx) => { + var body = ctx.Req.Json>(); // parse, validate and store the request payload... - return context; + return ctx; }); Application.Run(); diff --git a/docs/reference/csharp/api/api-put.mdx b/docs/reference/csharp/api/api-put.mdx index a024daef8..3e58c8495 100644 --- a/docs/reference/csharp/api/api-put.mdx +++ b/docs/reference/csharp/api/api-put.mdx @@ -21,12 +21,12 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); -api.Put("/hello/:name", context => { - var name = context.Req.PathParams["name"]; +api.Put("/hello/:name", async (ctx) => { + var name = ctx.Req.PathParams["name"]; - context.Res.Text($"Updating {name}!"); + ctx.Res.Text($"Updating {name}!"); - return context; + return ctx; }); Application.Run(); @@ -60,12 +60,12 @@ using Application = Nitric.Sdk.Nitric; var api = Application.Api("main"); -api.Put("/hello/:name", context => { - var name = context.Req.PathParams["name"]; +api.Put("/hello/:name", async (ctx) => { + var name = ctx.Req.PathParams["name"]; - context.Res.Text($"Updating {name}!"); + ctx.Res.Text($"Updating {name}!"); - return context; + return ctx; }); Application.Run(); @@ -83,27 +83,27 @@ var api = Application.Api("main"); api.Put("/hello/:userId", new Middleware[] { - (context, next) => { - var user = context.Req.PathParams["userId"]; + async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; // Validate the user identity if (user != "1234") { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + ctx.Res.Text($"User {user} is unauthorised"); + ctx.Res.Status = 403; // Return prematurely to end the middleware chain. - return context; + return ctx; } // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + return await next(ctx); + }, async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; - context.Res.Text($"Updating {user}"); + ctx.Res.Text($"Updating {user}"); - return next(context); + return await next(ctx); } } ); @@ -121,10 +121,10 @@ using System.Collections.Generic; var api = Application.Api("main"); -api.Put("/hello/:name", context => { - var body = context.Req.Json>(); +api.Put("/hello/:name", async (ctx) => { + var body = ctx.Req.Json>(); // parse, validate and store the request payload... - return context; + return ctx; }); Application.Run(); diff --git a/docs/reference/csharp/api/api-route-all.mdx b/docs/reference/csharp/api/api-route-all.mdx index 03242d80f..a0caa0f46 100644 --- a/docs/reference/csharp/api/api-route-all.mdx +++ b/docs/reference/csharp/api/api-route-all.mdx @@ -17,12 +17,12 @@ using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); -route.All(context => { - // Construct a response for all incoming HTTP requests - var responseBody = new Dictionary(); - context.Res.Json(responseBody); +route.All(async (ctx) => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + ctx.Res.Json(responseBody); - return context; + return ctx; }); Application.Run(); @@ -50,12 +50,12 @@ using Application = Nitric.Sdk.Nitric; var route = Application.Api("main").Route("/customers"); -route.All(context => { +route.All(async (ctx) => { /* handle all requests */ }); // Don't call `Get()`, `Post()`, etc., they're already handled by `all()` -route.Get(context => { +route.Get(async (ctx) => { // This handler won't work }) @@ -72,12 +72,12 @@ using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); -route.All(context => { +route.All(async (ctx) => { // Construct a response for all incoming HTTP requests var responseBody = new Dictionary(); - context.Res.Json(responseBody); + ctx.Res.Json(responseBody); - return context; + return ctx; }); Application.Run(); @@ -94,27 +94,27 @@ using Application = Nitric.Sdk.Nitric; var route = Application.Api("main").Route("/customers"); route.All(new Middleware[] { - (context, next) => { - var user = context.Req.PathParams["userId"]; + async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; // Validate the user identity if (user != "1234") { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + ctx.Res.Text($"User {user} is unauthorised"); + ctx.Res.Status = 403; - // Return prematurely to end the middleware chain. - return context; + // Return prematurely to end the middleware chain. + return ctx; } // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + return next(ctx); + }, async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; - context.Res.Text($"Handling {user}"); + ctx.Res.Text($"Handling {user}"); - return next(context); + return next(ctx); } }); @@ -131,11 +131,34 @@ using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); -route.All(context => { - var body = context.Req.Json>(); +route.All(async (ctx) => { + var body = ctx.Req.Json>(); // parse, validate and store the request payload... - return context; + return ctx; }); Application.Run(); ``` + +### Error Handling + +```csharp +using Application = Nitric.Sdk.Nitric; +using System.Collections.Generic; + +var route = Application.Api("main").Route("/customers"); + +try { + route.All(async (ctx) => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + ctx.Res.Json(responseBody); + + return ctx; + }); + + Application.Run(); +} catch (Error err) { + // error handling +} +``` diff --git a/docs/reference/csharp/api/api-route-delete.mdx b/docs/reference/csharp/api/api-route-delete.mdx index a68db1f93..aa8da139c 100644 --- a/docs/reference/csharp/api/api-route-delete.mdx +++ b/docs/reference/csharp/api/api-route-delete.mdx @@ -1,8 +1,8 @@ --- -description: "Reference for Nitric's v0 .NET library - Register a handler for HTTP DELETE requests to the route." +description: "Reference for Nitric's .NET library - Register a handler for HTTP DELETE requests to the route." --- -# .NET - api.route.delete() +# .NET - Api.Route.Delete() This is reference documentation for the Nitric .NET SDK. To learn about APIs @@ -17,12 +17,12 @@ using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); -route.Delete(context => { - // Construct a response for all incoming HTTP requests - var responseBody = new Dictionary(); - context.Res.Json(responseBody); +route.Delete(async (ctx) => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + ctx.Res.Json(responseBody); - return context; + return ctx; }); Application.Run(); @@ -57,12 +57,12 @@ using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); -route.Delete(context => { - // Construct a response for all incoming HTTP requests - var responseBody = new Dictionary(); - context.Res.Json(responseBody); +route.Delete(async (ctx) => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + ctx.Res.Json(responseBody); - return context; + return ctx; }); Application.Run(); @@ -79,27 +79,27 @@ using Application = Nitric.Sdk.Nitric; var route = Application.Api("main").Route("/customers/:userId"); route.Delete(new Middleware[] { - (context, next) => { - var user = context.Req.PathParams["userId"]; + async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; // Validate the user identity if (user != "1234") { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + ctx.Res.Text($"User {user} is unauthorised"); + ctx.Res.Status = 403; - // Return prematurely to end the middleware chain. - return context; + // Return prematurely to end the middleware chain. + return ctx; } // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + return await next(ctx); + }, async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; - context.Res.Text($"Deleting {user}"); + ctx.Res.Text($"Deleting {user}"); - return next(context); + return await next(ctx); } }); @@ -116,10 +116,10 @@ using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); -route.Delete(context => { - var body = context.Req.Json>(); +route.Delete(async (ctx) => { + var body = ctx.Req.Json>(); // parse, validate and store the request payload... - return context; + return ctx; }); Application.Run(); diff --git a/docs/reference/csharp/api/api-route-get.mdx b/docs/reference/csharp/api/api-route-get.mdx index c67de3c1c..b83c3f23e 100644 --- a/docs/reference/csharp/api/api-route-get.mdx +++ b/docs/reference/csharp/api/api-route-get.mdx @@ -17,12 +17,12 @@ using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); -route.Get(context => { - // Construct a response for all incoming HTTP requests - var responseBody = new Dictionary(); - context.Res.Json(responseBody); +route.Get(async (ctx) => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + ctx.Res.Json(responseBody); - return context; + return ctx; }); Application.Run(); @@ -57,12 +57,12 @@ using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); -route.Get(context => { - // Construct a response for all incoming HTTP requests - var responseBody = new Dictionary(); - context.Res.Json(responseBody); +route.Get(async (ctx) => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + ctx.Res.Json(responseBody); - return context; + return ctx; }); Application.Run(); @@ -79,27 +79,27 @@ using Application = Nitric.Sdk.Nitric; var route = Application.Api("main").Route("/customers"); route.Get(new Middleware[] { - (context, next) => { - var user = context.Req.PathParams["userId"]; + async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; // Validate the user identity if (user != "1234") { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + ctx.Res.Text($"User {user} is unauthorised"); + ctx.Res.Status = 403; - // Return prematurely to end the middleware chain. - return context; + // Return prematurely to end the middleware chain. + return ctx; } // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + return await next(ctx); + }, async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; - context.Res.Text($"Getting {user}"); + ctx.Res.Text($"Getting {user}"); - return next(context); + return await next(ctx); } }); diff --git a/docs/reference/csharp/api/api-route-patch.mdx b/docs/reference/csharp/api/api-route-patch.mdx index 203bacb8b..1845d3e4d 100644 --- a/docs/reference/csharp/api/api-route-patch.mdx +++ b/docs/reference/csharp/api/api-route-patch.mdx @@ -16,14 +16,13 @@ using Application = Nitric.Sdk.Nitric; var route = Application.Api("main").Route("/customers/:userId"); -route.Patch(context => { - var user = context.Req.PathParams["userId"]; +route.Patch(async (ctx) => { + var user = ctx.Req.PathParams["userId"]; - context.Res.Text($"Patching {user}"); + ctx.Res.Text($"Patching {user}"); - return next(context); - } -); + return ctx; +}); Application.Run(); ``` @@ -56,14 +55,13 @@ using Application = Nitric.Sdk.Nitric; var route = Application.Api("main").Route("/customers/:userId"); -route.Patch(context => { - var user = context.Req.PathParams["userId"]; +route.Patch(async (ctx) => { + var user = ctx.Req.PathParams["userId"]; - context.Res.Text($"Patching {user}"); + ctx.Res.Text($"Patching {user}"); - return next(context); - } -); + return ctx; +}); Application.Run(); ``` @@ -74,32 +72,32 @@ When multiple functions are provided they will be called as a chain. If one succ ```csharp using Nitric.Sdk.Service; -using Application = Nitric.Sdk.Application; +using Application = Nitric.Sdk.Nitric; var route = Application.Api("main").Route("/customers/:userId"); route.Patch(new Middleware[] { - (context, next) => { - var user = context.Req.PathParams["userId"]; + async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; // Validate the user identity if (user != "1234") { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + ctx.Res.Text($"User {user} is unauthorised"); + ctx.Res.Status = 403; - // Return prematurely to end the middleware chain. - return context; + // Return prematurely to end the middleware chain. + return ctx; } // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + return await next(ctx); + }, async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; - context.Res.Text($"Patching {user}"); + ctx.Res.Text($"Patching {user}"); - return next(context); + return await next(ctx); } }); @@ -108,18 +106,18 @@ Application.Run(); ### Access the request body -The PATCH request body is accessible from the `context.Req` object. +The PATCH request body is accessible from the `ctx.Req` object. ```csharp -using Application = Nitric.Sdk.Application; +using Application = Nitric.Sdk.Nitric; using System.Collections.Generic; var api = Application.Api("main").Route("/customers"); -route.Patch(context => { - var body = context.Req.Json>(); +route.Patch(async (ctx) => { + var body = ctx.Req.Json>(); // parse, validate and store the request payload... - return context; + return ctx; }); Application.Run(); diff --git a/docs/reference/csharp/api/api-route-post.mdx b/docs/reference/csharp/api/api-route-post.mdx index 873489d40..20a271350 100644 --- a/docs/reference/csharp/api/api-route-post.mdx +++ b/docs/reference/csharp/api/api-route-post.mdx @@ -17,12 +17,12 @@ using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); -route.Post(context => { - // Construct a response for all incoming HTTP requests - var responseBody = new Dictionary(); - context.Res.Json(responseBody); +route.Post(async (ctx) => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + ctx.Res.Json(responseBody); - return context; + return ctx; }); Application.Run(); @@ -57,12 +57,12 @@ using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); -route.Post(context => { - // Construct a response for all incoming HTTP requests - var responseBody = new Dictionary(); - context.Res.Json(responseBody); +route.Post(async (ctx) => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + ctx.Res.Json(responseBody); - return context; + return ctx; }); Application.Run(); @@ -74,32 +74,32 @@ When multiple functions are provided they will be called as a chain. If one succ ```csharp using Nitric.Sdk.Service; -using Application = Nitric.Sdk.Application; +using Application = Nitric.Sdk.Nitric; var route = Application.Api("main").Route("/customers/:userId"); route.Post(new Middleware[] { - (context, next) => { - var user = context.Req.PathParams["userId"]; + async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; // Validate the user identity if (user != "1234") { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + ctx.Res.Text($"User {user} is unauthorised"); + ctx.Res.Status = 403; - // Return prematurely to end the middleware chain. - return context; + // Return prematurely to end the middleware chain. + return ctx; } // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + return await next(ctx); + }, async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; - context.Res.Text($"Creating {user}"); + ctx.Res.Text($"Creating {user}"); - return next(context); + return await next(ctx); } }); @@ -116,10 +116,10 @@ using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); -route.Post(context => { - var body = context.Req.Json>(); +route.Post(async (ctx) => { + var body = ctx.Req.Json>(); // parse, validate and store the request payload... - return context; + return ctx; }); Application.Run(); diff --git a/docs/reference/csharp/api/api-route-put.mdx b/docs/reference/csharp/api/api-route-put.mdx index 270455742..2d5ec221a 100644 --- a/docs/reference/csharp/api/api-route-put.mdx +++ b/docs/reference/csharp/api/api-route-put.mdx @@ -17,12 +17,12 @@ using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); -route.Put(context => { - // Construct a response for all incoming HTTP requests - var responseBody = new Dictionary(); - context.Res.Json(responseBody); +route.Put(async (ctx) => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + ctx.Res.Json(responseBody); - return context; + return ctx; }); Application.Run(); @@ -56,12 +56,12 @@ using Application = Nitric.Sdk.Nitric; var route = Application.Api("main").Route("/customers"); -route.Put(context => { - // Construct a response for all incoming HTTP requests - var responseBody = new Dictionary(); - context.Res.Json(responseBody); +route.Put(async (ctx) => { + // Construct a response for all incoming HTTP requests + var responseBody = new Dictionary(); + ctx.Res.Json(responseBody); - return context; + return ctx; }); Application.Run(); @@ -78,27 +78,27 @@ using Application = Nitric.Sdk.Nitric; var route = Application.Api("main").Route("/customers/:userId"); route.Put(new Middleware[] { - (context, next) => { - var user = context.Req.PathParams["userId"]; + async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; // Validate the user identity if (user != "1234") { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + ctx.Res.Text($"User {user} is unauthorised"); + ctx.Res.Status = 403; - // Return prematurely to end the middleware chain. - return context; + // Return prematurely to end the middleware chain. + return ctx; } // Call next to continue the middleware chain. - return next(context); - }, (context, next) => { - var user = context.Req.PathParams["userId"]; + return await next(ctx); + }, async (ctx, next) => { + var user = ctx.Req.PathParams["userId"]; - context.Res.Text($"Updating {user}"); + ctx.Res.Text($"Updating {user}"); - return next(context); + return await next(ctx); } }); @@ -115,10 +115,10 @@ using System.Collections.Generic; var route = Application.Api("main").Route("/customers"); -route.Put(context => { - var body = context.Req.Json>(); +route.Put(async (ctx) => { + var body = ctx.Req.Json>(); // parse, validate and store the request payload... - return context; + return ctx; }); Application.Run(); diff --git a/docs/reference/csharp/api/api-route.mdx b/docs/reference/csharp/api/api-route.mdx index 9ae846a08..975725bad 100644 --- a/docs/reference/csharp/api/api-route.mdx +++ b/docs/reference/csharp/api/api-route.mdx @@ -30,7 +30,7 @@ Application.Run(); and handlers. See [create a route with path params](#create-a-route-with-path-params) - + Additional options when creating the route. @@ -63,7 +63,7 @@ Route paths can include dynamic parameters. These values will automatically be p For example, if you have a customers path and you want to include a `customerId` param you would define the route like this. ```csharp -using Application = Nitric.Sdk.Application; +using Application = Nitric.Sdk.Nitric; var route = Application.Api("main").Route("/customers/:customerId"); @@ -80,22 +80,22 @@ using Application = Nitric.Sdk.Nitric; var main = Application.Api("main"); var route = main.Route("/customers", new RouteOptions(middleware: new Middleware[] { - (context, next) => + async (ctx, next) => { - var user = context.Req.PathParams["userId"]; + var user = ctx.Req.PathParams["userId"]; // Validate the user identity if (user != "1234") { - context.Res.Text($"User {user} is unauthorised"); - context.Res.Status = 403; + ctx.Res.Text($"User {user} is unauthorised"); + ctx.Res.Status = 403; // Return prematurely to end the middleware chain. - return context; + return ctx; } // Call next to continue the middleware chain. - return next(context); + return await next(ctx); } })); diff --git a/docs/reference/csharp/api/api.mdx b/docs/reference/csharp/api/api.mdx index d6c8c1af6..7cea2eef2 100644 --- a/docs/reference/csharp/api/api.mdx +++ b/docs/reference/csharp/api/api.mdx @@ -26,7 +26,7 @@ Application.Run(); The unique name of this API within the app. Subsequent calls to `api` with the same name will return the same object. - + Additional options when creating the API. @@ -87,17 +87,17 @@ using Nitric.Sdk.Resource; using Nitric.Sdk.Service; var api = Application.Api("main", new ApiOptions( - middleware: new Middleware[] { - (context, next) => { - return next(context); - } + middleware: new Middleware[] { + async (ctx, next) => { + return next(ctx); } + } )); -api.Get("/example", (ctx) => +api.Get("/example", async (ctx) => { - ctx.Res.Text("Hello World!"); - return ctx; + ctx.Res.Text("Hello World!"); + return ctx; }); Application.Run(); @@ -116,10 +116,10 @@ var api = Application.Api("main", new ApiOptions( )); // Define API routes -api.Get("/example", (ctx) => +api.Get("/example", async (ctx) => { - ctx.Res.Text("Hello World!"); - return ctx; + ctx.Res.Text("Hello World!"); + return ctx; }); Application.Run(); @@ -135,14 +135,14 @@ using System.Collections.Generic; // Define security configuration var securityOptions = new OidcOptions[] { - new OidcOptions( - name: "user", - audiences: ["YOUR_AUDIENCES"], - issuer: "https://example-issuer.com", - // Optionally apply required scopes to this api - // in this case users will require the products:read scope to access the API - scopes: new string[] { "products:read" } - ) + new OidcOptions( + name: "user", + audiences: ["YOUR_AUDIENCES"], + issuer: "https://example-issuer.com", + // Optionally apply required scopes to this api + // in this case users will require the products:read scope to access the API + scopes: new string[] { "products:read" } + ) }; var secureApi = Application.Api("main", new ApiOptions( @@ -150,10 +150,10 @@ var secureApi = Application.Api("main", new ApiOptions( )); // Define API routes -api.Get("/example", (ctx) => +api.Get("/example", async (ctx) => { - ctx.Res.Text("Hello, Secure World!"); - return ctx; + ctx.Res.Text("Hello, Secure World!"); + return ctx; }); Application.Run(); diff --git a/docs/reference/csharp/batch/job-handler.mdx b/docs/reference/csharp/batch/job-handler.mdx index 18784e9c9..ac444c0a6 100644 --- a/docs/reference/csharp/batch/job-handler.mdx +++ b/docs/reference/csharp/batch/job-handler.mdx @@ -18,7 +18,7 @@ using Application = Nitric.Sdk.Nitric; var analyze = Application.Job>("analyze"); -analyze.Handler((ctx) => +analyze.Handler(async (ctx) => { // Do some work return ctx; @@ -67,7 +67,7 @@ using Application = Nitric.Sdk.Nitric; var analyze = Application.Job>('analyze'); -analyze.Handler((ctx) => { +analyze.Handler(async (ctx) => { // Do some work return ctx }); @@ -84,7 +84,7 @@ using Application = Nitric.Sdk.Nitric; var analyze = Application.Job>("analyze"); -analyze.Handler((ctx) => +analyze.Handler(async (ctx) => { // Do some work return ctx; diff --git a/docs/reference/csharp/batch/job-submit.mdx b/docs/reference/csharp/batch/job-submit.mdx index 2261cc92c..7e03ed3f4 100644 --- a/docs/reference/csharp/batch/job-submit.mdx +++ b/docs/reference/csharp/batch/job-submit.mdx @@ -18,7 +18,7 @@ using Application = Nitric.Sdk.Nitric; var analyze = Application.Job>("analyze").Allow(JobPermission.Submit); -analyze.Submit(new Dictionary() { { "message", "message contents" } }); +await analyze.Submit(new Dictionary() { { "message", "message contents" } }); Application.Run(); ``` @@ -42,7 +42,7 @@ using Application = Nitric.Sdk.Nitric; var analyze = Application.Job>("analyze").Allow(JobPermission.Submit); -analyze.Submit(new Dictionary() { { "message", "message contents" } }); +await analyze.Submit(new Dictionary() { { "message", "message contents" } }); Application.Run(); ``` diff --git a/docs/reference/csharp/index.mdx b/docs/reference/csharp/index.mdx index f55dbdc0d..e80e032f3 100644 --- a/docs/reference/csharp/index.mdx +++ b/docs/reference/csharp/index.mdx @@ -30,7 +30,7 @@ To successfully run and deploy .NET applications using the Nitric framework, it ### Default Dockerfile -For your convenience, Nitric provides a default Dockerfile specifically tailored for .NET applications. This default Dockerfile is included with the [.NET starter template](https://github.com/nitrictech/examples/tree/main/v1/csharp-starter) available through the Nitric CLI. By using this template, you can quickly set up your development environment and focus on building your application without worrying about Docker configuration. +For your convenience, Nitric provides a default Dockerfile specifically tailored for .NET applications. This default Dockerfile is included with the [.NET starter template](https://github.com/nitrictech/examples/tree/main/v1/dotnet-starter) available through the Nitric CLI. By using this template, you can quickly set up your development environment and focus on building your application without worrying about Docker configuration. This Dockerfile provides a solid starting point for deploying .NET applications with Nitric. Feel free to customize it according to your application's needs. diff --git a/docs/reference/csharp/keyvalue/keyvalue-delete.mdx b/docs/reference/csharp/keyvalue/keyvalue-delete.mdx index e506e6287..61e433dfb 100644 --- a/docs/reference/csharp/keyvalue/keyvalue-delete.mdx +++ b/docs/reference/csharp/keyvalue/keyvalue-delete.mdx @@ -2,7 +2,7 @@ description: "Reference for Nitric's .NET library - Delete key from a key value store." --- -# .NET - Kv.Delete() +# .NET - KV.Delete() This is reference documentation for the Nitric .NET SDK. To learn about diff --git a/docs/reference/csharp/keyvalue/keyvalue-get.mdx b/docs/reference/csharp/keyvalue/keyvalue-get.mdx index fec8c24b7..b9cf98cca 100644 --- a/docs/reference/csharp/keyvalue/keyvalue-get.mdx +++ b/docs/reference/csharp/keyvalue/keyvalue-get.mdx @@ -2,7 +2,7 @@ description: "Reference for Nitric's .NET library - Get a value from a key value store." --- -# .NET - Kv.Get() +# .NET - KV.Get() This is reference documentation for the Nitric .NET SDK. To learn about diff --git a/docs/reference/csharp/keyvalue/keyvalue-keys.mdx b/docs/reference/csharp/keyvalue/keyvalue-keys.mdx index 78321331f..a6623da87 100644 --- a/docs/reference/csharp/keyvalue/keyvalue-keys.mdx +++ b/docs/reference/csharp/keyvalue/keyvalue-keys.mdx @@ -2,7 +2,7 @@ description: "Reference for Nitric's .NET library - Retrieve all or some of the keys from a value store." --- -# .NET - Kv.Keys() +# .NET - KV.Keys() This is reference documentation for the Nitric .NET SDK. To learn about diff --git a/docs/reference/csharp/keyvalue/keyvalue-set.mdx b/docs/reference/csharp/keyvalue/keyvalue-set.mdx index a8739d6bc..e0478f501 100644 --- a/docs/reference/csharp/keyvalue/keyvalue-set.mdx +++ b/docs/reference/csharp/keyvalue/keyvalue-set.mdx @@ -2,7 +2,7 @@ description: "Reference for Nitric's .NET library - Store a key value pair in a key value store." --- -# .NET - Kv.Set() +# .NET - KV.Set() This is reference documentation for the Nitric .NET SDK. To learn about diff --git a/docs/reference/csharp/queues/queue-dequeue.mdx b/docs/reference/csharp/queues/queue-dequeue.mdx index 99170a3ef..802c80d35 100644 --- a/docs/reference/csharp/queues/queue-dequeue.mdx +++ b/docs/reference/csharp/queues/queue-dequeue.mdx @@ -2,7 +2,7 @@ description: "Reference for Nitric's .NET library - Receive tasks from a queue." --- -# .NET - Queue.Receive() +# .NET - Queue.Dequeue() This is reference documentation for the Nitric .NET SDK. To learn about Queues @@ -18,8 +18,8 @@ using Application = Nitric.Sdk.Nitric; class UserRequest { - public string UserId { get; set; } - public string Message { get; set; } + public string UserId { get; set; } + public string Message { get; set; } } var batchQueue = Application.Queue("batch").Allow(QueuePermission.Dequeue); @@ -27,11 +27,11 @@ var batchQueue = Application.Queue("batch").Allow(QueuePermission.D var tasks = batchQueue.Dequeue(); tasks.ForEach(task => { - // Work on a task... - Console.WriteLine($"Request from user {task.Message.UserId}: {task.Message.Message}"); + // Work on a task... + Console.WriteLine($"Request from user {task.Message.UserId}: {task.Message.Message}"); - // Complete the task - task.Complete(); + // Complete the task + task.Complete(); }); Application.Run(); @@ -81,8 +81,8 @@ using Application = Nitric.Sdk.Nitric; class UserRequest { - public string UserId { get; set; } - public string Message { get; set; } + public string UserId { get; set; } + public string Message { get; set; } } var batchQueue = Application.Queue("batch").Allow(QueuePermission.Dequeue); @@ -90,11 +90,11 @@ var batchQueue = Application.Queue("batch").Allow(QueuePermission.D var tasks = batchQueue.Dequeue(); tasks.ForEach(task => { - // Work on a task... - Console.WriteLine($"Request from user {task.Message.UserId}: {task.Message.Message}"); + // Work on a task... + Console.WriteLine($"Request from user {task.Message.UserId}: {task.Message.Message}"); - // Complete the task - task.Complete(); + // Complete the task + task.Complete(); }); Application.Run(); diff --git a/docs/reference/csharp/queues/queue-enqueue.mdx b/docs/reference/csharp/queues/queue-enqueue.mdx index 42df37d2f..197ccd20e 100644 --- a/docs/reference/csharp/queues/queue-enqueue.mdx +++ b/docs/reference/csharp/queues/queue-enqueue.mdx @@ -1,8 +1,8 @@ --- -description: "Reference for Nitric's v0 .NET library - Send tasks to a queue." +description: "Reference for Nitric's .NET library - Send tasks to a queue." --- -# .NET - Queue.Send() +# .NET - Queue.Enqueue() This is reference documentation for the Nitric .NET SDK. To learn about Queues diff --git a/docs/reference/csharp/queues/queue.mdx b/docs/reference/csharp/queues/queue.mdx index 022997886..fb2bddcd8 100644 --- a/docs/reference/csharp/queues/queue.mdx +++ b/docs/reference/csharp/queues/queue.mdx @@ -17,8 +17,8 @@ using Application = Nitric.Sdk.Nitric; class UserRequest { - public string UserId { get; set; } - public string Message { get; set; } + public string UserId { get; set; } + public string Message { get; set; } } var batchQueue = Application.Queue("batchQueue").Allow(QueuePermission.Enqueue); @@ -69,8 +69,8 @@ using Application = Nitric.Sdk.Nitric; class UserRequest { - public string UserId { get; set; } - public string Message { get; set; } + public string UserId { get; set; } + public string Message { get; set; } } var batchQueue = Application.Queue("batchQueue"); @@ -86,8 +86,8 @@ using Application = Nitric.Sdk.Nitric; class UserRequest { - public string UserId { get; set; } - public string Message { get; set; } + public string UserId { get; set; } + public string Message { get; set; } } var batchQueue = Application.Queue("batchQueue").With(QueuePermission.Dequeue); diff --git a/docs/reference/csharp/schedule/schedule-cron.mdx b/docs/reference/csharp/schedule/schedule-cron.mdx index 5a6c4c624..ef3f82cf1 100644 --- a/docs/reference/csharp/schedule/schedule-cron.mdx +++ b/docs/reference/csharp/schedule/schedule-cron.mdx @@ -9,8 +9,8 @@ Sets the cron expressions that determines when the schedule triggers and a callb ```csharp using Application = Nitric.Sdk.Nitric; -Application.Schedule("send-reminder").Cron("0 1 1 * *", ctx => { - // do some processing +Application.Schedule("send-reminder").Cron("0 1 1 * *", async (ctx) => { + // do some processing }); Application.Run(); @@ -41,13 +41,13 @@ Application.Run(); using Application = Nitric.Sdk.Nitric; // every 15 minutes -Application.Schedule("check for updates").Cron("0/15 * * * *", ctx => { - Console.WriteLine("checking for updates"); +Application.Schedule("check for updates").Cron("0/15 * * * *", async (ctx) => { + Console.WriteLine("checking for updates"); }); // at 1:00 am on the 1st of every month -Application.Schedules("delete stale data").Cron("0 1 1 * *", ctx => { - Console.WriteLine("clearing stale data"); +Application.Schedules("delete stale data").Cron("0 1 1 * *", async (ctx) => { + Console.WriteLine("clearing stale data"); }); Application.Run(); diff --git a/docs/reference/csharp/schedule/schedule-every.mdx b/docs/reference/csharp/schedule/schedule-every.mdx index a90637243..183b445c4 100644 --- a/docs/reference/csharp/schedule/schedule-every.mdx +++ b/docs/reference/csharp/schedule/schedule-every.mdx @@ -9,10 +9,10 @@ Sets the frequency and one or many handlers to be triggered. ```csharp using Application = Nitric.Sdk.Nitric; -Application.Schedule("send-reminder").Every("3 hours", context => +Application.Schedule("send-reminder").Every("3 hours", async (ctx) => { - // do some processing - return context; + // do some processing + return ctx; }); Application.Run(); @@ -42,10 +42,10 @@ Application.Run(); ```csharp using Application = Nitric.Sdk.Nitric; -Application.Schedule("send-reminder").Every("3 minutes", context => +Application.Schedule("send-reminder").Every("3 minutes", async (ctx) => { - // do some processing - return context; + // do some processing + return ctx; }); Application.Run(); @@ -53,27 +53,40 @@ Application.Run(); ### Create a Schedule with multiple middleware/handlers -```csharp +```csharp title:Middlewares.cs using System; +using System.Threading.Tasks; using Nitric.Sdk.Service; -using Application = Nitric.Sdk.Nitric; -// Create a middleware to handle report generation -private IntervalContext GenerateReport(IntervalContext ctx, Func next) +namespace Common; + +class Middlewares { + // Create a middleware to handle report generation + public static async Task GenerateReport(IntervalContext ctx, Func> next) + { + Console.WriteLine("generate report"); // Code to generate a report - return next(ctx); -} + return await next(ctx); + } + + // Create a middleware to handle notifications + public static async Task SendNotification(IntervalContext ctx, Func> next) + { + Console.WriteLine("sending notification"); -// Create a middleware to handle notifications -private IntervalContext SendNotification(IntervalContext ctx, Func next) -{ // Code to send a notification - return next(ctx); + return await next(ctx); + } } +``` + +```csharp title:Application.cs +using Application = Nitric.Sdk.Nitric; +using Common; // Create a schedule that runs every 7 days -Application.Schedule("send-reminder").Every("7 days", GenerateReport, SendNotification); +Application.Schedule("send-reminder").Every("7 days", Middlewares.GenerateReport, Middlewares.SendNotification); Application.Run(); ``` diff --git a/docs/reference/csharp/schedule/schedule.mdx b/docs/reference/csharp/schedule/schedule.mdx index d86fe4ba7..04aa2e272 100644 --- a/docs/reference/csharp/schedule/schedule.mdx +++ b/docs/reference/csharp/schedule/schedule.mdx @@ -9,10 +9,10 @@ Creates a new Schedule to run a function on a defined frequency. ```csharp using Application = Nitric.Sdk.Nitric; -Application.Schedule("send-reminder").Every("3 hours", context => +Application.Schedule("send-reminder").Every("3 hours", async (ctx) => { // do some processing - return context; + return ctx; }); Application.Run(); @@ -35,24 +35,24 @@ Application.Run(); using Application = Nitric.Sdk.Nitric; // Create a schedule that runs every 3 minutes -Application.Schedule("send-reminder").Every("3 minutes", context => +Application.Schedule("send-reminder").Every("3 minutes", async (ctx) => { // do some processing - return context; + return ctx; }); // Create a schedule that runs every 3 hours -Application.Schedule("send-reminder").Every("3 hours", context => +Application.Schedule("send-reminder").Every("3 hours", async (ctx) => { // do some processing - return context; + return ctx; }); // Create a schedule that runs every 3 days -Application.Schedule("send-reminder").Every("3 days", context => +Application.Schedule("send-reminder").Every("3 days", async (ctx) => { // do some processing - return context; + return ctx; }); Application.Run(); @@ -64,10 +64,10 @@ Application.Run(); using Application = Nitric.Sdk.Nitric; // Create a schedule that runs every 3 minutes -Application.Schedule("send-reminder").Cron("3 * * * *", context => +Application.Schedule("send-reminder").Cron("3 * * * *", async (ctx) => { // do some processing - return context; + return ctx; }); Application.Run(); diff --git a/docs/reference/csharp/storage/bucket-file-downloadurl.mdx b/docs/reference/csharp/storage/bucket-file-downloadurl.mdx index b40b3612e..3e4fa68b9 100644 --- a/docs/reference/csharp/storage/bucket-file-downloadurl.mdx +++ b/docs/reference/csharp/storage/bucket-file-downloadurl.mdx @@ -61,13 +61,13 @@ var images = Application.Bucket("images").Allow(BucketPermission.Read); var mainApi = Application.Api("main"); mainApi.Get("/images/:id", context => { - var id = context.Req.PathParams["id"]; - var signedUrl = images.File(id).GetDownloadUrl(); + var id = context.Req.PathParams["id"]; + var signedUrl = images.File(id).GetDownloadUrl(); - context.Res.Status = 303; - context.Res.Headers["Location"] = new string[] { signedUrl }; + context.Res.Status = 303; + context.Res.Headers["Location"] = new string[] { signedUrl }; - return context; + return context; }); Application.Run(); diff --git a/docs/reference/csharp/storage/bucket-on.mdx b/docs/reference/csharp/storage/bucket-on.mdx index a61f2de9e..66c3b7399 100644 --- a/docs/reference/csharp/storage/bucket-on.mdx +++ b/docs/reference/csharp/storage/bucket-on.mdx @@ -22,25 +22,25 @@ var assets = Application.Bucket("assets"); var accessibleAssets = Application.Bucket("assets").Allow(BucketPermission.Read); // The request will contain the name of the file `Key` and the type of event `NotificationType` -assets.On(BlobEventType.Delete, "*", context => { - Console.WriteLine("A file named " + context.Req.Key + "was deleted"); +assets.On(BlobEventType.Delete, "*", async (ctx) => { + Console.WriteLine("A file named " + ctx.Req.Key + "was deleted"); - return context; + return ctx; }); -assets.On(BlobEventType.Write, "/images/cat", context => { +assets.On(BlobEventType.Write, "/images/cat", async (ctx) => { Console.WriteLine("A cat image was written"); - return context; + return ctx; }); // If `.On()` is called with a permissioned bucket, a file reference will also be provided with the request -accessibleAssets.On(BlobEventType.Write, "/images/dog", context => { - var dogImage = accessibleAssets.File(context.Req.Key).Read(); +accessibleAssets.On(BlobEventType.Write, "/images/dog", async (ctx) => { + var dogImage = accessibleAssets.File(ctx.Req.Key).Read(); Console.WriteLine(dogImage.ToString()); - return context; + return ctx; }); Application.Run(); diff --git a/docs/reference/csharp/topic/topic-subscribe.mdx b/docs/reference/csharp/topic/topic-subscribe.mdx index 02cb9a331..c5c3498f0 100644 --- a/docs/reference/csharp/topic/topic-subscribe.mdx +++ b/docs/reference/csharp/topic/topic-subscribe.mdx @@ -23,7 +23,7 @@ class EventUpdate var updates = Application.Topic("updates"); -updates.Subscribe(ctx => { +updates.Subscribe(async (ctx) => { Console.WriteLine(ctx.Req.Message); return ctx; @@ -59,7 +59,7 @@ class EventUpdate var updates = Application.Topic("updates"); -updates.Subscribe(ctx => { +updates.Subscribe(async (ctx) => { Console.WriteLine(ctx.Req.Message); return ctx; @@ -81,7 +81,7 @@ class EventUpdate var updates = Application.Topic("updates"); -updates.Subscribe((ctx, next) => +updates.Subscribe(async (ctx, next) => { // Validate request if (invalidRequest(ctx)) @@ -89,7 +89,7 @@ updates.Subscribe((ctx, next) => return ctx; } return next(ctx); - }, (ctx, next) => { + }, async (ctx, next) => { // Handle request return next(ctx); } diff --git a/docs/reference/csharp/websocket/connection-close.mdx b/docs/reference/csharp/websocket/connection-close.mdx index e537ba9d2..a24d9fab0 100644 --- a/docs/reference/csharp/websocket/connection-close.mdx +++ b/docs/reference/csharp/websocket/connection-close.mdx @@ -37,7 +37,7 @@ class WebsocketMessage var websocket = Application.Websocket("public"); // Broadcast message to all the registered websocket connections -websocket.On(WebsocketEventType.Message, ctx => { +websocket.On(WebsocketEventType.Message, async (ctx) => { var message = ctx.Req.Message(); if (message.Status == "close") diff --git a/docs/reference/csharp/websocket/connection-send.mdx b/docs/reference/csharp/websocket/connection-send.mdx index 88931e3ed..c9f38f69f 100644 --- a/docs/reference/csharp/websocket/connection-send.mdx +++ b/docs/reference/csharp/websocket/connection-send.mdx @@ -51,32 +51,32 @@ class OpenConnection var websocket = Application.Websocket("public"); var connections = Application.KV("connections").Allow( - KeyValueStorePermission.Set, KeyValueStorePermission.Get, KeyValueStorePermission.Delete + KeyValueStorePermission.Set, KeyValueStorePermission.Get, KeyValueStorePermission.Delete ); -websocket.On(WebsocketEventType.Connected, ctx => +websocket.On(WebsocketEventType.Connected, async (ctx) => { - connections.Set(ctx.Req.ConnectionId, new OpenConnection { Id = ctx.Req.ConnectionId }); - return ctx; + connections.Set(ctx.Req.ConnectionId, new OpenConnection { Id = ctx.Req.ConnectionId }); + return ctx; }); -websocket.On(WebsocketEventType.Disconnected, ctx => +websocket.On(WebsocketEventType.Disconnected, async (ctx) => { - connections.Delete(ctx.Req.ConnectionId); - return ctx; + connections.Delete(ctx.Req.ConnectionId); + return ctx; }); -websocket.On(WebsocketEventType.Message, ctx => +websocket.On(WebsocketEventType.Message, async (ctx) => { - var keys = connections.Keys(); + var keys = connections.Keys(); - while (keys.MoveNext()) - { - var message = ctx.Req.Message(); - websocket.Connection(keys.Current).SendMessage(message); - } + while (keys.MoveNext()) + { + var message = ctx.Req.Message(); + websocket.Connection(keys.Current).SendMessage(message); + } - return ctx; + return ctx; }); Application.Run(); diff --git a/docs/reference/csharp/websocket/websocket-on.mdx b/docs/reference/csharp/websocket/websocket-on.mdx index 170df73ff..f3785d622 100644 --- a/docs/reference/csharp/websocket/websocket-on.mdx +++ b/docs/reference/csharp/websocket/websocket-on.mdx @@ -54,7 +54,7 @@ Application.Run(); Messages can be read as literal strings using `ctx.Req.Message()`. ```csharp -websocket.On(WebsocketEventType.Message, ctx => { +websocket.On(WebsocketEventType.Message, async (ctx) => { var message = ctx.Req.Message(); Console.WriteLine($"New Message from {ctx.Req.ConnectionId}: {message}"); @@ -72,7 +72,7 @@ class EventUpdate public string Content { get; set; } } -websocket.On(WebsocketEventType.Message, ctx => { +websocket.On(WebsocketEventType.Message, async (ctx) => { var message = ctx.Req.Message(); Console.WriteLine($"Status: {message.Status}, Message: {message.Content}") @@ -101,13 +101,13 @@ var connections = Application.KV("connections").Allow( KeyValueStorePermission.Set, KeyValueStorePermission.Get, KeyValueStorePermission.Delete ); -websocket.On(WebsocketEventType.Connected, ctx => +websocket.On(WebsocketEventType.Connected, async (ctx) => { connections.Set(ctx.Req.ConnectionId, new OpenConnection { Id = ctx.Req.ConnectionId }); return ctx; }); -websocket.On(WebsocketEventType.Disconnected, ctx => +websocket.On(WebsocketEventType.Disconnected, async (ctx) => { connections.Delete(ctx.Req.ConnectionId); return ctx; @@ -119,24 +119,22 @@ Application.Run(); ### Chain functions as a single method handler ```csharp -using Nitric.Sdk.Service; using Application = Nitric.Sdk.Nitric; - -private WebsocketContext ValidateRequest(WebsocketContext ctx, Func next) -{ - // Validate Request - return next(ctx); -} - -private WebsocketContext HandleRequest(WebsocketContext ctx, Func next) -{ - // Handle Request - return next(ctx); -} +using Nitric.Sdk.Service; var websocket = Application.Websocket("public"); -websocket.On(WebsocketEventType.Message, ValidateRequest, HandleRequest); +websocket.On(WebsocketEventType.Message, async (ctx, next) => +{ + // Validate Request + Console.WriteLine("Validate Request"); + return await next(ctx); +}, async (ctx, next) => +{ + // Handle Request + Console.WriteLine("Handle Request"); + return await next(ctx); +}); Application.Run(); ```