Options
CodeBehind provides a dedicated options file located at code_behind/options.ini. This file contains various configuration options that allow developers to customize the framework's behavior without modifying the framework's source code.
The options file includes settings for View compilation, file paths, routing, Controllers, WebForms Core integration, WebSocket connections, Server-Sent Events (SSE), and other framework features.
The default options file in CodeBehind looks like this:
[CodeBehind-options] view_path=wwwroot move_view_from_wwwroot=true dll_path=wwwroot/bin move_dll_from_wwwroot_bin=true rewrite_aspx_file_to_directory=false access_aspx_file_after_rewrite=false ignore_default_after_rewrite=true start_trim_in_aspx_file=true inner_trim_in_aspx_file=true end_trim_in_aspx_file=true set_break_for_layout_page=true convert_cshtml_to_aspx=false show_minor_errors=false error_page_path=/error.aspx/{value} prevent_access_default_aspx=false default_role=guest web_forms_script_path=/script auto_create_web_forms_script=true recreate_web_forms_script_after_recompile=false use_default_controller=true default_controller=DefaultController use_segment_in_default_controller=true set_break_for_default_controller=true access_controller_by_lower_case=true just_access_controller_by_lower_case=true ignore_prefix_controller=. ignore_suffix_controller=. put_two_underlines_equal_to_dash_for_controller=false set_default_pages=true max_web_socket_connections_per_client=3 web_socket_buffer_size=4096 send_view_only_in_get_method=false ignore_layout_for_post_back=false set_text_html_content_type_for_post_back=true sse_interval=1000 max_sse_connections_per_client=3 In the following sections, we will examine these settings and explain how they can be used to customize CodeBehind applications.
View File Configuration
Change View Path
(view_path=wwwroot)
This setting specifies the directory in which CodeBehind stores and compiles View files (.aspx). Developers can move their View files out of the wwwroot directory and place them in a directory of their choice.
This is particularly useful when View files contain server-side code. Keeping these files outside the publicly accessible wwwroot directory helps prevent direct access to their source files and improves application security.
Operation location: View file compilation
Move Views from wwwroot
(move_view_from_wwwroot=true)
When enabled, this setting automatically moves all .aspx and .astx files from the wwwroot directory to the directory specified by view_path during recompilation.
This eliminates the need to manually relocate View files when changing the View directory.
Operation location: View file compilation
Rewrite ASPX File Paths as Directory Paths
(rewrite_aspx_file_to_directory=false)
One of the interesting features of CodeBehind is the ability to access ASPX files through directory-style URLs without their file extensions.
When this option is enabled, a URL that corresponds to an ASPX file can also be accessed using a path without the .aspx extension.
For example, the following file:
/page/about.aspx
Can also be accessed through:
/page/about
This feature provides cleaner URLs without requiring additional routing configuration.
Note: You can safely enable this option because the rewriting process does not introduce additional processing overhead.
Operation location: View file compilation
Allow Access to ASPX Files After Rewriting
(access_aspx_file_after_rewrite=false)
When rewrite_aspx_file_to_directory is enabled, this option determines whether the original ASPX file path remains accessible.
If enabled, both the extensionless URL and the original .aspx URL can be used to access the same View.
If disabled, access is limited to the rewritten directory-style URL.
Operation location: View file compilation
Ignore Default.aspx After Rewriting
(ignore_default_after_rewrite=true)
In CodeBehind, a file named Default.aspx is automatically recognized as the default View of its containing directory. Therefore, developers do not need to include its filename in the URL.
When ASPX-to-directory rewriting is enabled, this option determines how Default.aspx files are handled in the rewritten directory structure.
When enabled, Default.aspx is treated as the default View of the corresponding directory rather than allowing the Default path to be treated as a separate directory.
Operation location: View file compilation
Change DLL Path
(dll_path=wwwroot/bin)
This setting specifies the directory where CodeBehind stores and loads compiled DLL files.
Developers can move DLL files from the default wwwroot/bin directory to a directory of their choice. Keeping DLL files outside the publicly accessible wwwroot directory helps prevent direct access to compiled assemblies and improves application security.
Operation location: DLL compilation
Move DLLs from wwwroot/bin
(move_dll_from_wwwroot_bin=true)
When enabled, this setting automatically moves all DLL files from the wwwroot/bin directory to the directory specified by dll_path during recompilation.
This eliminates the need to manually move compiled DLL files when changing the DLL directory.
Operation location: DLL compilation
Whitespace Management During View Compilation
CodeBehind provides three options for automatically removing unnecessary whitespace from ASPX files during compilation.
These options make it possible to write cleaner and more readable View code without worrying about extra line breaks, tabs, or spaces affecting the resulting HTML.
Trim at the Beginning of ASPX Files
(start_trim_in_aspx_file=true)
When enabled, this option removes unnecessary line breaks, tabs, and spaces from the beginning of ASPX files during compilation.
This means you no longer need to place the DOCTYPE declaration or the opening HTML tag immediately after the Page directive. You can start writing them on the next line.
For example, instead of writing:
Standard syntax:
<%@ Page %><!DOCTYPE html> You can write:
<%@ Page %> <!DOCTYPE html> The same applies to Razor syntax:
@page <!DOCTYPE html> This makes View files easier to read and maintain.
Operation location: View file compilation
Trim Inside ASPX Files
(inner_trim_in_aspx_file=true)
When enabled, this option removes unnecessary line breaks following server-side code blocks during compilation.
This prevents unwanted blank lines from appearing between HTML elements in the resulting output.
For example, both Razor and standard syntax support server-side code blocks:
Razor syntax:
@{ code } Standard syntax:
<% code %> With this option enabled, unnecessary line breaks following these code blocks are removed.
Operation location: View file compilation
Trim at the End of ASPX Files
(end_trim_in_aspx_file=true)
When enabled, this option removes unnecessary line breaks, tabs, and spaces from the end of ASPX files during compilation.
This helps prevent unnecessary whitespace from being included in the compiled output.
Operation location: View file compilation
Prevent Direct Access to Layout Files
(set_break_for_layout_page=true)
When enabled, Layout files are automatically excluded from direct access. This means users cannot access these files directly through their URLs.
Layout files are intended to be used as part of the View composition process rather than executed as independent pages.
Operation location: View file compilation
Support the CSHTML Extension
(convert_cshtml_to_aspx=false)
CodeBehind provides an option to support .cshtml files. This allows developers to use the familiar CSHTML extension and take advantage of code highlighters that recognize Razor syntax.
When enabled, CSHTML files can contain both Razor syntax and standard CodeBehind syntax. During compilation, these files are converted into ASPX files.
For default pages, the filename must be Default.cshtml. Files named Index.cshtml, for example, will not automatically become the default page.
Important: CSHTML files should not be added to Visual Studio projects as compilation items. The reason is that, in addition to CodeBehind, the default .NET compilation process may also attempt to compile these files. This can cause compilation conflicts, unstable behavior, and potential security issues.
Also note that Visual Studio's default code highlighter may display unnecessary errors in CSHTML files that use CodeBehind-specific syntax.
Operation location: View file compilation
Show Minor Compilation Errors
(show_minor_errors=false)
When enabled, this option displays minor compilation issues that do not prevent successful compilation but indicate that the code could be improved or optimized.
These messages are written to the views_compile_error.log file in the code_behind directory.
This option is useful for identifying potential problems and improving the quality of View files without interrupting the compilation process.
Operation location: View file compilation
Error Handling and Default Pages
Configure the Error Page Path
(error_page_path=/error.aspx/{value})
The default CodeBehind template includes an error page. This option specifies the path used to display that page when an error occurs.
The default path contains a variable named {value}. CodeBehind replaces this variable with the corresponding error code.
For example:
/error.aspx/500
In this example, {value} is replaced with 500.
This allows developers to handle different types of errors through a single error page and customize the displayed content according to the error code.
For more information about configuring error pages, see the following tutorial:
Operation location: Every request
Prevent Direct Access to Default.aspx
(prevent_access_default_aspx=false)
In CodeBehind, a file named Default.aspx is automatically recognized as the default View of its containing directory.
For example, if a Default.aspx file exists in the root directory, accessing:
example.com
will execute:
example.com/Default.aspx
Similarly, if a Default.aspx file exists in the dir directory, accessing:
example.com/dir
will execute:
example.com/dir/Default.aspx
However, the original Default.aspx URL remains accessible by default.
When this option is enabled, direct access to the Default.aspx file path is disabled, while access to the directory itself remains available.
For example:
-
example.com/dir/Default.aspxwill not be accessible. -
example.com/dir/will remain accessible.
This helps prevent multiple URLs from accessing the same page, which can contribute to cleaner URL structures and better SEO.
Operation location: Every request
Set the Default User Role
(default_role=guest)
This option specifies the default role assigned to users in the application. Its default value is guest.
Developers can change this value to customize the default role used by CodeBehind.
WebForms Core Integration
WebFormsJS Script Path
(web_forms_script_path=/script)
This option specifies the directory path used for the WebFormsJS client-side script.
For example, with the default value:
web_forms_script_path=/script
The WebFormsJS file will be available at:
/script/web-forms.js
Developers can change this path to place the script in a different directory.
Automatically Create the WebFormsJS Script
(auto_create_web_forms_script=true)
When enabled, CodeBehind automatically creates the WebFormsJS file.
This eliminates the need to manually create or copy the client-side script into the project.
Recreate WebFormsJS After Recompilation
(recreate_web_forms_script_after_recompile=false)
When enabled, CodeBehind recreates the WebFormsJS file after each recompilation.
This is useful when the WebFormsJS script needs to be regenerated to reflect changes in the framework or its configuration.
Controller Configuration
Use the Default Controller
(use_default_controller=true)
When enabled, accessing the application's root URL causes the default Controller to execute.
This provides a convenient way to define the Controller responsible for handling requests to the root path.
Specify the Default Controller Name
(default_controller=DefaultController)
This option specifies the name of the Controller class used as the default Controller.
The default value is DefaultController.
Developers can change this value to use a different Controller class for the root path.
Enable Segments in the Default Controller
(use_segment_in_default_controller=true)
When enabled, the default Controller can access URL segments.
This allows developers to handle additional path information through the default Controller.
Note: If another Controller matching the requested route is found, that Controller will be executed instead of the default Controller.
Restrict the Default Controller to the Root Path
(set_break_for_default_controller=true)
When enabled, the default Controller is excluded from the list of Controllers used during route configuration.
As a result, the default Controller is executed only for requests to the root path, rather than being considered for other routes.
Allow Lowercase Controller Names in URLs
(access_controller_by_lower_case=true)
When enabled, Controller class names can be accessed through URLs using lowercase letters.
This provides greater flexibility when defining routes and accessing Controllers.
Allow Only Lowercase Controller Names in URLs
(just_access_controller_by_lower_case=true)
When enabled, Controller class names can only be accessed through lowercase URLs.
This option can be used to enforce a consistent lowercase URL structure.
Ignore a Prefix in Controller Names
(ignore_prefix_controller=.)
This option allows developers to exclude a specified prefix from the Controller name when generating its accessible URL.
For example, if the prefix Route is specified, a Controller named:
RouteContent
can be accessed through:
example.com/Content
This makes it possible to use naming conventions in Controller classes without including those prefixes in the URLs.
Ignore a Suffix in Controller Names
(ignore_suffix_controller=.)
Similar to the previous option, this setting allows developers to exclude a specified suffix from Controller names when generating their accessible URLs.
For example, if the suffix Controller is specified, a Controller named:
ContentController
can be accessed through:
example.com/Content
This is particularly useful when following naming conventions that require a common suffix for Controller classes.
Convert Double Underscores to Dashes in Controller Routes
(put_two_underlines_equal_to_dash_for_controller=false)
When enabled, this option treats two consecutive underscores in a Controller class name as a dash in its corresponding URL.
For example, a Controller named:
active__page
can be accessed through:
example.com/active-page
This provides an alternative way to create readable URLs from Controller class names.
Automatically Create Default Pages
(set_default_pages=true)
When enabled, CodeBehind automatically creates the default project template and its associated pages.
This makes it easier to initialize a new application without manually creating the initial files.
WebSocket and SSE Configuration
Maximum WebSocket Connections per Client
(max_web_socket_connections_per_client=3)
This setting determines the maximum number of simultaneous WebSocket connections allowed per client.
When the number of connection requests exceeds this limit, the oldest active WebSocket connection is terminated, and a new connection is established in its place.
This helps control the number of active connections maintained for each client.
WebSocket Buffer Size
(web_socket_buffer_size=4096)
This setting determines the size of the buffer used for WebSocket communication.
Choosing an appropriate buffer size is important. A buffer that is too large may consume unnecessary memory, while a buffer that is too small may limit the amount of data that can be handled efficiently.
The default value is 4096 bytes.
Send View Only for GET Requests
(send_view_only_in_get_method=false)
When enabled, this setting restricts View content delivery to GET requests.
For all other HTTP methods, including POST, PUT, and DELETE, the server does not include the View content in the response.
This helps prevent unnecessary View transmission during requests intended for data submission or modification.
Ignore Layout for Post-Back Requests
(ignore_layout_for_post_back=false)
When enabled, the server automatically excludes the Layout from the response whenever it detects a Post-Back request sent by WebFormsJS, identified by the Content-Type header.
This eliminates the need for developers to manually check whether a request originates from WebFormsJS and conditionally disable Layout rendering.
Set HTML Content Type for Post-Back Responses
(set_text_html_content_type_for_post_back=true)
When enabled, this setting instructs CodeBehind to set the response Content-Type header to text/html; charset=utf-8 whenever it receives a Post-Back request identified by the corresponding header from WebFormsJS.
This ensures that the browser interprets the response as HTML rather than attempting to process it as another content format.
SSE Transmission Interval
(sse_interval=1000)
This setting specifies the time interval, in milliseconds, between consecutive SSE data transmissions from the server to the client.
For example, a value of 1000 means that SSE data is transmitted every second.
Developers can adjust this value to control how frequently SSE data is sent.
Maximum SSE Connections per Client
(max_sse_connections_per_client=3)
This setting defines the maximum number of simultaneous SSE connections allowed per client.
When the number of connection requests exceeds this limit, the oldest active SSE connection is terminated, and a new connection is established in its place.
This helps prevent an excessive number of SSE connections from being maintained by a single client.
Conclusion
The CodeBehind options file provides a centralized way to customize many aspects of the framework, from View compilation and file management to Controller routing and real-time communication.
Instead of modifying framework code or implementing additional configuration logic, developers can adjust these settings directly through code_behind/options.ini.
More customization options may be added to the options file in future versions of CodeBehind.
Related links
CodeBehind on GitHub:
https://github.com/elanatframework/CodeBehind
CodeBehind in NuGet:
https://www.nuget.org/packages/CodeBehind/
CodeBehind page:
https://elanat.net/codebehind
