Routing is the process of mapping current request to a controller stored-procedure that will provide its response.

In Chameleon routes are defined in a table named chameleon.Routes. Routing is the first step in serving a request. This is done by a Chameleon middleware named RoutingMiddleware. It uses a CLR stored-procedure named chm.FindRoute for this purpose.

chm.FindRoute UDF performs two main jobs:

1. First, it looks for a route in chameleon.Routes table that matches current request (based on its URL and its method).
2. Second, it determines name of a stored-procedure that will act as a Controller (the C part in in MVC terminology) to provide the response of current request.

If RoutingMiddleware finds a route, it selects list of values for the route parameters (if the route has any parameter).

In this section, different features of RoutingMiddleware is explained.

• Defining routes
• Route Structure
• Parameters
• System Parameters
• Optional Parameters
• Processing Order
• Disable/Enable
• Defaults
• Area
• Parameters Constraints
• Http Method Constraint
• Http Method Mapping
  • Global Mapping
  • Local Mapping
  • Disable http mapping locally
• Catch-All routes
• Name of controller SPROC
• Manual SPROC name
• Related Settings

A route is a pattern that can cover one or more URL. It is defined like a relative path using slash separator.

			  /a/b/c
			

In order for a route to match a given URL, its segments or fragments -the parts between slash- should match their equivalent segment in the URL.

The example above matches a URL whose path is exactly as /a/b/c. No path with less or greater number of segments like /a, /a/b or /a/b/c/d will match this route.

As it was stated earlier, routes are defined in a table named chameleon.Routes. Structure or schema of this table is as follows:

Each segment of a route is defined as a fixed value or a parameter.

Fixed values must match exactly with their equivalent segment in order to match as we saw in previous section. The comparison is performed case-insensitively. So, /product matches /Product and /PRODUCT as well.

Parameters are merely a placeholder for an equivalent segment in the given URL and span multiple values.

Route parameters are defined using brace characters as in {controller}. They match any value in the equivalent segment in the given URL.

Example:

  /product/{action}

The above route matches any URL that has two segments and starts with /product like /product/list, /product/show, /product/add but not /product since it has only one segment or /product/edit/123 since it has three segments.

RoutingMiddleware processes routes in chameleon.Routes table based on their routeOrder column (in ascending order).

Example:

If given URL is /product/list, the second route is matched, since it has more priority over /{controller}/{action?} due to its routeOrder.

Each route in chameleon.Routes table has an isActive column with bit data type. RoutingMiddleware assumes only those routes whose isActive equals 1. This enables us to dynamically disable/enable routes.

Defaults

Using the defaults column in chameleon.Routes we can specify default values for route parameters in case the parameter is missing in the URL. The defaults value should be in JSON format.

Example:

Although action parameter in the above route is not optional, the route matches a /product URL, since there is a default value for action parameter in the defaults column.

AS stated earlier in System Parameters section, there is a system parameter named area by which we can define the same route in different areas of our application. If we use area parameter directly in the route (somewhere inside route as {area}) or indirectly (in defaults field), the value of the area parameter will be added to the name of the stored-procedure that RoutingMiddleware will determine after matching the route.

Example 1: explicit area

  /{area}/{controller}/{action}/{id?}

The above route will match /admin/product/add, /user/product/favorite but not /product/list.

Example 2: implicit area

The above route matches /api/product/add but not /admin/product/add.

It is possible to define constraints for route parameters using the constraints field. The value of this field should be a JSON object whose keys are route parameter names and their values are constraints that are defined for each route.

RoutingMiddleware supports two types of route parameter constraints:

• Regex: we can specify a regular expression for the route parameter.
• UDF: we can specify name of a User-Defined-Function that will check whether provided value for the route parameter matches its condition. The signature of the UDF should correspond to the following function:

  CREATE or ALTER FUNCTION dbo.RouteParameterConstraint
(
	@context_id int,
	@value      nvarchar(4000)
)
RETURNS bit
AS
...

That is, it should have two parameters:

• @context_id of int type
• @value of nvarchar(4000) type

It should also return bit (1 as true or 0 as false).

Upon invocation, RoutingMiddleware will pass current context-id to the first parameter and value of the route parameter for the second parameter.

If the UDF returns 1, it is assumed that route parameter satisfies its constraint, otherwise it does not and hence, the route will not match current URL.

Example 1: Specifying a regular expression

The above route matches /product/show/123 but will not match /product/list/all since all does not match ^\d+$ regular expression that is defined for id parameter.

Example 2: Specifying a UDF

Suppose we have the following UDF:

  create or alter function dbo.isValidAction
(
	@context_id int,
	@value      nvarchar(4000)
) returns bit
as
begin
	return case when @value in ('index', 'list', 'show') then 1 else 0 end
end

We have also the following route in chameleon.Routes table:

The above route matches /product/show but will not match /product/add since dbo.isValidAction will not return 1 for add.

RoutingMiddleware provides another option for using default value for action parameter when it is not specified in the route, no value was found for it in the URL or not default value for it is specified in defaults field. We can ask RoutingMiddleware to use the http method -or a mapping of http method- as the default value for action parameter. This is primary useful in providing REST apis, but it can also be used in other cases as well.

Http method mapping can be done at two levels: global and local.

One scenario regarding routing is having the ability to define a catch-all route i.e. a route that is able to catch any URL. This is possible using * character at the beginnng of a route parameter. If a route parameter stars with *, it can match any segments from that segments onward it equals to.

Example:

  route = /{controller}/{action}/{rest*}

The above route matches any URL with 2 and more segments.

Mateched routes example:

• /product/list: controller = product, action = list, rest = '/'
• /product/edit/123: controller = product, action = edit, rest = '/123'
• /product/books/tags/csharp: controller = product, action = books, rest = '/tags/csharp'
• /blog/john-doe/2022/08: controller = blog, action = john-doe, rest = '/2022/08'

The second job of RoutingMiddleware is determining name of controller SPROC. In this step, system route parameters play a primary role. RoutingMiddleware uses the following format or formula in order to determine name of controller stored-procedure.

Notes:

• The default value of {schema} is dbo. This can be changed using Chameleon.Routing.SprocDefaultSchema setting.
• The default value of {prefix} is USP. This can be changed using Chameleon.Routing.SprocPrefix setting.
• Between the parametric parts a dash or - character is used. This can also be changed using Chameleon.Routing.SprocPartSeparator setting.

Example:

Sample URLs and generated controller SPROC name:

We can override RoutingMiddleware sproc name determination in two ways:

1. Static Name: Specifying name of controller SPROC explicitly using Sproc field in a route. This way the specified sproc will handle all URLs that match the route.
2. Dynamic Name: Specifying name of a get-sproc UDF that will return name of controller SPROC. This way name of controller sproc will be dynamic. The name of get-sproc UDF can be specified in two ways:
   1. Global Chameleon.Routing.GetSproc setting.
   2. Local getSproc setting in route's settings field.

In the second method, name of the get-sproc UDF should only contain alphanumeric characters, dot , bracket or underline characters. The get-sproc UDF should have a single int parameter and return nvarchar. When the UDF is called, current context-id is passed to the UDF.

Example:

  CREATE OR ALTER FUNCTION dbo.GetRouteSproc
(
	@context_id int
)
RETURNS NVARCHAR(500)
AS
BEGIN
	declare @result nvarchar(500)
	declare @area nvarchar(500)
	declare @controller nvarchar(500)
	declare @action nvarchar(500)
	declare @method nvarchar(500)

	select @method = [method] from chameleon._requestUrl where [context_id] = @context_id
	set @method = '_' + isnull(@method, 'get')
	set @area = isnull('_' + chameleon.[Route.GetValue](@context_id, 'area', null), '')
	set @controller = isnull('_' + chameleon.[Route.GetValue](@context_id, 'controller', null), '')
	set @action = isnull('_' + chameleon.[Route.GetValue](@context_id, 'action', null), '')

	set @result = 'dbo.usp' + lower(@area) + lower(@controller) + lower(@action) + @method

	return @result
END

This get-sproc UDF makes area, controller, action parameters lowercase and adds http method to the end of sproc name. For a URL like /product/list that is requested with GET and POST method, the name of controller sproc will be dbo.usp_product_list_get and dbo.usp_product_list_post respectively.

[Chameleon.Routing.SprocPrefix]: string (default = USP)

Specifies default prefix of controller stored procedure. It will be added to the begining of the name of controller sproc.

[Chameleon.Routing.SprocDefaultSchema]: string (default = dbo)

Specifies default schema of controller stored procedure.

[Chameleon.Routing.SprocPartSeparator]: string (default =_)

Specifies default separator by which different parts of controller stored procedure will be concatenated with. Default is underline character.

[Chameleon.Routing.HttpMethodAsAction]: boolean (default = true)

This is a global setting that specifies whether HTTP methods should be used as action in case of action parameter is missing.

[Chameleon.Routing.HttpMethodMapping]: string

Specifies how http methods should be mapped to actions when action parameter is missing. Default value for this setting is as follows:

  { "GET":"get", "POST": "insert", "PUT": "update", "PATCH": "modify", "DELETE": "delete" }