IAppContext Interface

The Application context object holds information that is used throughout each page (or server) request. The Application is available to all objects, either as a direct parameter or property on an existing object. The Application object is created as the first object in any request, and when possible it is cached for performance purposes. The application hosts extensions and fires various application ExtensionEvents to those extensions. The normal IAppContext implementation is provided by the AppContext object.

The following properties are commonly accessed:

Session - Gets the current Session object.
UserContext - Gets the UserContext object describing the current user.
DataDB - Gets the primary IDatabase source for operation data.
Databases - Gets the Databases collection of IDatabase objects for the application.
Navigators - Gets the Navigators collection of Navigator objects for the application.
PageInfos - Gets the PageInfos collection of PageInfo objects for the application.
Picklists - Gets the Picklists collection of Picklist objects for the application.
Services - Gets the ServiceInfos collection of IServiceInfo objects for the application.
Templates - Gets the Templates collection of Template objects for the application.

The following methods are commonly used:

DisplayMessage(Alert) - Displays a message to the user.
Navigate(String, String, String) - Ends the current request and navigates to a page within the application.
ResolveEmbeddedFunctions(String, IDatabase, ResolveOptions) - Resolves a string for embedded functions.
Send(MailMessage) - Sends an email message using the default mail service.

In addition to the properties and methods directly exposed via the interface, a number of additional commands, identified by AppExecCmds, are available via the Exec(Enum, Int32, Object) method.

Namespace: NetQuarry
Assembly: EAP.Core (in EAP.Core.dll) Version: 2.0.0.0 (4.6.8.0)

Syntax

Copy

public interface IAppContext : IEAPBase, 
	IDisposable

Public Interface IAppContext
	Inherits IEAPBase, IDisposable

The IAppContext type exposes the following members.

Properties

	Name	Description
	ApplicationRoot	Returns the root virtual folder for the application.
	AppVersion	Gets the application build version number (not the platform version number). Currently this is determined from the file version of the first application extension (if any).
	BestTextCulture	Gets the best text locale available to the application (according to the available resource files) to satisfy the desired locale specified via the application's CultureInfo property. Note that this is the "best" text locale available, but not all text items are necessarily available from the "best" resource. When no matching text is found in the "best" resource, other resources will be searched. At this time the platform provides a standard "en" (theoretically non-specific English, but in practice U.S. English) resource file only. An application can include custom resource files by placing appropriately named resource files in the folder specified in the CustomResourcePath application property.
	Browser	Returns the BrowserInfo information object about the current request's browser.
	Components	Returns the collection of ComponentInfo objects.
	CSRFToken	Gets the current Cross-Site Request Forgery (CSRF) token. Normally the CSRF token is automatically injected into a form when the page is rendered and validated when the page is posted back. You can use ValidateCSRFToken(String, CSRFValidationOptions) if explicit validation is required. CSRF token use can be disabled by setting NoCSRFToken on the application. A good CSRF overview can be found at Cross-Site Request Forgery (CSRF) Prevention Cheat Sheet which describes CSRF thusly: Cross-Site Request Forgery (CSRF) is a type of attack that occurs when a malicious web site, email, blog, instant message, or program causes a user’s web browser to perform an unwanted action on a trusted site for which the user is currently authenticated. The impact of a successful CSRF attack is limited to the capabilities exposed by the vulnerable application. For example, this attack could result in a transfer of funds, changing a password, or purchasing an item in the user's context. In effect, CSRF attacks are used by an attacker to make a target system perform a function via the target's browser without knowledge of the target user, at least until the unauthorized transaction has been committed.
	Culture	The general CultureInfo (.Net culture object) to use for the application.
	CurrentPage	Gets/sets the current .Net Page being rendered. In general, this value is set as soon as the application context is attached to the page. Note that in cases where a page is not being rendered, e.g. AJAX calls, scheduled services, etc., this value will be null.
	Databases	The collection of IDatabase objects associated with this application.
	DataCache	Gets the operational data CacheManager object for this application.
	DataDB	Get the primary data source IDatabase for the application. Note that the data source IDatabase is also contained in the Databases collection. The DataDB is identified with the IsDefault attribute on its data source. See also MasterDB and RepositoryDB.
	DisposableObjects	Returns a list of objects tracked by the application. These objects include all IDataReader objects opened via OpenDataReader(String, IDbConnection, DataFuncOptions, String, String) and all IMapper objects.
	DocumentLang	Gets the language id to use for the page's HTML tag as specified in https://www.w3.org/International/questions/qa-html-language-declarations. Note that the language is based on the BestTextCulture value.
	EventInfos	Returns the EventInfo objects collection.
	Extensions	Gets the collection of IExtension objects configured for this application.
	Favorites	Returns the favorites (bookmarks) collection for this user.
	Features	Returns the current set of Feature objects for the application
	Filters	The collection of SavedFilter objects for the application.
	ID	Sets/Gets the application ID.
	IsDeveloper	Determines whether or not the current user is a developer or the current code is a DEBUG build. Note that IsProduction, IsTest, and IsDeveloper are independent of one another and various combinations are valid.
	IsProduction	Gets/Sets the value of the application property "IsProduction". The IsProduction flag is intended to suppress possibly-sensitive developer information on a site that is on the open internet. Control of information that is less sensitive and should be available in test systems, even when on the open internet, is based on the IsTest property. Note that IsProduction, IsTest, and IsDeveloper are independent of one another and various combinations are valid.
	IsStrictMode	Determines whether or not the application is being run in "strict" mode. In strict mode platform security is more restrictive. In particular: Mapper fields that are not visible are treated as "sensitive" by default (excepting fields marked as PK, UniqueKey, or SubformKey). Sensitive fields are not rendered into the HTML in any form when not visible to the current user. Since this will prevent their use in javascript, a field can be marked with FieldSecurityAttrs.DOMAccessed to specify that it should be rendered into HTML even when not visible to the current user. Values posted back for mapper fields that were (or should have been) locked, hidden, or omitted when the page was rendered will be ignored. Since this will prevent values being saved that were set on such fields in javascript, a field can be marked with FieldSecurityAttrs.DOMModified to specify that posted back value changes should be accepted even when locked, hidden, or omitted.
	IsTest	Gets/Sets a flag is intended to suppress non-sensitive tester/developer information that should be available in a test environment even when that system is on the open internet. More sensitive information that should always be suppressed on the open internet, even in a test system, is controlled by the IsProduction flags. The IsTest property is controlled by the application's web.config file's appSettings section test_environment key and defaults to false: Copy <appSettings> <add key="test_environment" value="true"/> </appSettings> Note that IsProduction, IsTest, and IsDeveloper are independent of one another and various combinations are valid.
	IsValid	Indicates whether the context is valid or not.
	MasterDB	Get the master data source IDatabase for the application. The master data source is consistent across all tenants even when per-tenant data source mappings are used. When no such mappings are used this will be the same as the DataDB. The MasterDB is identified with the IsMaster attribute on its data source. See also RepositoryDB.
	MetadataCache	Gets/Sets the value of the application property "MetadataCache">
	MetaTableInfos	Returns the MetaTableInfo objects collection.
	ModuleInfos	The collection of ModuleInfo objects for the application.
	NamedFilters	Returns the NamedFilter objects collection.
	Navigators	The collection of Navigator objects for the application.
	PageInfos	The collection of PageInfo objects for the application.
	PerfmonObjects	The collection of PerfmonObjects objects for the application.
	Picklists	Returns the collection of Picklist items.
	Properties	The Properties collection of Property objects for this object. (Inherited from IEAPBase.)
	Reports	Returns the collection of Report objects.
	RepositoryDB	Get the primary repository IDatabase for the application. Note that the repository IDatabase is also contained in the Databases collection . See also MasterDB and DataDB.
	Services	Returns the collection of IServiceInfo objects.
	Session	Gets/sets the Session object.
	Settings	The set of application settings loaded from the xot_app_setting.
	Templates	Returns the collection of Template objects.
	TextItems	The TextItems collection of TextItem localized text objects for this object. (Inherited from IEAPBase.)
	TimeZones	Returns the TimeZone object collection.
	TLSCache	Provides access to this thread's Thread-Local Storage (TLS) cache.
	UserContext	Returns the UserContext object.
	Version	Gets/sets the version of this object's assembly. (Inherited from IEAPBase.)
	Versions	The collection of EAPVersion objects for this application. The versions defined in this collection can be used programmatically to control application behaviour in your code. It can also be used declaratively to switch on/off certain meta-data thoughout the application: Fields - The inclusion of specific IField objects in a particular IMapper object's Fields collection. Extensions - The inclusion of specific ExtensionInfo objects in a particular IMapper object's Extensions collection. Pages - The inclusion of specific PageInfo objects in the application's PageInfos collection. Page Elements - The inclusion of specific PageElementInfo objects in a particular PageInfo object's Elements collection. Navigators - The inclusion of specific Navigator objects in the application's Navigators collection.. Nav Targets - The inclusion of specific NavTarget objects in a particular Navigator object's Targets collection. In these cases the inclusion of specific items can configured to be version-specific by setting a particular item's Version and Min Version and/or Max Version. Where the Version is name of the EAPVersion item in this collection and the Min Version and Max Version are the minimum and maximum version numbers, respectively, for that version for which the versioned-item should be included (note that you may specify a minimum without a maximum, or vice versa). By using an appropriate combination of min/max values you can define identical objects that phase in and out for specific versions. Initially Versions are loaded into the collection from the xmt_versions table which is managed in the NetQuarry Studio. Versions can also be added (or removed or modified) programmatically.
	Vocab	Tenant-specific vocabulary overrides.

Top

Methods

	Name	Description
	AuthenticateUser(String)	Authenticates a user and populates the UserContext object. Note that if the application is being used to authenticate a different user than the one associated with the application (and therefore the user represented by UserContext) you must use the AuthenticateUser command.
	AuthenticateUser(String, String, String)	Authenticates the current user and populates/creates the UserContext object using the specified IAuthenticationProvider. Note that if the application is being used to authenticate a different user than the one associated with the application (and therefore the user represented by UserContext) you must use the AuthenticateUser command.
	AuthenticateUser(String, String, String, Int32)	Authenticates the current user and populates/creates the UserContext object using the specified IAuthenticationProvider. Note that if the application is being used to authenticate a different user than the one associated with the application (and therefore the user represented by UserContext) you must use the AuthenticateUser command.
	Clone	Clones this object and returns a new AppContext object.
	Clone(String, String)	Clones this object and returns a new AppContext object.
	Clone(String, String, String)	Clones this object and returns a new AppContext object.
	Close	Closes the application's internal datasources and clean's up any user token state that exist.
	DisplayMessage(Alert)	Registers a message, specified by the Alert object, for display on the next page rendering. Note that this page message facility is built on top of the existing Alerts functionality. The message information is stored in the xot_alerts table and delivered asynchronously via an AJAX call upon the next page rendering.
	DisplayMessage(String, String, AlertDelivery, Int32, AlertAttrs)	Registers a message for display on the next page rendering. Note that this page message facility is built on top of the existing Alerts functionality. The message information is stored in the xot_alerts table and delivered asynchronously via an AJAX call upon the next page rendering.
	Dispose	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. (Inherited from IDisposable.)
	Exec	The Exec method provides extended functionality. (Inherited from IEAPBase.)
	GetFirstNavigablePage	Returns the first navigable page for this user
	GetPageInfo(String)	Get the PageInfo object for the specified MOP.
	GetPageInfo(String, GetPageFlags)	Get the PageInfo object for the specified MOP per the provided flags.
	GetPermaLink	Returns a permanant link to an item by inserting the QueryString parameters supplied into the main database's xot_url table.
	GetResourceString	Returns the string for the given resource for this application's Culture.
	GetText(String)	Returns a string from the TextItems collection
	GetText(String, String)	Returns a string from the TextItems collection
	HasFeature(String)	Returns true if the feature is implemented on the application.
	HasFeature(String, String)	Returns true if the feature is implemented on the application and the requested property is used.
	HasPermission	Returns true if the specified object "has" the specified ObjectPermissions. If the object has no assigned permisions, the return value is true.
	HasPolicy(String)	Obsolete. Returns true if the current user has not been explicitly denied the policy. NOTE: This method is deprecated. Use HasPolicy(String, Boolean) instead for improved security.
	HasPolicy(String, Boolean)	Returns true if the current user has been granted the policy.
	Hibernate	Command the AppContext object to hibernate until next round trip. Hibernated applications's are awoken via WakeUp.
	Init	Initialize the AppContext object.
	Init(AppContextInitOptions)	Initialize the AppContext object based on the provieded AppContextInitOptions.
	Load	Load the AppContext object from the database.
	LoadComponent	Finds the specified component in the application's Components collection, loads it, verfies that it implements the requested interface (if specified), and returns the object. Normally an appropriate AssemblyLoadFail exception will be thrown if the component could not be found, loaded or requested interface obtained for any reason. However, if OkIfNotFound is set a failure will suppress any such error and result in null being returned.
	LogPerformance	Log the performance metric of an object using a diagnostic service
	Navigate(String)	Causes a Redirect to the specified page.
	Navigate(String, String)	Causes a Redirect to the specified page.
	Navigate(String, String, String)	Causes a Redirect to the specified page.
	Navigate(String, String, String, String)	Causes a Redirect to the specified page.
	Navigate(String, String, String, String, NavigateAttrs, String)	Causes a Redirect to the specified page.
	OpenRepository	Open the repository IDatabase.
	Permissions	Returns a bitmask of the object's ObjectPermissions. If the object has no assigned permissions, the return value is 0xffffffff (All permission bits are set)
	RegisterDebugInfo(Page, String, String)	Register a dbginfo item on the page. These items will be emitted into the page HTML for debugging purposes and may be viewed by hitting F8 on the page.
	RegisterDebugInfo(Page, String, String, String)	Register a dbginfo item on the page (with category information). These items will be emitted into the page HTML for debugging purposes and may be viewed by hitting F8 on the page.
	RegisterDebugInfo(Page, String, String, String, LogMessageLevel)	Register a dbginfo item on the page (with caetgory and severity level). These items will be emitted into the page HTML for debugging purposes and may be viewed by hitting F8 on the page.
	RegisterDebugInfo(Page, String, String, String, String)	Register a dbginfo item on the page (with category and sublist information). These items will be emitted into the page HTML for debugging purposes and may be viewed by hitting F8 on the page.
	RegisterDebugInfo(Page, String, String, String, String, LogMessageLevel)	Register a dbginfo item on the page (with full information). These items will be emitted into the page HTML for debugging purposes and may be viewed by hitting F8 on the page.
	RegisterEmbeddedFunction(String, String)	Registers an embedded function for use in SQL statments. The function name should not include the leading lowercase 'fn' associated with embedded functions. See EmbeddedParser for more information on embedded functions.
	RegisterEmbeddedFunction(String, String, String)	Registers an embedded function for use in SQL statments. The function name should not include the leading lowercase 'fn' associated with embedded functions. See EmbeddedParser for more information on embedded functions. Embedded functions are automatically resolved for both DefaultValues on Field objects and Filters on Mapper objects. Normally, you register an extension to run at startup and register custom functions in the ExtensionEvents.ApplicationAfterLoad event.
	ResolveEmbeddedFunctions	Resolve an expression string for embedded functions. See EmbeddedParser for more information on embedded functions.
	Send(MailMessage)	Sends an email message using the contents of the message object.
	Send(MailMessage, String)	Sends an email message using the contents of the message object and the specified email service.
	SetUserTimeZone	Sets the user's timezone.
	UrlRead	Reads a URL from the database xot_url table. URL's are generally stored in this manner for one of two purposes: 1) For permanent use as a saved reference of some type, and 2) As a temporary URL whose reference is passed as a query parameter (for security and to reduce query parameter size). Use UrlSave(String, UrlLinkType, NullableDateTime) to save URL's.
	UrlSave	Stores a URL in the database xot_url table. URL's are generally stored in this manner for one of two purposes: 1) For permanent use as a saved reference of some type, and 2) As a temporary URL whose reference is passed as a query parameter (for security and to reduce query parameter size). Use UrlRead(String) to retrieve saved URL's.
	UsesImplicitVocab	Returns true if the locationAttrs supports implicit vocab.
	ValidateCSRFToken	Validates the specified token against the CSRFToken. Note that if the ThrowStandardError option is specified then this method will throw the standard invalid CSRF token exception and will not return.
	WakeUp	Command the AppContext object to wake up the database connections. Applications are hibernated via Hibernate.
	WakeUp(WakeUpFlags)	Command the AppContext object to wake up the database connections. Applications are hibernated via Hibernate.

Top

Extension Methods

	Name	Description
	BootstrapVersion	Returns the current Bootstrap version. For example, if the current version is 3.3.6 then this method returns 336. If it was version 4.1.3 then this method returns 413. (Defined by AppContextExtensions.)
	LogException	Logs an error and writes it to the request log (Defined by ApplicationExtensionMethods.)
	LogNextMapperSource	Extension method to IAppContext object to set a one-time-use logSource to be used on the next IMapper Init(). (Defined by AppContextExtensions.)
	UIStyle	Gets the AppUIStyle application UI style. (Defined by AppContextExtensions.)
	UseBootstrap	Determines of this is a Bootstrap-based application. Note that currently this determination is based on whether or not bootstrap.master is set as the MasterPageFile. (Defined by AppContextExtensions.)
	UserAuthenticationView	Gets the AuthenticationView for the application which is the view to use for the DatabaseAuthenticationProvider during authentication. By default this is 'users'. (Defined by ApplicationExtensionMethods.)

Top

Remarks

The Application object handles connecting to the authentication provider, authenticating the user, checking object permissions for that user, storing user (UserContext) information, holding the list of available PageInfo objects, and connecting to the metadata (Repository) data source. It also has a collection of DataSources specified in metadata.

Application Load

An application is loaded in the following sequence:

Configuration properties are loaded from the running application's configuration file. In the web, this file is web.config. In the studio, this file is EAP.Tools.exe.config. The configuration settings must have the named connection strings that will be used in the application.
The repository database is opened (see OpenRepository(String, Properties)).
The application's ID is set (optional). If there is no ID set, the default application configured in the repository is used.
Init(AppContextInitOptions) is called. During Init, the TextItems, Properties, Versions, Extensions, and Related Data Sources are loaded.
The IAuthenticationProvider is determined from Application properties and an instance is created.
The ApplicationBeforeAuthenticate event is fired.
The configured Authentication provider's IAuthenticationProvider method is called to authenticate the user and load the user's profiles.
The ApplicationAfterAuthenticate event is fired.
The Load method is called to load the PageInfo and Navigator objects into the PageInfos and Navigators collections respectively. Pages and navigators respect the permissions of the authenticated user.
The ApplicationAfterLoad event is fired.

Reference

IAppContextExtensions

NetQuarryApplicationExtensionBase

NetQuarry.SecurityIAuthenticationProvider