Links

Application

Wisej.Web.Application
Namespace: Wisej.Web
Assembly: Wisej.Framework (3.1.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;
  • Manage cookies. Use Cookies to manage browser's cookies.
  • 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.
  • Read the application's URL. Use Uri, Url, StartupUri, and StartupUrl.
  • Read the applications's system information. Use StartupPath, ProductName, ProductVersion, etc.
  • Retrieve browser related information. Use the Browser to read the client browser type, OS, version, capabilities, screen size, browser size, language, and state. The Browser object is updated automatically when the user resizes the browser or the page is reloaded.
  • Control the client browser. Start a Download, execute JavaScript functions or scriptlets using Call or Eval. Make the browser navigate to a different URL using Navigate or simply Reload the page.
  • Manage the main page or current desktop. MainPage lets you change the Page object that fills the browser and "navigate" from page to page. Desktop lets you change the active Desktop object on the client browser.
  • 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.

Properties

ActiveProfile

ClientProfile: Returns or sets the current client responsive profile.
This is the profile that best matches the current browser on the client. It is updated automatically on every request.

Browser

ClientBrowser: Returns or sets the client browser information.

ClientId

String: Returns the current unique client id.

Clients

ClientCollection: Returns a collection of all the unique client browsers using the application.

CommonAppDataPath

String: Returns the path for the application data that is shared among all users.

CommonAppDataRegistry

RegistryKey: Returns the registry key for the application data that is shared among all users.

CompanyName

String: Returns the company name associated with the application stored in the AssemblyCompanyAttribute.

Configuration

Configuration: Returns the current Configuration.

Cookies

CookieCollection: Collection of cookies.

Current

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.
});
});

CurrentCulture

CultureInfo: Returns or sets the current CultureInfo for the session.

Desktop

Desktop: Returns or sets the current Desktop.

EnableUnloadConfirmation

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.

ExecutablePath

String: Returns the path for the application's main assembly.

FavIcon

Image: Returns or sets the favicon to display in the browser.

FavIconSource

String: Returns or sets the URL to the favicon to display in the browser.

Hash

String: Returns or sets the hash part of the URL on the client.

IsAuthenticated

Boolean: Returns a value indicating whether the session has been authenticated.

IsDisposed

Boolean: Indicates that the current application instance, which corresponds to the session, has been terminated and disposed.

IsExpired

Boolean: Returns true when the current session has expired.

IsSecure

Boolean: Returns true if this session is running in secure mode (https:// and wss://)

IsTerminated

Boolean: Returns true when the current session has been terminated.

IsWebSocket

Boolean: Returns true if the current session is connected using WebSocket.

LicenseInfo

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.
  • LicenseKey: License key loaded from web.config or assigned to LicenseKey.
  • 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"];

LicenseKey

String: Returns or sets the runtime server license key.
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 = "...";
}
}

MainPage

Page: Returns or sets the current full page window.

OpenForms

FormCollection: Returns a collection of open forms owned by the application.

OpenPages

PageCollection: Returns a collection of open pages owned by the application.

Platform

ClientPlatform: The name of the currently loaded platform.

ProductName

String: Returns the product name associated with this application.

ProductVersion

String: Returns the product version associated with this application stored either in AssemblyInformationalVersionAttribute or AssemblyFileVersionAttribute.

QueryString

NameValueCollection: Returns the parameters used to launch the application.

RightToLeft

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".

RuntimeMode

Boolean: Returns true when the application is running in not in design, debug or test mode.

ServerName

String: Returns the server's host name, DNS alias, or IP address as it would appear in self-referencing URLs.

ServerPort

Int32: Returns the port number to which the request was sent.

ServerVariables

NameValueCollection: Returns the server variables.

Services

ServiceProvider: Returns the ServiceProvider implementation used by Wisej.NET to manage Dependency Injection across the application. [Since 3.1]

Session

Object: Provides a generic storage for session-based objects.

SessionCount

Int32: Returns the total number of currently active sessions.

SessionId

String: Returns the unique current session ID.

ShowConsole

Boolean: Shows or hides the debug console on the browser.
Displays a simple HTMl only debug console. Works with any browser also when the developer tools are not available.

ShowLoader

Boolean: Returns or sets whether the browser is blocked by the Ajax loader.

StartupPath

String: Returns the root path of the web application.

StartupUri

Uri: Returns the URI used to start the application.

StartupUrl

String: Returns the URL used to start the application.

Theme

ClientTheme: Returns or sets the current ClientTheme.
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";

Title

String: Returns or sets the page title in the browser.

Uri

Uri: Returns the current Uri used either to launch or reload the application. It may be different from StartupUri.

Url

String: Returns the current URL used either to launch or reload the application. It may be different from StartupUrl.

User

IPrincipal: Returns the security information for the current request.

UserAgent

String: Returns the raw user agent string of the client browser.

UserHostAddress

String: Returns the IP host address of the remote client.

UserHostName

String: Returns the DNS name of the remote client.

UserIdentity

WindowsIdentity: Returns the WindowsIdentity type for the current user.

UserLanguages

String[]: Gets a sorted string array of client language preferences.

Methods

AddEventFilter(filter)

Adds an event filter to monitor all the incoming events before they are routed to their respective component.
Parameter
Type
Description
filter
An object that implements the IEventFilter interface to add to the filter list.

AddTranslation(text, translation)

Adds the text and corresponding translation to the default locale on the client.
Parameter
Type
Description
text
String
The text to translate.
translation
String
The translation override.

AlertAsync(message)

Instructs the browser to display a dialog with an optional message, and to wait until the user dismisses the dialog.
Parameter
Type
Description
message
String
A string you want to display in the alert dialog.
Returns: Task. An awaitable Task that represents the asynchronous operation.

Call(function, args)

Executes the JavaScript function on the client.
Parameter
Type
Description
function
String
The name of the function to execute.
args
Object[]
The arguments to pass to the function.

Call(function, callback, args)

Executes the JavaScript function on the client and receives the return value (or null) in the callback method.
Parameter
Type
Description
function
String
The name of the function to execute.
callback
Asynchronous callback method that receives the return value.
args
Object[]
The arguments to pass to the function.

CallAsync(function, args)

Asynchronously executes the JavaScript function on the client and returns an awaitable Task with the result of the remote call.
Parameter
Type
Description
function
String
The name of the function to execute.
args
Object[]
The arguments to pass to the function.
Returns: Task<Object>. An awaitable Task that represents the asynchronous operation.

CancelFullScreen()

Cancels the fullscreen mode.

ConfirmAsync(message)

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
String
A string you want to display in the confirm dialog.
Returns: Task<Boolean>. An awaitable Task that represents the asynchronous operation.

Download(image, fileName, ondownload)

Downloads the specified image to the client.
Parameter
Type
Description
image
Image
The image to download.
fileName
String
The name of the file to save on the client.
ondownload
Optional callback invoked when fileName is downloaded.

Download(stream, fileName, ondownload)

Downloads the bytes in the stream to the client.
Parameter
Type
Description
stream
Stream
The stream to send to the client.
fileName
String
The file name the client will use to save the stream.
ondownload
Optional callback invoked when fileName is downloaded.

Download(filePath, fileName, ondownload)

Downloads the specified file on the client.
Parameter
Type
Description
filePath
String
The file to download.
fileName
String
The name of the file to save on the client.
ondownload
Optional callback invoked when fileName is downloaded.

DownloadAndOpen(target, filePath, fileName, ondownload)

Downloads the specified file on the client.
Parameter
Type
Description
target
String
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
String
The file to download.
fileName
String
The name of the file to save on the client.
ondownload
Optional callback invoked when fileName is downloaded.

DownloadAndOpen(target, image, fileName, ondownload)

Downloads the specified image to the client.
Parameter
Type
Description
target
String
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
Image
The image to download.
fileName
String
The name of the file to save on the client.
ondownload
Optional callback invoked when fileName is downloaded.

DownloadAndOpen(target, stream, fileName, ondownload)

Downloads the bytes in the stream to the client.
Parameter
Type
Description
target
String
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
Stream
The stream to send to the client.
fileName
String
The file name the client will use to save the stream.
ondownload
Optional callback invoked when fileName is downloaded.

EndPolling()

Stops the polling requests from the client.

Eval(script)

Executes the JavaScript script on the client.
Parameter
Type
Description
script
String
The script to evaluate.

Eval(script, callback)

Executes the JavaScript script on the client and receives the return value (or null) in the callback method.
Parameter
Type
Description
script
String
The script to evaluate.
callback
Asynchronous callback method that receives the return value.

EvalAsync(script)

Asynchronously executes the JavaScript script on the client and returns an awaitable Task with the result of the remote call.
Parameter
Type
Description
script
String
The script to evaluate.
Returns: Task<Object>. An awaitable Task that represents the asynchronous operation.

Exit()

Terminates the application and the corresponding session.

FindComponent(match)

Find the first component that matches the conditions defined in the predicate function.
Parameter
Type
Description
match
A custom Predicate expression used to match the IWisejComponent to find.
Returns: IWisejComponent. The first IWisejComponent qualified by the match expression.
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");

FindComponents(match)

Finds all the components that match the conditions in the predicate function.
Parameter
Type
Description
match
A custom Predicate expression used to match the list of IWisejComponent objects to find.
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);

LoadAssembly(nameOrFile)

Loads an assembly given the file name or path.
Parameter
Type
Description
nameOrFile
String
The file name or full path for the assembly to load.
Returns: Assembly. The loaded Assembly.
This method loads the assembly and, if the assembly contains Wisej components that need embedded resources - like JavaScript classes or CSS styles - that are embedded in the assembly, notifies the client with the URL to load the additional resources dynamically.

LoadComponent(nameOrFile, className)

Creates an instance of the specified component from the assembly.
Parameter
Type
Description
nameOrFile
String
The file name or full path for the assembly to load.
className
String
Returns: IWisejComponent. An instance of a Wisej component implementing the IWisejComponent interface.

LoadPackages(packages, callback)

Parameter
Type
Description
packages
callback

LoadPackagesAsync(packages)

Parameter
Type
Description
packages
Returns: Task<Boolean>.

LoadTheme(name, mixins)

Changes the current theme.
Parameter
Type
Description
name
String
Name of the theme resource. Use only the name without the path and without the extension.
mixins
String[]
Optional list of theme mixins. If null, the default theme mixins are always applied.

MapPath(path)

Returns the full file path in relation to the application's project directory.
Parameter
Type
Description
path
String
Returns: String. The full path relative to the current application's root directory.
Navigate to the specified URL.
Parameter
Type
Description
url
String
URL to navigate to.
target
String
The target browser window: _self, _blank, etc.
EXPERIMENTAL: Navigate to the specified URL in a new browser tab and receive an optional callback when the tab is closed.
Parameter
Type
Description
url
String
URL to navigate to.
target
String
The target browser window, cannot be _self and cannot be empty.
onclose
Action
Callback function invoked when the browser tab is closed. Can be null.

OpenWindow(url, target, windowFeatures, onclose)

EXPERIMENTAL: Opens the specified URL in a browser's popup window and receive an optional callback when the tab is closed.
Parameter
Type
Description
url
String
URL to navigate to.
target
String
The target browser window, cannot be _self and cannot be empty.
windowFeatures
String
A string containing a comma-separated list of window features in the form name=value — or for boolean features, just name. These features include options such as the window's default size and position, whether or not to open a minimal popup window, and so forth.
onclose
Action
Callback function invoked when the browser popup window is closed. Can be null.

Play(type)

Plays one of the built-in sounds
Parameter
Type
Description
type
One of MessageBoxIcon value that identifies the sound to play.

Play(soundUrl)

Plays a sound.
Parameter
Type
Description
soundUrl
String
A string representing either a sound file URL or a base64 data URL.

Post(callback)

Executes the callback method after all processing is completed and before updating the client.
Parameter
Type
Description
callback