Handle
API that handles HTTPHandle
API is needed.
This page describes the built-in Handle
APIHandle
class.Main
methodGET
, POST
, PUT
, DELETE
and PATCH
can be caught by methods with the same name in the Handle
class.{?}
. This indicates that there is a fragment of dynamic data in the URI. The type of the data is determined by the code delegate that follows.string name
. This means that the parameter will be parsed as a string, for example: /hello/albert
, /hello/anna
. To accept an integer parameter, simply change the lambda parameter type./squared?123
and /squared?-4321
/serialnumbers/4534123
, /itemid/34321
Self.GET
variant, which takes database class instance as a second parameter:CUSTOM
verb in the Handle
class makes it possible to register other HTTP methods or even catch all methods and URIs.Request
ObjectRequest
parameter can be declared together with the enumerated parameters. It encapsulates the entire request.Headers[String]
accessor on a Request
object (same as for the Response
object):Cookies
as a list of strings "name=value" (same as for Response object):GetClientIpAddress()
on the Request
object.HandlerAppName
property to find out which application the request belongs to. This might be useful when working with request filters.Handle
interface) and calling handlers (using the Self
interface), one can supply last HandlerOptions
parameter, which specifies certain options for handler calls or registration. Here are the notable handler options:SkipRequestFilters
: used to declare a handler for which request filters will not be applied.SkipResponsetFilters
: used to declare a handler for which response filters will not be applied.SkipHandlersPolicy
: If the database flag "EnforceURINamespaces" is set to True, all application handlers are required to start with application name. In this case SkipHandlersPolicy
flag allows to register any URI handler.SelfOnly
: registered handler is going to be accessible only inside codehost using Self
interface. SelfOnly
handlers are not registered in gateway, in comparison with normal handlers.sccode
instance) using Node
and X
. Internal requests and handlers can be nested and create a call hierarchy. Sometimes its useful to cast a specific exception deep down in the hierarchy and handle it on another level or let the system handle it (for example by automatically sending the response). This can be achieved using ResponseException
exception object. The following example illustrates this concept:/exc3
constructs and throws an instance of ResponseException
exception. Handler /exc2
catches the exception, modifies some data and re-throws the exception. Eventually, the ResponseException
is caught by outer system handler and ResponseObject
is automatically sent on the original Request req
. Note that ResponseException
mechanisms are working only within one user application (they are simple C# exceptions).ResponseException
by either constructor or UserObject
property.Handle.UnregisterHttpHandler
method.Attempt to HTTP upload of more than 1048576 bytes. Closing socket connection
MaximumReceiveContentLength
in %userprofile%\Documents\Starcounter\Personal\scnetworkgateway.xml
.FileUploadPage
(code-behind, HTML) in the sample app KitchenSink.Handle.GET
, a Response
object should be returned.Response
class has many implicit cast operators to make this convenient.string
(mime type will be text/plain or text/html depending on the request Accept
header)byte[]
(mime type will be the first one in the Accept
header)Json
object (mime type will be application/json
)int
, uint
, decimal
, bool
, double
, long
, ulong
, DateTime
returns a Javascript literal (JSON)null
(no content)Response
object, you have the choice of setting the body to a byte[]
, a string
.Json
class, the mime type will application/json
and the body will contain a JSON string.Accept
header of the request. If the request prioritizes text/html
or application\json
, the HTTP response will use this type accordingly. If no Accept header was provided, the mime-type text/plain
will be used.Response
object:StatusCode
equal to the integer and default status description.Not found
status code.Response
object, the body can be set to a byte[]
, string
, or Stream
.
As Starcounter schedules threads in a optimized way, it is recommended to allow Starcounter to handle streaming. This is done by assigning the stream
to the Response
object and then returning the response, relying on Starcounter to read the stream and send the network traffic on its own accord. Streamed object should allow getting length of the stream in bytes (Length
property).stream
object is automatically closed when the stream data is sent completely or if the connection is dropped.Handle.ResolveStaticResource
which takes a resource URI and incoming request and returns a response representing this resource. Response however can be a 404, so to return a "nice" 404 page user has to do the following code, for example:Response
object cannot be returned immediately in the handler. One reason could be the access of third party resources or doing long-running jobs. By returning HandlerStatus.Handled
in the handler, the user indicates that the response will be returned later or that it already has been returned another way.StatusCode
: 404, 501, etcStatusDescription
: "Not Found", "Service Unavailable", etcContentType
: "text/html", "application/json", etcContentEncoding
: "gzip", etcCookies
: a list of entries like "MyCookie1=123", "MyCookie2=456", etcBody
: "Here is response body!", etcBodyBytes
: Byte[] bodyBytes = { 1, 2, 3, 4, 5};, etcConnFlags
: used to manipulate the connection with client.Response.ConnectionFlags
values are available:Response.ConnectionFlags.DisconnectImmediately
: immediately disconnects the associated connection with endpoint without sending any data first.Response.ConnectionFlags.DisconnectAfterSend
: first sends given message to endpoint and then closes the corresponding connection.Response
object is straightforward using the Headers
property:StatusCode
default value is 200StatusDescription
default value is "OK"Server
default value is Server: Starcounter/#starcounter_version (Windows)
, for example: Server: Starcounter/2.3.1.7779 (Windows)
.Headers
accessor on the Response
or Request
object:Self.GET
, it's necessary to be able to set properties not on the current response, but directly on corresponding, not yet available, outgoing responses, like headers, status codes, messages, and cookies. To achieve that, the following static methods are available from the class Handle
: