Skip to content

annotations.md

Latest commit

 

History

History
226 lines (166 loc) · 7.98 KB

annotations.md

File metadata and controls

226 lines (166 loc) · 7.98 KB
Raw

Annotations Guide

Tags

for tag1, tag2, tag3 [, ...]
tag tag1, tag2, tag3 [, ...]
tags tag1, tag2, tag3 [, ...]

All annotations in lines below this line apply only to tags in the argument list.

Disabled

disabled
disabled [ tag1, tag2, tag3 [, ...] ]

The endpoint is disabled. Optional tag list disabled only for tags in the argument list.

Enabled

enabled
enabled [ tag1, tag2, tag3 [, ...] ]

The endpoint is enabled. Optional tag list enabled only for tags in the argument list.

HTTP

HTTP 
HTTP [ GET | POST | PUT | DELETE ]
HTTP [ GET | POST | PUT | DELETE ] path

HTTP settings:

  • Use HTTP annotation to enable when running in CommentsMode.OnlyWithHttpTag option.
  • Change the HTTP method with the optional second argument.
  • Change the HTTP path with the optional third argument.

RequestParamType

requestparamtype [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
paramtype  [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
request_param_type  [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
param_type  [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
request-param-type  [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
param-type  [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]

Set how request parameters are sent - query string or JSON body.

RequiresAuthorization

requiresauthorization
authorize
requires_authorization
requires-authorization
requiresauthorization [ role1, role2, role2 [, ...] ]
authorize [ role1, role2, role2 [, ...] ]
requires_authorization [ role1, role2, role2 [, ...] ]
requires-authorization [ role1, role2, role2 [, ...] ]

Require authorization for this endpoint.

  • If the user is not authorized and authorization is required, the endpoint will return the status code 401 Unauthorized.
  • If the user is authorized but not in any of the roles required by the authorization, the endpoint will return the status code 403 Forbidden.

AllowAnonymous

allowanonymous
allow_anonymous
allow-anonymous
anonymous
anon

Allow anonymous access with no authorization to this endpoint.

CommandTimeout

commandtimeout seconds
command_timeout seconds
command-timeout seconds
timeout seconds

Set the command execution timeout in seconds.

RequestHeadersMode

requestheadersmode [ ignore | context | parameter ]
request_headers_mode [ ignore | context | parameter ]
request-headers-mode [ ignore | context | parameter ]
requestheaders [ ignore | context | parameter ]
request_headers [ ignore | context | parameter ]
request-headers [ ignore | context | parameter ]

Set how request parameters are handled:

  • Ignore: do not send request headers.
  • Context: Request headers are set as the session variable under request.headers key.
  • Parameter: Request headers are set as a default parameter defined with RequestHeadersParameterName.

RequestHeadersParameterName

requestheadersparametername name
requestheadersparamname name
request_headers_parameter_name name
request_headers_param_name name
request-headers-parameter-name name
request-headers-param-name name

When RequestHeadersMode is set to send request headers as a parameter, set the existing parameter name. The default is headers.

BodyParameterName

bodyparametername name
body-parameter-name name
body_parameter_name name
bodyparamname name
body-param-name name
body_param_name name

Set the name of the existing parameter which is sent as body content. When the BodyParameterName is set, all other parameters are sent by the query string.

ResponseNullHandling

responsenullhandling [ emptystring | nullliteral | nocontent ]
response_null_handling [ emptystring | nullliteral | nocontent ]
response-null-handling [ emptystring | nullliteral | nocontent ]

Sets the response NULL handling option for a single function results other than JSON (text, number, etc...):

  • EmptyString: Empty content response. This is the default.
  • NullLiteral: Content is the null string.
  • NoContent: Response is HTTP 204 No Content status response code.

QueryStringNullHandling

querystringnullhandling [ emptystring | nullliteral | ignore ]
query_string_null_handling [ emptystring | nullliteral | ignore ]
query-string-null-handling [ emptystring | nullliteral | ignore ]

Sets the response NULL handling option for the query string parameters:

  • EmptyString: Empty query string is interpreted as the NULL value parameter.
  • NullLiteral: The literal value null (case insensitive) in the query string is interpreted as the NULL value parameter.
  • Ignore: Doesn't handle NULL parameters in query strings. This is the default.

Headers

key: value

Any line containing a: character is interpreted as the request header key and value where the key is the left side and the value is the right side string. For example: Content-Type: text/html

Login

login
signin

This annotation will transform the routine into the authentication endpoint that performs the sign-in operation.

Note: to be able to use this feature authentication needs to be enabled and configured in your application, for example:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication().AddCookie();

The login-enabled endpoints must return a named record.

The program will result in the ArgumentException exception if the login-enabled routine is either of these:

  • void
  • returns simple value
  • returns set of record unnamed records

The login operation will be interpreted as an unsuccessful login attempt and return the status code 401 Unauthorized without creating a user identity if either:

  • The routine returns an empty record.
  • The returned record includes a status column, and the value of he status column name is:
    • False for boolean types.
    • Not 200 for numeric types.

The login operation will be interpreted as a successful login attempt and return the status code 200 OK with creating a new user identity if either:

  • The routine returns a record without status status column.
  • The returned record includes a status column, and the value of the status column name is:
    • True for boolean types.
    • 200 for numeric types.

To authorize a different authorization scheme, return a schema column name with the value of that schema.

Any other records will be set as new claims for the created user identity on successful login, where:

Logout

logout
signout

This annotation will transform the routine into the endpoint that performs the logout or the sign-out operation.

If the routine doesn't return any data, the default authorization scheme is signed out. Any values returned will be interpreted as scheme names (converted to string) to sign out.