Documentation

SETUP

A little scripting required, read on....

The Session Object

For all frameworks, the Session object has the same properties/methods.

The Application Cache Object

Achieve amazing scalabilty using ISP Global Cache. Available for Classic ASP (COM component), ASP.NET and ASP.NET Core

Redis

If you never have installed Redis server before, you probably want to go with the defaults and download our Redis Microsoft-fork for Windows, or download it and compile it directly from the Redis website
Our version works well with the Windows configured defaults. The zip contains a install.CMD , run this as an Administrator and check if Redis keeps on running. If it does not like the environment (memory etc), it will stop executing and report it in the eventlog. Add --loglevel verbose in the .CMD file enable logging. If you have customized Redis to your wishes, such as master-slave, encryption, using a password or you use multiple endpoints, contact us if you experience any issues.

ISP Session COM (classic ASP)

ISP Session comes as a ZIP archive, containing a demo and 2 COM dll's and an install vbs script (RegisterCOM.vbs)
RegisterCOM.vbs can be clicked and started. It verifies if your Windows machine has the Visual C++ 12 runtime (msvcr120.dll), and downloads and executes the setups if needed.
After that, both 32-bits and 64-bit COM dlls are registered. It would be safe to reboot in case the Visual C++ runtime was updated to the latest version.

To get started with ISP Session for classic ASP pages, basically,

  • Download the Demo
  • Run RegisterCOM.vbs
  • Study the demo.
  • Take the include file (ispsession.asp), include it, in your page(s)
  • Make sure that the IIS built in ASP session state is disabled as well for the website on which you will deploy.
  • Copy the web.Config from the Demo or -modify- if you have mixed classic ASP pages within your .aspx environment (this is possible)
    The demo web.Config is good to start with, but later on, you need the license information and probably, you might need to modify the session cookie settings and such.
  • If Redis is on a remote machine, make sure you modify the web.Config appSetting: key="ispsession_io:DataSource" value="remoteserver:6379"/>
The most work, is when you have to add the include file for each asp page that requires a session. However, if you already include another file, you can modify and use that file and merge the scripts from ispsession.asp from the demo.

In the past, some have upgraded ISP Session from previous versions (say, 5.1) or written their own scripts and used CreateObject("NWCTools.CSession") instead of Server.CreateObject("NWCTols.CSession") the 'Server.' prefix IS required.

Classic ASP does not work with web.Config, normally it works with global.asa. However, our COM component, shares settings with ASP.NET and also parses appSettings, it does not read appsettings.json

 

ISP Session Core.Net

From the nuget package console in Visual Studio run install-package ispsession.io.core. The assembly will be added, however, appsettings.json is not modified automatically.
Add the file if it does not exist in the root of (where project.json is) your site, and merge or use the sample below.

   "ispsession.io": {
    "AppKey": "F01FB5D0BCA6CE4C8CC773916F281C32",
    "CookieName": "GUID",
    "Path": "/",
    "Domain": "",
    "SnifQueryStringFirst": true,
    "CookieNoSSL": true,
    "Liquid": false,
    "CookieExpires": 0,
    "ReEntrance": true,
    "SessionTimeout": 30,
    "HASH_SESSIONID": false, // for classic asp, some use Session.SessionId to be numeric
    "Compress": false,
    "Csession.LIC": "mydomain.local",
    "License": "F01FB5D0BCA6CE4C8CC773916F281C32",
    "DatabaseConnection": "localhost"
  },
                        
After adding appsettings.json, open startup.cs and merge these lines below:
public void ConfigureServices(IServiceCollection services)
{
    //other code omitted
    services.Configure<SessionAppSettings>(Configuration.GetSection("ispsession.io"));
    services.AddISPSession();
}
And finally, merge the code below
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
//other code omitted for simplicity
app.UseISPSession();
}

ISP Session classic ASP.NET

This plugin is quite easy to install. After running install-package ispsession.io the assembly is added, and web.Config is modified with defaults.
Only the appsetting in web.Config named ispsession_io:DataSource must be modified if Redis is not installed on the local server.

 

Configuration

For ISP Session COM and ISP Session Classic ASP.NET the variables, are 'shared' in web.Config. For the version of AspNetCore, you should ignore the ispession_io: prefix, which is used in web.Config to avoid name conflicts with other applications.

Setting name Description
AppKey Configure this with any Hexadecimal GUID (32-length) that you want. Only websites that have the same App_Key can share a session
CookieName The name of the Session cookie. Defaults to 'GUID'
Path Cookiepath; Defaults to '/'. This is the cookiepath and it limits a cookie to specified virtual path of your website.
Domain DOmain of the CookiePath. Defaults to empty. Set this to e.g. .domain.com to limit the cookie domain scope.
SnifQueryStringFirst If set to true, the Cookie identified by 'CookieName' would first be identified from the URL, if it is available. This also means that it takes preference and can overwrite a Session cookie with the one from the URL
CookieNoSSL this limits the session cookie to https only (default true)
CookieExpires A number in minutes, e.g. 43200 for 30 days. Leave empty for Session cookies, not stored on customer devices
ReEntrance Must be set to true, if a session was not established by a cookie, but by a URL, also 'revives' a session, if it does not exist anymore (does not restore data).
Compress Only supported in ISP Session for classic ASP.NET, do not set if you share session with classic ASP
HASH_SESSIONID Available only for classic ASP. If you set this to true, Session.SessionID will return an integer, instead of the SessionID as a hexadecimal GUID.
Liquid If you set this to true, the Session Cookie is regenerated at each request. Protects agains replay attacks.
Csession.LIC This will contain all the active directory domains, workgroup names, or server names or workstations that are included in the license.Each line is xml encoded by a new line
DataSource A Redis server string, separated by comma's if you have multiple endpoints, such as remoteserver:myport or append a password password@remoteserver:myport.

Session Object and usage

The session object is common among the three frameworks, where it differs, it is indicated. I don't make distinction between VBScript syntax and C#.
So it is required knowledge that Session(key) = value is VBScript syntax and Session[key] = value; is C# syntax.

Also note there is NO support for ASP.NET Core 1.0. Support starts at 2.0 for Session interoperability. Application Caching support is not yet build

Session[key] = value; This gets or sets a session value of most supported types, such as string or integer or even class instances (COM, classic ASP)
Session.Timeout = 30 Sample above sets or gets timeout in minutes. Note, the default is configurable through web.Config or appsettings.json (.NET Core)
Session.Codepage = x Not supported/deprecated, do not use. Codepage can be set in classic ASP, through a page directive (eg <%@ lcid="1033"%>)
Session.LCID = x Not supported/deprecated, do not use. LCID can be set in classic ASP, through a page directive (eg <%@ codepage="65001"%>)
Session.StaticObjects Not supported. Using CreateObject or new instance of a class, in place, is a common practise. Classic ASP: You can create static objects, though, on Application Level in global.asa, if you wish
Session.Contents Property. Returns a reference to a VariantDictionary, e.g. Session.Contents[key] = value;, has the same effect as Session[key] = value;
In addition, the VariantDictionary has some additional properties, such as Session.Contents.Exists(key) returning a boolean or Session.Contents.VarType returning the Variant data type(number), or Session.Contents.Count which returns the number of Session Items available.
Session.IsExpired Property. Boolean Identifies if Session cookie exists but the session no longer exist at the serverside.
Session.IsNew Property. Boolean identifies if session just was created at current browser request.
Session.LiquidCookie Property. boolean (get/set) identifies if the cookie must/is refreshed at each browser request. Offers extra layer of security.
SEssion.ReEntrance Property. Boolean (get/set/) identifies if the cookie can be set through URL and thus be resumed while there was no session -cookie-
Session.URL(path) Property. VBScript only. Helper function. Returns a wrapped URL having the specified CookieName in the QueryString. E.g.<%=Session.URL("mypage.asp?i=1")%> would result in mypage.asp?i=1&GUID=[sessionid]
Session.Execute(path) Executes specified asp page (VBScript only). You cannot use Server.Execute, since that would not deal correctly with the session replacement.
Session.CreateInstance(ProgId) Function, VBScript only. This helper function, initiates a COM object by progid, and initializes it. When it is IIS context compatible, it invokes OnStartPage and passes the IIS scripting context (if possible)
Note that the .NET versions, also in case of COM objects, tries to invoke OnStartPage, which is legacy, but still supported within IIS context.
Session.Statistics(appkey, (optional) guid) Not yet supported today. Returns a dictionary enumerated all sessions, having size, timeout and expiration information.
Session.EnsureURLCookie Method. VBScript only. Makes sure that the current .asp page, has a GUID in the URL, redirects to current page including the GUID if necessary.
Session.OldSessionID Property. Returns the old cookie, which you might need in case the Liquid feature is 'on' and you need a reference to the previous SessionId value.
Session.ReadOnly Property. Returns the state of the session if the session was set readonly by using a page directive (ASP.NET) @page EnableSessionState="ReadOnly"
You also can set this property to 'true' in code, but this must be done before any variable was modified. Any attempt to modify the session state in code, will result in an exception.
Session.Abandon Method. Removes the current session cookie, and at page cleanup time, it will remove the Session state from Redis server.
 

Cache Object and usage

The Cache object is common among the three frameworks, where it differs, it is indicated. I don't make distinction between VBScript syntax and C#.
So you are assumed to know that Session(key) = value is syntactically in VBScript while Session[key] = value; is C# syntax.

[Set] Cache[key] = value;
[Set] value = Cache[key];
This gets or sets a Cache value of most supported data types, such as string or integer or even class instances (COM, classic ASP).
The Cache object is highly optimized. It only serializes keys that are dirty (changed), added or removed. When no item is added or removed, Redis is queried only at page initialisation.
Classic ASP.NET 4.5.2
- 4.7.2
ASP.NET Core 2.1 +
var keyName = Cache.Key(1); Retrieves the keyname as a string, by position. Note that the index is 1 based.
var numberOfKeys = Cache.Count(); Retrieves the number of items inside the Cache dictionary.
for(var x = 1; x <= Cache.Count(); x++)
{
var myKey = Cache.Key(x);
}
foreach support The Cache object, supports iterating using a foreach statement like:
foreach(var key in Cache)
{
var myValue = Cache[key];
}
Cache.Remove([key]); Removes the specified key from the collection. The key is removed from Redis when the ASP causes the 'OnEndPage' event
Cache.RemoveAll(); Method. Removes all keys that are in the dictionary of the current Cache instance. The keys are removed from Redis when the ASP causes the 'OnEndPage' event
Cache.ExpireKeyAt([key], [ms]); Method. Expires the specified key given the argument 'ms' in milliseconds.
e.g. Cache.ExpireKeyAt("myKey", 10000); // key 'myKey' will be removed by redis after 10 seconds.
var keyExists = Cache.Exists([key]); Function. Boolean Identifies if the specified key exists in the current instance of Cache. When executing this function, the key is not created at redis.
var myType = Cache.VarType([key]); Function. Short value. Identifies the type of OLE Variant that is stored for the specified key. e.g. When you set Cache["mykey"] = "Hello World", Cache.VarType("mykey") will return 12, int32 (long) would be 3 and int16 (integer) 2, object 9. See VARENUM at msdn.microsoft.com for the full specification.
Cache.LockKey([key]); Method. Locks the specified key until the page runs the event 'OnEndPage' or UnlockKey is used. You would use this feature, when only one page can access the key and value while others have to wait until the key is unlocked.
We use the Redis 'RedLock' algorithm for this.
Cache.UnlockKey([key]); Method. Unlocks the specified key.