Comment on page
Application
Wisej.Web.Application
Namespace: Wisej.Web
Assembly: Wisej.Framework (3.2.0.0)
Represent a Wisej application session. Provides methods and events to manage the application in the context of the current session.
C#
VB.NET
public class Application : IWisejComponent, IDisposable, IWisejSynchronized
Public Class Application
Inherits IWisejComponent
Implements IDisposable, IWisejSynchronized
This class provides several static methods, properties and events that allow the application to manage all sorts of features related to the current session:
- Save and retrieve session variable. Use Session to store and retrieve session variable. The property is a dynamic object and a Dictionary, therefore you can access its properties directly or through the indexer.
Application.Session.myValue = 12;
Application.Session["myValue"] = 12;
- Read server variables. Use ServerVariables to retrieve all the data made available by the server. Some of the variables in the collection are also available directly: ServerPort, ServerName, UserAgent, etc.
- Listen to the application's global events. See SessionTimeout , BeginRequest, ApplicationStart, ApplicationExitApplicationRefresh, BrowserSizeChangedResponsiveProfileChanged, CultureChanged, and many more.
- Manage all live components in the session. Through the Application class you can find, iterate, inspect all live components of any type. See OpenForms for all the currently created (visible or invisible) instances of Form. OpenPages returns all the created Page objects. FindComponent and FindComponents provide an easy way to find any component in the session or to iterate the list of components that match a custom expression.
- Start background tasks in context. StartTask provides a powerful way to start a background task on the server that can keep interacting with the client browser while running independently.
- Manage the application's theme. Use LoadTheme to load a Wisej theme into the application. Or use the Theme object to read all sorts of information from the current ClientTheme.
- Terminate the application without waiting for the session to timeout. Use Exit to terminate the current session and free all the related memory.
There is a lot more exposed by the Application class. You can inspect all the properties and methods in Visual Studio through IntelliSense or online at docs.wisej.
This is the profile that best matches the current browser on the client. It is updated automatically on every request.
String: Returns the company name associated with the application stored in the AssemblyCompanyAttribute.
IWisejComponent: Returns the application component instance that an application can store and use later to restore the context when updating client widgets during an out-of-bound call using the Update method.
Threads that are not started using StartTask don't have any knowledge of the current session and don't have a way to communicate with the client The Current property returns the instance of the Application class that is bound to the current session. It can be used just like any other component with the method Update or RunInContext to restore the session for the current thread. The advantage of using Current instead of the instance of a control or a page is to avoid to keep a reference to a component that may be disposed by the application.
var current = Application.Current;
var thread = new Thread(() => {
Application.Update(current, () => {
// code here is running in context.
});
});
Boolean: Returns or sets whether the browser will ask the user to confirm unloading the current page.
This property attaches the window.onbeforeunload event. See https://developer.mozilla.org/en-US/docs/Web/API/WindowEventHandlers/onbeforeunload. It's not possible to determine whether the page is being unloaded because the user is trying to close the tab, close the browser, or is refreshing the page, or is taking any other action that may reload the page.
Boolean: Indicates that the current application instance, which corresponds to the session, has been terminated and disposed.
Object: Returns a dynamic object containing the currently loaded license information. [Since 3.1.3]
These are the currently available fields (may change in future releases):
- Valid: Whether the license is valid. Note that a license may be expired and valid if the product release date is within the license expiration date.
- ProductName: Full name of the licensed product.
- CustomerName: Name of the registered customer that owns the license.
- ExpirationDate: Expiration date for the product free updates.
Retrieve the values either using a dynamic object or a property indexer:
string productName = Application.LicenseInfo.ProductName;
string customerName = Application.LicenseInfo["CustomerName"];
Setting the LicenseKey programmatically has to be done before the application is loaded. The best place is the static constructor for the Program static class, or the static constructor of the main window (if defined in Default.js).
static class Program
{
static Program()
{
Application.LicenseKey = "...";
}
}
String: Returns the product version associated with this application stored either in AssemblyInformationalVersionAttribute or AssemblyFileVersionAttribute.
Boolean: Returns or sets whether all the controls in the applications should operate using the right-to-left mode.
The value of this property is updated automatically when the current language changes if the value of "rightToLeft" in the application configuration file is set to "auto".
String: Returns the server's host name, DNS alias, or IP address as it would appear in self-referencing URLs.
ServiceProvider: Returns the ServiceProvider implementation used by Wisej.NET to manage Dependency Injection across the application. [Since 3.1]
Displays a simple HTMl only debug console. Works with any browser also when the developer tools are not available.
You can create and modify a new custom theme using the ClientTheme class. The new theme can be based on an existing theme, can be empty, or can be initialized from a JSON string.
// create a new custom theme cloned from the current theme.
var myTheme = new ClientTheme("MyTheme", Application.Theme);
// alter the buttonFace color.
myTheme.Colors.buttonFace = "red";
// update the current session using the new custom theme.
Application.Theme = myTheme;
You may also alter a global theme shared by all sessions.
// change the buttonFace color in the current theme.
// if the theme is one of the global themes, i.e. it was loaded
// using Application.LoadTheme(name), then the change is also global.
Application.Theme.Colors.buttonFace = "red";
// since the theme objects are all dynamic and use a special DynamicObject
// class part of the Wisej Framework, you can also use a string indexer
// to address any field.
Application.Theme.Colors["buttonFace"] = "red";
Uri: Returns the current Uri used either to launch or reload the application. It may be different from StartupUri.
String: Returns the current URL used either to launch or reload the application. It may be different from StartupUrl.
Adds an event filter to monitor all the incoming events before they are routed to their respective component.
Parameter | Type | Description |
---|---|---|
filter |
Adds the text and corresponding translation to the default locale on the client.
Instructs the browser to display a dialog with an optional message, and to wait until the user dismisses the dialog.
Parameter | Type | Description |
---|---|---|
message | A string you want to display in the alert dialog. |
Executes the JavaScript function on the client.
Executes the JavaScript function on the client and receives the return value (or null) in the callback method.
Parameter | Type | Description |
---|---|---|
function | The name of the function to execute. | |
callback | Asynchronous callback method that receives the return value. | |
args | The arguments to pass to the function. |
Asynchronously executes the JavaScript function on the client and returns an awaitable Task with the result of the remote call.
Cancels the fullscreen mode.
Instructs the browser to display a dialog with an optional message, and to wait until the user either confirms or cancels the dialog. until the user dismisses the dialog.
Parameter | Type | Description |
---|---|---|
message | A string you want to display in the confirm dialog. |
Downloads the specified file on the client.
Parameter | Type | Description |
---|---|---|
filePath | The file to download. | |
fileName | The name of the file to save on the client. | |
ondownload | Optional callback invoked when fileName is downloaded. |
Downloads the specified image to the client.
Parameter | Type | Description |
---|---|---|
image | The image to download. | |
fileName | The name of the file to save on the client. | |
ondownload | Optional callback invoked when fileName is downloaded. |
Downloads the bytes in the stream to the client.
Parameter | Type | Description |
---|---|---|
stream | The stream to send to the client. | |
fileName | The file name the client will use to save the stream. | |
ondownload | Optional callback invoked when fileName is downloaded. |
Downloads the specified file on the client.
Parameter | Type | Description |
---|---|---|
target | Specifies where to open the file. Leave empty or use "_self" to open in the current tab, _blank to open in a new tab. | |
filePath | The file to download. | |
fileName | The name of the file to save on the client. | |
ondownload | Optional callback invoked when fileName is downloaded. |
Downloads the specified image to the client.
Parameter | Type | Description |
---|---|---|
target | Specifies where to open the file. Leave empty or use "_self" to open in the current tab, _blank to open in a new tab. | |
image | The image to download. | |
fileName | The name of the file to save on the client. | |
ondownload | Optional callback invoked when fileName is downloaded. |
Downloads the bytes in the stream to the client.
Parameter | Type | Description |
---|---|---|
target | Specifies where to open the file. Leave empty or use "_self" to open in the current tab, _blank to open in a new tab. | |
stream | The stream to send to the client. | |
fileName | The file name the client will use to save the stream. | |
ondownload | Optional callback invoked when fileName is downloaded. |
Stops the polling requests from the client.
Executes the JavaScript script on the client.
Parameter | Type | Description |
---|---|---|
script | The script to evaluate. |
Executes the JavaScript script on the client and receives the return value (or null) in the callback method.
Parameter | Type | Description |
---|---|---|
script | The script to evaluate. | |
callback | Asynchronous callback method that receives the return value. |
Asynchronously executes the JavaScript script on the client and returns an awaitable Task with the result of the remote call.
Parameter | Type | Description |
---|---|---|
script | The script to evaluate. |
Terminates the application and the corresponding session.
Find the first component that matches the conditions defined in the predicate function.
Parameter | Type | Description |
---|---|---|
match |
This method lets an application find any live component in the current session.
// Find the first component that is a Button with Text = "OK"
var button = Application.FindComponent(c => c is Button && ((Button)c).Text == "OK");
Finds all the components that match the conditions in the predicate function.
Parameter | Type | Description |
---|---|---|
match |
Returns: IList<IWisejComponent>. The list of IWisejComponent instances qualified by the match expression.
This method lets an application iterate through all the live components in the current session.
// List all text boxes that are read only in all forms.
var list = Application.FindComponents(c => c is TextBox && ((TextBox)c).ReadOnly);
EXPERIMENTAL: Returns a session-static instance of T . [Since 3.2.7]
Parameter | Type | Description |
---|---|---|
T | | Type of the singleton object. |
reference | Thread-static reference to the T singleton. | |
builder | Optional method for the creation of an instance of T . |
This utility method simplifies the management of session-static (or session singleton) instances. It should be used to convert traditional static variables to session-static instances when changing an application designed for single users to a multi-user system. The code below shows how to use this feature together with the ThreadStaticAttribute to manage session-static instances and, at the same time, improve the speed of the code that relies on the singleton objects. Using the ThreadStaticAttribute backing field allows the code that retrieves the session-static instance to quickly check the last instance and compare the session id and avoid accessing the dictionary for every access within the same request. Otherwise the code would have to always store a local variable in order to speed up multiple operations using the same static field.
public class MyStatics {
// Thread-static singleton.
[ThreadStatic] private static SessionReference<MyStatics> _instance;
// Previously static fields (or properties).
public int Counter;
// Session singleton.
public MyStatics Instance
=> Application.GetInstance(ref _instance);