UltiDev Web Server Pro Configuration .NET API 1.0.0.15
.NET API for registering and unregistering web sites and applications with UltiDev Web Server.
UWS.Configuration.Metabase Class Reference

Facilitates registration application with UltiDev Web Server. To register an application with UWS, start with GetWebAppEntry() and then use RegisterApplication(). More...

List of all members.

Static Public Member Functions

static WebAppConfigEntry GetWebAppEntry (Guid applicationID, bool includeUninstalledInSearch)
 Returns an instance of WebAppconfigEntry that can be used to register an application with the web server.

To register an application, call this method first, and then one of the RegisterApplication() variants.

static WebAppConfigEntry GetWebAppEntry (Guid applicationID)
 Returns an instance of WebAppconfigEntry that can be used to register an application with the web server.
static void RegisterApplication (RuntimeVersion aspNetVersion, bool run32bitOnx64, bool useDefaultSharedHostProcess, ProcessIdentity processIdentity, WebAppConfigEntry application)
 Registers an application and if necessary, a corresponding host process.
static void RegisterApplication (RuntimeVersion aspNetVersion, bool run32bitOnx64, bool useDefaultSharedHostProcess, ProcessIdentity processIdentity, WebAppConfigEntry application, ICollection< AppShortcut > shortcuts)
 Registers an application and if necessary, a corresponding host process.
static void RegisterApplication (RuntimeVersion aspNetVersion, bool run32bitOnx64, ProcessIdentity hostUserIdentity, WebAppConfigEntry application)
 Registers an application with a default host process.
static void RegisterApplication (RuntimeVersion aspNetVersion, bool run32bitOnx64, ProcessIdentity hostUserIdentity, WebAppConfigEntry application, ICollection< AppShortcut > shortcuts)
 Registers an application with a default host process.
static void RegisterApplication (RuntimeVersion aspNetVersion, bool run32bitOnx64, WebAppConfigEntry application)
 Registers an application with a default host process running under Network Service user account.
static void RegisterApplication (RuntimeVersion aspNetVersion, bool run32bitOnx64, WebAppConfigEntry application, ICollection< AppShortcut > shortcuts)
 Registers an application with a default host process running under Network Service user account.
static void UnregisterApplication (Guid appID)
 Unregisteres an application and stops its hosting. Does nothing ig application with given ID is not registered.
static bool HasRegisteredApplications ()
 Returns False if there are no applications registered with UltiDev Web Server.
static int GetRegisteredApplicationCount ()
 Returns current number of applications registered with UWS.
static WebAppConfigEntry FindApplication (Guid appID)
 Finds existing application configuration entry.
static RedirectionConfigEntry FindRedirection (Guid redirectionID)
 Finds existing redirection configuration entry.
static RedirectionConfigEntry GetRedirectionEntry (Guid redirectionID)
 Finds an existing or creates new redirection configuration entry.
static void RegisterRedirector (RedirectionConfigEntry redirectionConfig)
 Registers redirection from a given set of listen URLs to a new location.
static void UnregisterRedirector (Guid redirectiorID)
 Unregisters redirection.
static string CreateAppRedirectLink (Guid appID, string host=null, string optionalPathAndQueryString=null, params ushort[] portOrder)
 Generates port-agnostic link to an application via UWS Redirector.
static string GetDefaultHost (bool forIOS)
 Returns machine's host name. If forIOS set to True, returns host name in either "machinename.local" or "machinename" format, depending whether machine is a member of a workgroup or a domain. If forIOS set to False, returns fully-qualigied domain name (FQDN) if machine is a member of a domain, or returns machine name, if computer is a member of a workgroup.
static bool WaitForAppToStart (Guid appID, int timeoutMilliseconds=-1)
 Allows waiting for an application to come online. Returns true when application responded, and false if timed out or application not found.
static bool LaunchTheAppInTheBrowser (Guid appID, string optionalPathAndQueryString=null, int timeoutMilliseconds=-1)
 Opens locally-registered application in the default browser, if application is running.

Detailed Description

Facilitates registration application with UltiDev Web Server. To register an application with UWS, start with GetWebAppEntry() and then use RegisterApplication().

To register an application, start with calling GetWebAppEntry(), which returns a reference to either new, or unregisterd, or currently registerd application. After that you may set WebAppConfigEntry properties and finally call RegisterApplication() method.

In order to unregister an application, simply call UnregisterApplication().


Member Function Documentation

static string UWS.Configuration.Metabase.CreateAppRedirectLink ( Guid  appID,
string  host = null,
string  optionalPathAndQueryString = null,
params ushort[]  portOrder 
) [static]

Generates port-agnostic link to an application via UWS Redirector.

Parameters:
appID
hostOptional. Host name or IP address to be used in the URL pointing to the UWS Recirector application. If null, default host will be used. If set to "*IOS*", host will be in the format of "machinename.local" or "machinename", depending on whether host machine is a member of a domain.
optionalPathAndQueryStringOptional. A part to be appended to the redirection URL, in case start page is different from web app's default document.
portOrderOptional. Lists port number preference order. Should be used when multiple non-80 and non-443 is used as listen addresses.
Returns:
static WebAppConfigEntry UWS.Configuration.Metabase.FindApplication ( Guid  appID) [static]

Finds existing application configuration entry.

Parameters:
appID
Returns:
Returns null if entry does not exist.
static RedirectionConfigEntry UWS.Configuration.Metabase.FindRedirection ( Guid  redirectionID) [static]

Finds existing redirection configuration entry.

Parameters:
redirectionID
Returns:
Returns null if entry does not exist.
static string UWS.Configuration.Metabase.GetDefaultHost ( bool  forIOS) [static]

Returns machine's host name. If forIOS set to True, returns host name in either "machinename.local" or "machinename" format, depending whether machine is a member of a workgroup or a domain. If forIOS set to False, returns fully-qualigied domain name (FQDN) if machine is a member of a domain, or returns machine name, if computer is a member of a workgroup.

Parameters:
forIOS
Returns:
static RedirectionConfigEntry UWS.Configuration.Metabase.GetRedirectionEntry ( Guid  redirectionID) [static]

Finds an existing or creates new redirection configuration entry.

Parameters:
redirectionID
Returns:
static int UWS.Configuration.Metabase.GetRegisteredApplicationCount ( ) [static]

Returns current number of applications registered with UWS.

Returns:

Added to build 15.

static WebAppConfigEntry UWS.Configuration.Metabase.GetWebAppEntry ( Guid  applicationID) [static]

Returns an instance of WebAppconfigEntry that can be used to register an application with the web server.

Parameters:
applicationIDWhen a web application is being upgraded, be sure to keep applicationID the same between different versions of the web application to keep system-assigned listen ports unchanged.
Returns:

This method creates a new or finds an existing WebAppConfigEntry object. To find existing the applications with given application ID must either be currently registered or be listed among previously uninstalled. Since returned instance of the WebAppConfigEntry structure may be describing currently registered or previously uninstalled application, it may come already prepopulated with previously used ListenAddresses and some other data.

static WebAppConfigEntry UWS.Configuration.Metabase.GetWebAppEntry ( Guid  applicationID,
bool  includeUninstalledInSearch 
) [static]

Returns an instance of WebAppconfigEntry that can be used to register an application with the web server.

To register an application, call this method first, and then one of the RegisterApplication() variants.

Parameters:
applicationIDWhen a web application is being upgraded, be sure to keep applicationID the same between different versions of the web application to keep system-assigned listen ports unchanged.
includeUninstalledInSearchTrue to try to find application info among previously uninstalled applications. False to look only at currently registered applications.
Returns:
An instance of the WebAppConfigEntry that can be populated and used to register an applications.

This method creates a new or finds an existing WebAppConfigEntry object. To find existing the applications with given application ID must either be currently registered or be listed among previously uninstalled. Since returned instance of the WebAppConfigEntry structure may be describing currently registered or previously uninstalled application, it may come already prepopulated with previously used ListenAddresses and some other data.

static bool UWS.Configuration.Metabase.HasRegisteredApplications ( ) [static]

Returns False if there are no applications registered with UltiDev Web Server.

Returns:

Added to build 15.
A simple check whether this method returns True does not necesserily ensure that your app installer can uninstall UWS. To be in compliance with the UWS license, ISVs' app installer can uninstall UWS only if their application was the one that installed UWS in the first place. If UWS was installed by the end user, or by another application's installer, your installer cannot uninstall UWS even if there are not applications registerd with UWS.

static bool UWS.Configuration.Metabase.LaunchTheAppInTheBrowser ( Guid  appID,
string  optionalPathAndQueryString = null,
int  timeoutMilliseconds = -1 
) [static]

Opens locally-registered application in the default browser, if application is running.

Parameters:
appID
optionalPathAndQueryStringOptional path relative to application's root.
timeoutMillisecondsAmount of time to keep trying before applications responds. If set to negative value (use with caution), will try until application responds. If set to 0, will try to reach the application only once.
Returns:
True if application found accessible and launched successfully. False if application either has not responded within timeout limits, or browser failed to start.

This function will first ensure that application is accessible, and if it is, it will be launched in the browser. If application is found to be inaccessible, nothing will happen - the method will return false. If application is newly-registered, it may take some time to start the application, so this method will wait for a while for the application to come online, and once it does, it will be launched in the browser. This method is useful for post-registration application start.

static void UWS.Configuration.Metabase.RegisterApplication ( RuntimeVersion  aspNetVersion,
bool  run32bitOnx64,
bool  useDefaultSharedHostProcess,
ProcessIdentity  processIdentity,
WebAppConfigEntry  application,
ICollection< AppShortcut shortcuts 
) [static]

Registers an application and if necessary, a corresponding host process.

Parameters:
aspNetVersionVersion of .NET CLR. Matters for ASP.NET application, but not for static HTML web sites. When registering static HTML sites, please use CLR 2. If true, will run 32-bit on x64 systems. If false, will run as 64-bit on x64 systems.
useDefaultSharedHostProcessIf true, will place application into a default host process. If false, will create a new private host process specifically for the application. More info in the Remarks section.
applicationDefinition of an application to be registered. Should be retrieved using one of GetWebAppEntry() method variants.
run32bitOnx64Set to true if application needs to run as 32 bit on 64-bit systems. Usually it's necessary if application uses legacy 32-bit components, like MS Jet/Access database and other older 32-bit components. Also needs to be set to true if registering ASP.NET 1.1 applications because they ASP.NET 1.1 was created to run as 32-bit on x64 systems.
processIdentityNetwork Service or Local System user. Use Network Service for better security.
shortcutsOptional collection of application shortcut icons to be created during application registration.

Requires elevated/administrative privileges. Using default shared host process is recommended for application targeting consumer and other markets that are likely to have low-end/outdated target computer systems. When using shared host processes, applications use less memory and load faster at the expense of slightly lesser reliability due to potential crashes of host processes caused by other applications sharing same host process. Please keep in mind that each host process can easily use 40+MB of memory just to load .NET Framework, so sharing host process is a good idea for low-memory target systems. However, for applications targeting higher-end servers, using application-specific host processes will ensure better reliability by isolation the application from misbehaving applications.

"NETWORK SERVICE" user - a low-privilege user account that should be used in most situations to achieve better security. This account does not have access to many restricted folders on the file system. Use ServicedComponent of Server type to run components in a different user context. Alternatively, use SystemUtilites.AclFolder() methods to grant Network Service user access to small subset of your app folders. App_Data folder will be ACLed to allow full access to Network Service user.

"LOCAL SYSTEM", a.k.a. "NT AUTHORITY\SYSTEM" - a high privilege user account that should not be used for hosting Internet-facing applications, as well as for hosting applications in other high threat environments. This account has access to most files and folders on disk and to other resources.

static void UWS.Configuration.Metabase.RegisterApplication ( RuntimeVersion  aspNetVersion,
bool  run32bitOnx64,
ProcessIdentity  hostUserIdentity,
WebAppConfigEntry  application 
) [static]

Registers an application with a default host process.

Parameters:
aspNetVersionVersion of .NET CLR. Matters for ASP.NET application, but not for static HTML web sites. When registering static HTML sites, please use CLR 2. If true, will run 32-bit on x64 systems. If false, will run as 64-bit on x64 systems.
run32bitOnx64Set to true if application needs to run as 32 bit on 64-bit systems. Usually it's necessary if application uses legacy 32-bit components, like MS Jet/Access database and other older 32-bit components. Also needs to be set to true if registering ASP.NET 1.1 applications because they ASP.NET 1.1 was created to run as 32-bit on x64 systems.
hostUserIdentityNetwork Service or Local System user. Use Network Service for better security.
applicationDefinition of an application to be registered. Should be retrieved using one of GetWebAppEntry() method variants.

Requires elevated/administrative privileges. "NETWORK SERVICE" user - a low-privilege user account that should be used in most situations to achieve better security. This account does not have access to many restricted folders on the file system. Use ServicedComponent of Server type to run components in a different user context. Alternatively, use SystemUtilites.AclFolder() methods to grant Network Service user access to small subset of your app folders. App_Data folder will be ACLed to allow full access to Network Service user.

"LOCAL SYSTEM", a.k.a. "NT AUTHORITY\SYSTEM" - a high privilege user account that should not be used for hosting Internet-facing applications, as well as for hosting applications in other high threat environments. This account has access to most files and folders on disk and to other resources.

static void UWS.Configuration.Metabase.RegisterApplication ( RuntimeVersion  aspNetVersion,
bool  run32bitOnx64,
WebAppConfigEntry  application,
ICollection< AppShortcut shortcuts 
) [static]

Registers an application with a default host process running under Network Service user account.

Parameters:
aspNetVersionVersion of .NET CLR. Matters for ASP.NET application, but not for static HTML web sites. When registering static HTML sites, please use CLR 2. If true, will run 32-bit on x64 systems. If false, will run as 64-bit on x64 systems.
applicationDefinition of an application to be registered. Should be retrieved using one of GetWebAppEntry() method variants.
run32bitOnx64Set to true if application needs to run as 32 bit on 64-bit systems. Usually it's necessary if application uses legacy 32-bit components, like MS Jet/Access database and other older 32-bit components. Also needs to be set to true if registering ASP.NET 1.1 applications because they ASP.NET 1.1 was created to run as 32-bit on x64 systems.
shortcutsOptional collection of application shortcut icons to be created during application registration.

Requires elevated/administrative privileges.

static void UWS.Configuration.Metabase.RegisterApplication ( RuntimeVersion  aspNetVersion,
bool  run32bitOnx64,
WebAppConfigEntry  application 
) [static]

Registers an application with a default host process running under Network Service user account.

Parameters:
aspNetVersionVersion of .NET CLR. Matters for ASP.NET application, but not for static HTML web sites. When registering static HTML sites, please use CLR 2. If true, will run 32-bit on x64 systems. If false, will run as 64-bit on x64 systems.
applicationDefinition of an application to be registered. Should be retrieved using one of GetWebAppEntry() method variants.
run32bitOnx64Set to true if application needs to run as 32 bit on 64-bit systems. Usually it's necessary if application uses legacy 32-bit components, like MS Jet/Access database and other older 32-bit components. Also needs to be set to true if registering ASP.NET 1.1 applications because they ASP.NET 1.1 was created to run as 32-bit on x64 systems.

Requires elevated/administrative privileges.

static void UWS.Configuration.Metabase.RegisterApplication ( RuntimeVersion  aspNetVersion,
bool  run32bitOnx64,
ProcessIdentity  hostUserIdentity,
WebAppConfigEntry  application,
ICollection< AppShortcut shortcuts 
) [static]

Registers an application with a default host process.

Parameters:
aspNetVersionVersion of .NET CLR. Matters for ASP.NET application, but not for static HTML web sites. When registering static HTML sites, please use CLR 2. If true, will run 32-bit on x64 systems. If false, will run as 64-bit on x64 systems.
run32bitOnx64Set to true if application needs to run as 32 bit on 64-bit systems. Usually it's necessary if application uses legacy 32-bit components, like MS Jet/Access database and other older 32-bit components. Also needs to be set to true if registering ASP.NET 1.1 applications because they ASP.NET 1.1 was created to run as 32-bit on x64 systems.
hostUserIdentityNetwork Service or Local System user. Use Network Service for better security.
applicationDefinition of an application to be registered. Should be retrieved using one of GetWebAppEntry() method variants.
shortcutsOptional collection of application shortcut icons to be created during application registration.

Requires elevated/administrative privileges. "NETWORK SERVICE" user - a low-privilege user account that should be used in most situations to achieve better security. This account does not have access to many restricted folders on the file system. Use ServicedComponent of Server type to run components in a different user context. Alternatively, use SystemUtilites.AclFolder() methods to grant Network Service user access to small subset of your app folders. App_Data folder will be ACLed to allow full access to Network Service user.

"LOCAL SYSTEM", a.k.a. "NT AUTHORITY\SYSTEM" - a high privilege user account that should not be used for hosting Internet-facing applications, as well as for hosting applications in other high threat environments. This account has access to most files and folders on disk and to other resources.

static void UWS.Configuration.Metabase.RegisterApplication ( RuntimeVersion  aspNetVersion,
bool  run32bitOnx64,
bool  useDefaultSharedHostProcess,
ProcessIdentity  processIdentity,
WebAppConfigEntry  application 
) [static]

Registers an application and if necessary, a corresponding host process.

Parameters:
aspNetVersionVersion of .NET CLR. Matters for ASP.NET application, but not for static HTML web sites. When registering static HTML sites, please use CLR 2. If true, will run 32-bit on x64 systems. If false, will run as 64-bit on x64 systems.
useDefaultSharedHostProcessIf true, will place application into a default host process. If false, will create a new private host process specifically for the application. More info in the Remarks section.
applicationDefinition of an application to be registered. Should be retrieved using one of GetWebAppEntry() method variants.
run32bitOnx64Set to true if application needs to run as 32 bit on 64-bit systems. Usually it's necessary if application uses legacy 32-bit components, like MS Jet/Access database and other older 32-bit components. Also needs to be set to true if registering ASP.NET 1.1 applications because they ASP.NET 1.1 was created to run as 32-bit on x64 systems.
processIdentityNetwork Service or Local System user. Use Network Service for better security.

Requires elevated/administrative privileges. Using default shared host process is recommended for application targeting consumer and other markets that are likely to have low-end/outdated target computer systems. When using shared host processes, applications use less memory and load faster at the expense of slightly lesser reliability due to potential crashes of host processes caused by other applications sharing same host process. Please keep in mind that each host process can easily use 40+MB of memory just to load .NET Framework, so sharing host process is a good idea for low-memory target systems. However, for applications targeting higher-end servers, using application-specific host processes will ensure better reliability by isolation the application from misbehaving applications.

"NETWORK SERVICE" user - a low-privilege user account that should be used in most situations to achieve better security. This account does not have access to many restricted folders on the file system. Use ServicedComponent of Server type to run components in a different user context. Alternatively, use SystemUtilites.AclFolder() methods to grant Network Service user access to small subset of your app folders. App_Data folder will be ACLed to allow full access to Network Service user.

"LOCAL SYSTEM", a.k.a. "NT AUTHORITY\SYSTEM" - a high privilege user account that should not be used for hosting Internet-facing applications, as well as for hosting applications in other high threat environments. This account has access to most files and folders on disk and to other resources.

static void UWS.Configuration.Metabase.RegisterRedirector ( RedirectionConfigEntry  redirectionConfig) [static]

Registers redirection from a given set of listen URLs to a new location.

Parameters:
redirectionConfigRedirector definition.
static void UWS.Configuration.Metabase.UnregisterApplication ( Guid  appID) [static]

Unregisteres an application and stops its hosting. Does nothing ig application with given ID is not registered.

Parameters:
appID

Requires elevated/administrative privileges.

static void UWS.Configuration.Metabase.UnregisterRedirector ( Guid  redirectiorID) [static]

Unregisters redirection.

Parameters:
redirectiorID
static bool UWS.Configuration.Metabase.WaitForAppToStart ( Guid  appID,
int  timeoutMilliseconds = -1 
) [static]

Allows waiting for an application to come online. Returns true when application responded, and false if timed out or application not found.

Parameters:
appID
timeoutMillisecondsIf negative, will be trying indefinitely. If 0, will make one attempt to reach the app, and if positive, will be making attempts for the duration of the specified time period.
Returns:
 All Classes Namespaces Functions Enumerations Properties