From Bistro
Jump to: navigation, search


Bistro configuration settings are centralized to the web.config, and mostly pertain to the bootstrapping process.

Modules and Handlers

The bistro runtime integrates with the ASP.NET pipeline via a module and a handler. To do so, you need the following:

  • For Cassini (VS Development Server) and IIS 6 and 5.1

in configuration/system.web/httpModules, add the following line <source lang="xml"> <add type="Bistro.Http.Module, Bistro.Core" name="BistroModule" /> </source>

Something to remember
IIS 6 and 5.1 don't handle wild-cards gracefully, and require additional configuration. That can be found here.
  • For IIS 7

In configuration/system.webServer/modules, set the modules.runAllManagedModulesForAllRequests attribute to true, and add the following line <source lang="xml"> <add name="BistroModule" type="Bistro.Http.Module, Bistro.Core" preCondition="" /> </source>

In configuration/system.webServer/handlers, add the following line <source lang="xml"> <add name="BistroHandler" path="*" verb="*" type="Bistro.Http.Module, Bistro.Core" modules="BistroModule" scriptProcessor="" resourceType="Either" requireAccess="Read" preCondition="" /> </source>

The <bistro> configuration element

In most scenarios, the default configuration of the runtime will suffice. In the scenarios where that is not the case, the bistro configuration section can be added to the web.config:

  • In the configuration/configSections element of the web.config, add

<source lang="xml"> <section name="bistro" type="Bistro.Configuration.SectionHandler, Bistro.Core" /> </source>

The bistro element can now be added to the configuration section of the web.config

Url recognition rules

The allowed-extensions and <ignored-directories> elements let the user modify the default url processing behavior of the bistro runtime. By default, only extension-less urls, across all directories are treated as bistro bind-points. To modify this behavior

  • Use the <allowed-extensions> element to override what url extensions are treated as bind-points:

<source lang="xml"> <allowed-extensions> <clear/> <add name="empty" value="" /> <add name="django" value=".django" /> </allowed-extensions> </source>

Note that specifying any elements in this list automatically turns off the default no-extension mapping.
If you still desire that functionality, you will need to re-enable it with an explicit allowed-extension of the empty string (see example above)


  • Extensions specified in this list may start with a ".".
  • Extensions containing a "." (such as "") will be ignored
  • Extensions are not case sensitive
  • A wild-card may be specified as .*. If present, this will instruct the runtime to intercept all requests. This should only be used in conjunction with an ignored directory, to prevent static content requests from being treated as bistro bind points.

Something to remember
You can use this configuration section to specify a bistro-specific url extension, and configure your application to run on IIS6 or 5.1 by mapping a handler to your extension. You will, however, need to modify your bind rules to include whatever extension you specify.
  • Use the <ignored-directories> element to specify what directories should not be treated as bind points. This instructs the bistro runtime to ignore all requests that start with the specified path.

<source lang="xml"> <ignored-directories> <add name="Images" value="content/images" /> </ignored-directories> </source>

Note that incoming requests will be tested for the ignored directory list from the application root
This means that given, requests for /virtualdir/content/images will be ignored, but requests for /virtualdir/different/content/images will be treated as a bistro request.


  • Directory specifications may start and end with a slash ('/')
  • Direction of separators does not matter ('/' will work same as '\')
  • Directory comparison is not case sensitive

Component definitions

Attributes on the <bistro> element let the user specify the following components:

To modify these components, you need to specify the configuration options on the bistro element:

<source lang="xml"> <bistro application="..." dispatcher-factory="..." handler-factory="..." manager-factory="..." logger-factory="..." format-manager-factory="..." /> </source>

Note that all components are optional, and will revert to system defaults if omitted, or if the runtime is unable to load the class. Watch for warning messages in the log if issues arise.

Formatting and Serialization (new in

Object graph serialization and deserialization is supported through the IWebFormatter interface. Formatters implementing this interface can be specified using web-formatters and default-formatter properties, as follows:

  • Use the <web-formatters> element to specify a list of available formatters:

<source lang="xml"> <web-formatters> <clear/> <add name="Json" value="Bistro.Extensions.Format.Json.JsonFormatter, Bistro.Extensions" /> <add name="Xml" value="Bistro.Extensions.Format.Xml.XmlFormatter, Bistro.Extensions" /> </web-formatters> </source>

  • Use the default-formatter attribute to denote which formatter will be used to serialize object graphs without explicit serialization advice:

<source lang="xml"> <bistro default-formatter="Json" /> </source>