Overview

When you render a chart's image using either an image, or input tag, the chart's image is automatically saved to a file. By using advanced storage capabilities, Dundas Chart for ASP.NET gives you a great deal of flexibility for managing chart image files and other resources within a web application.

Using the Chart HTTP Handler

The Chart HTTP Handler is used to assist in processing Chart requests. It has several advantages:

• Reduces hard drive operations by storing temp files in memory.
• Provides options for specifying a timeout, after which temp files are overwritten.
• Reduces temp file collisions in web-farm environments.

• When the chart assembly is added to the project, the ChartHttpHandler is automatically added to the web.config file (Figure 1). 

•  

  

  Figure 1: Chart HTTP Handler.

•  

  In addition to the HTTP Handler node, the Chart adds a key into the appSettings section of the web.config file (Figure 2). The value of this key specifies options for the Chart HTTP Handler.

•  

  

  Figure 2: Specifying Chart HTTP Handler Options.

•  

  Using the Storage attribute, you can specify whether to store the temp files in memory or as a file. It is up to you to decide the type of storage that best suits your available resources. There are two possible values for Storage:

  • Memory: The temp files are stored in memory. This is enabled by default.
  • File: The temp files are stored at a file location. You must specify a Url corresponding to a path on the local machine. If an incorrect value is defined for this Url property, then an exception will be thrown.

   

• Optionally, for users who are viewing the chart in web-farm environments, you can specify a value for the Dir attribute. This corresponds to the folder location of a server path for which all temp images are stored. The Url should specify an HTTP path. This approach is recommended for web-farm environments that use a central repository to store temp files. To prevent chart images from being overwritten, a unique machine ID is assigned to each temp file request.

  The Timeout attribute corresponds to a "time to live" (in seconds) for temp files. Thus, a generated file that remains for a longer period of time than the Timeout is subject to be overwritten in the order it was created. For example, if the Timeout is set to 360, and File1 has been stored for more than 360 seconds (6 mins), the next file created will overwrite File1.

• If you set Timeout to 0, no event will be written into the Event Log.  This is important in scenarios where you do not deploy your application to a machine because the end user does not have administrative privileges.

Image Storage Mode

The ImageStorageMode property defines the type of storage that will be used when the chart is rendered as an image. By default, this property is set to Auto, meaning that the ChartHttpHandler will be used if it is present in the configuration file. If you wish to always use the storage features of the ChartHttpHandler, you can set ImageStorageMode to UseHttpHandler.  

Working With Chart Images

The ImageUrl property is used to determine either the absolute, or relative, location of the file as well as its name and file extension. These elements are all automatically added to the image's URL depending on the image type specified.  

For more information on rendering chart images, see the topic on Rendering Methods.

There are three methods for using the ImageUrl property:

1. Using a Single File Name

If you provide one file name for the ImageUrl property, then this file may be overwritten by another chart request before the original request is sent to the client. However, if the chart is not frequently updated (e.g. if the chart is updated on a daily basis), then using one file name for the chart image will suffice. This method should only be used when the chart image rarely changes.

2. Using Unique File Names With UIDs

To prevent chart image files from being overwritten, use a unique file name for each chart generated. The simplest way to do this is to insert the #UID string into your file name. This ID string will be replaced with another unique ID every time that the chart is saved to a file.

For example, if you set ImageUrl to "Temp/ChartPic_#UID" the file name will actually be "Temp/ChartPic_cf5941dc-d1e9-474b-bb19-b85739585336.jpg". Now each time that you generate a new chart it will get saved using a unique file name.

Using unique file names eliminates the possibility that the chart image files could be overwritten before they are sent to the requesting client. However, this method also introduces a new problem; each time you generate a chart a new file is created, which will have to be deleted at some point in time. While it is true that this method will ensure that users are always sent the correct chart image file, you must be mindful that these image files must be deleted manually from the server.

Note
Due to the inherent overhead incurred in using this method, we recommend you use the Round Robin approach described below.

3. Round Robin (This is the default method)

You can define, and use, a sequence of file names for your chart images. Each time a chart is generated the next file name in the sequence will be used. When the end of the sequence has been reached, the process repeats with the first file name being used again.

This method allows you to have control over the lifetime of the image files, and it will not create any more temporary files than the sequence length requires.

To define your file name sequence you must insert the string #SEQ(300,5) into your ImageUrl property. The first number parameter (300) defines the length of the sequence (i.e. maximum number of temporary image files), the second number parameter (5) defines the required "time to live" for the file in minutes. If the file is overwritten, and the life span of that file was less than this second value, then a warning message will be inserted into the Event Log. For example, if you set ImageUrl to "Temp/ChartPic_#SEQ(300,5)", the file names will become:

Temp/ChartPic_000001.jpg, Temp/ChartPic_000002.jpg, ... , Temp/ChartPic_000300.jpg.

If you reduce the sequence length, then there will be fewer files created, and as a result this will require less hard drive space. On the other hand, reducing the sequence length also means that these image files will be overwritten more frequently. For example, if the sequence length is a 1000, and there are 500 visitors an hour at a web site, then each chart image will exist for approximately two hours before being overwritten. This may, or may not, be acceptable to you.

You can also set the required "time to live" parameter (the second parameter). You should note that setting this parameter, to say 5, does not guarantee that the file will be available, or that it will not be overwritten for 5 minutes. Instead, this function will check the "live time" of the file just before it is overwritten, and if it finds that this time was less than specified value, a warning message will be inserted into the Application Event Log. When this occurs, the allowable number of files can be increased to handle a greater amount of traffic occurring at the web site at that time.

To solve a caching issue within Internet Explorer, a GUID is applied to the image URL.

This GUID is similar to:

"ChartPic_000002.jpg?4ea19276-5cb8-4f55-9d8f-8fe9c542de5".

If you want to generate a chart without the GUID appended to it, simply use the keyword #NOGUIDPARAM.

Example

This example demonstrates the syntax used when you want to avoid adding a GUID to a chart image's name.

  myFileName#SEQ(x,y)#NOGUIDPARAM
        

This method does not require that image files be deleted manually from the server.

Caution
The Chart control may be unable to insert warnings into the Event Log because of security settings present on your system. Please check your security settings to avoid an issue.

 

Finding An Image File Name

When using one of the file naming strategies the actual file name is not known when the chart is being created. In some situations, this name is needed and can be found using the method, GetCurrentImageUrl, from the Chart object.

When you use one of the above mentioned methods, or naming strategies for storing and rendering your chart images, the actual names of the image files are not known until the chart has been created. In some cases, you may want to have the image file name, and in such cases, use the GetCurrentImageUrl method of the Chart object to get the image file names as required.

Example

This example demonstrates the syntax for retrieving the file name of an image file at run-time.

Visual Basic	Copy Code
Imports Dundas.Charting.WinControl ... ' Retrieving the file name. Dim filename as String = Chart1.GetCurrentImageUrl()

C#	Copy Code
using Dundas.Charting.WinControl; ... // Retrieving the file name. string filename = Chart1.GetCurrentImageUrl();

See Also