This documentation is for the old version. Go to the latest Graphics Mill docs

Image Cache Management (AJAX Controls)

When using the BitmapViewer AJAX control, we need to store the image data between sessions. The standard approach in ASP.NET is using a System.Web.UI.Control.ViewState (i.e. save the necessary data in the HTML page). However since the images are typically too large, this approach is not good because of huge overheads.

That's why Graphics Mill for .NET implements another approach - saving the temporary images in the special folder at server disk, called an image cache.

The Public and the Private Cache

Image caching is used for two tasks, and that's why the AJAX Controls of Graphics Mill for .NET have two caches:

Public Cache. This cache stores the images which are sent directly to the browser. E.g. it can be a low-resolution preview image, and visible portions of entire image.
Private Cache. It stores the original image between server calls. For better understanding, let's examine how it works:
1. When user enters the page which contains the BitmapViewer control, the server event Page_Load is raised. As usual this event is used to initialize the control, including the image loading.
2. When page is prepared to be sent to the client (i.e. Page_Render event), the image is saved into the private cache.
3. When the postback occurs, and the server code is running again, the image is loaded from the private cache back to the Bitmap property. So you can operate with it transparently, as if it was never unloaded.

Setting the Private and the Public Cache up

Graphics Mill for .NET AJAX Controls automatically create image cache in the App_Data/GraphicsMillAjaxCache and allow to work with it without any additional settings. The image cache management mechanism for the BitmapViewer is performed via the HTTP module. If necessary, you can override the cache location using web.config in the same way as described below.

To set the image cache up, you should use Aurigma.GraphicsMill.AjaxControls section of the web.config file of your application. To do it, declare this section in the configSection tag. After that you should insert the Aurigma.GraphicsMill.AjaxControls section and put necessary keys as described further. As a result, the web.config should be looking like that:

XML

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  
  <configSections>
    <section name="Aurigma.GraphicsMill.AjaxControls" 
    type="System.Configuration.NameValueSectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
  </configSections>
      
  <system.web>

    <!--  
    ...
    other settings
    ...
    -->
  
  </system.web>

  <Aurigma.GraphicsMill.AjaxControls>

    <!--  
    ...
    Settings of web controls including cache options
    ...
    -->

  </Aurigma.GraphicsMill.AjaxControls>
  
</configuration>

Image Cache Paths

To specify the path to the public and private cache use the following keys:

RelativePublicCachePath - URL to the public cache folder.
RelativePrivateCachePath - URL to the private cache folder.

These URLs should be specified relatively the site root and begin from the forward slash character (/).

Also, if you do not want to have the private cache inside the site root, and prefer to specify physical path, use the AbsolutePrivateCachePath key. However you cannot specify absolute path for the public cache, because it is sent to browser, and therefore should point to some folder inside your web site.

Note

If you specified relative path to the private cache, you should not use absolute path, and vice versa.

Here is an example of these keys usage:

XML

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  
  <configSections>
    <section name="Aurigma.GraphicsMill.AjaxControls" 
    type="System.Configuration.NameValueSectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
  </configSections>
      
  <system.web>

    <!--  
    ...
    -->
  
  </system.web>

  <Aurigma.GraphicsMill.AjaxControls>
    <add key="RelativePrivateCachePath" value="/AjaxControls/GraphicsMill/PrivateCache/" />
    <add key="RelativePublicCachePath" value="/AjaxControls/GraphicsMill/PublicCache/" />    
  </Aurigma.GraphicsMill.AjaxControls>
  
</configuration>

Do not forget to set up proper permissions for these folders. Both of them should have modify permission for the user the ASP.NET process is running under. On Windows NT/2000/XP this is typically an internet user (IUSR_<machinename>) and ASPNET account. On Windows 2003 grant modify permission to NETWORK SERVICE group.

Cache Cleanup

When cached files are no longer needed, Graphics Mill for .NET removes them. The file is removed from the cache when:

The maximum life time of the file exceeded. To specify it, use PublicCacheMaxLifeTime/PrivateCacheMaxLifeTime keys. These keys specify the life time for private/public cache in seconds.
The maximum file count of the cache exceeded. In this case the oldest file is removed and new one is written instead of it. Use PublicCacheMaxFileCount/PrivateCacheMaxFileCount keys to specify it.

Since public and private caches have absolutely different intent, you should use different cleanup policies for them. Use the following considerations when choosing these settings:

Public cache is used only to deliver the visible portions of images to the browser. That's why you need not set long life time for the public cache since these files are not necessary after browser downloads them. For example, you can specify 5 minutes to guaranty loading the image even by users with slow modem connection.
Also, since there are quite large number of such files, especially if user zooms and scrolls the image intensively, it is recommended to specify big value here.
Unlike the public cache, the private cache should be stored quite long time. As a matter of the fact, you should guaranty that the image will be kept long enough while user updates the image (e.g. by applying some effect). That's why you should specify large life time, e.g. 20 minutes.
As for file count, there are much less files stored in the private cache. That's why you can specify smaller value than for the public cache.

The full example of cache settings is below:

XML

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  
  <configSections>
    <section name="Aurigma.GraphicsMill.AjaxControls" 
    type="System.Configuration.NameValueSectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
  </configSections>
      
  <system.web>

    <!--  
    ...
    -->
  
  </system.web>

  <Aurigma.GraphicsMill.AjaxControls>
    <add key="RelativePrivateCachePath" value="/AjaxControls/GraphicsMill/PrivateCache/" />
    <add key="RelativePublicCachePath" value="/AjaxControls/GraphicsMill/PublicCache/" />    

    <add key="PrivateCacheMaxLifeTime" value="1200" />
    <add key="PrivateCacheMaxFileCount" value="200" />
    <add key="PublicCacheMaxLifeTime" value="300" />
    <add key="PublicCacheMaxFileCount" value="500" />
  </Aurigma.GraphicsMill.AjaxControls>
  
</configuration>