Share via

Image File Management (Chart Controls)

  • Article

When the RenderType property is set to ImageTag, the Chart control saves the rendered chart images as files in memory or on disk (For more information, see Chart Image Rendering). You can specify how the Chart control manages the image files. To do this, use the ImageStorageMode property.

In the ImageStorageMode property, you choose to use the chart HTTP handler to manage image files or to manage them manually.

Using the Chart HTTP Handler

By default, the ImageStorageMode property is set to UseHttpHandler. This causes the Chart control to use the ChartHttpHandler that is registered in the Web.config file to manage the rendered chart images.

Use the chart HTTP handler to:

  • Prevent file override collisions in a server cluster or a multiple-process site.

  • Protect the security of rendered chart images by preventing users from downloading chart images that are rendered for other users.

  • Reduce disk operations by storing image files in memory or other storage options, such as Microsoft SQL Server.

Usage

When you drag a Chart control from the Toolbox onto the design surface of the ASP.NET page, the ChartHttpHandler is automatically registered in the Web.config file as "ChartImageHandler". You can configure ChartImageHandler's behavior in the <appSettings> element. The applicable code section is provided below with the automatically generated settings:

<appSettings>

<add key="ChartImageHandler" value="storage=file;timeout=20;dir=c:\TempImageFiles\;" />

</appSettings>

Use the parameters in the value attribute to configure the chart HTTP handler. See the table below for a description for each parameter.

Parameter Description

storage

Storage mode. Three options are available:

  • file: Store the rendered chart images as temporary files. You must also specify the storage location in the url or dir parameter. In a server cluster or a multiple-process site, you must specify the dir parameter.

  • memory: Store the rendered chart images in the memory space of the running process. Do not use this option in a server cluster or a multiple-process site.

  • session: Store the rendered chart images in a session variable.

url

The relative URL of the image storage location. If the dir parameter is specified, it is used instead of url.

The default value is "~/".

dir

Absolute directory path of the image storage location. This can be either a local path or network path. In a server cluster environment, use a network path to keep the temporary files in a shared location. Each temporary file is assigned with a unique machine ID to prevent the files from being overridden inappropriately.

timeout

The timeout period in seconds for rendered chart images. After this period has elapsed for an image, it may be replaced by a newer image.

The default value is 30.

handler

A custom IChartStorageHandler implementation. The value should be formatted as a fully qualified assembly name. For example: MyNamespace.MyClass.MyHandler.

privateImages

Privacy protection. When set to true, the generated image can only be downloaded by its owner if some of the following types of identifications are enforced:

  • The user is authenticated.

  • AnonymousID is enabled.

  • SessionID is available.

The default value is true.

deleteAfterServicing

Whether the image should be deleted after successful download from a client.

The default value is true.

webDevServerUseConfigSettings

Whether to store rendered chart images in memory when running the application in full trust level using the Visual Studio development server.

The default value is true. This may mean that your settings in the Web.config file have no effect when you run the ASP.NET application from Visual Studio.

Configuration Settings in Different Trust Levels

The following is list of trust levels and how the trust levels affect the configuration settings in the Web.config file.

  • Full trust: All configuration variations apply.

  • High trust: The ASP.NET Development Server cannot be detected. Therefore, webDevServerUseConfigSettings has no effect.

  • Medium trust: Same as high trust.

  • Low trust: Same as high trust, except that file access is forbidden. The storage parameter must be set to session or memory.

  • Minimal trust: Same as low trust, except that the chart HTTP handler detection fails. This means that the ChartImageHandler key in your Web.config file is mandatory.

Managing Images Manually

To manage rendered chart images manually, set the ImageStorageMode property to UseImageLocation, and then set the ImageLocation property to an absolute or relative path.

Note

In this mode, each Chart control manages its one image storage independently.

The ImageLocation property can contain the path as well as certain keywords. For example: "~/Temp/ChartPic_#SEQ(300,5)". This string is made up of three elements:

  • The absolute or relative directory path. For example: "~/Temp/".

  • The file name, or the leading text of all image file names. For example: "ChartPicture_".

  • A keyword. For example: "#SEQ(300, 5)".

ImageLocation Without Keywords

If you specify an image location without a keyword, the Chart control uses a single file all image rendering. The resulting file path is the directory with leading text that you specify and the file extension specified in the ImageType property. For example: "~/Temp/ChartPicture_.png".

Note that if the chart data or appearance changes frequently, the image file may be overridden before it is sent to the client, causing the client to receive the incorrect image. To avoid this issue, use one of the keywords.

ImageLocation With Keywords

You can insert three different keywords into the ImageLocation property.

Keyword Description

#UID

Generate a unique identifier for each rendered chart image. For example: "~/Temp/ChartPicture#UID".

Using this keyword ensures that the server replies each page request with the correct rendered image. You must manually remove old files. Otherwise the number of files will grow indefinitely.

#SEQ(maxFiles,minutes)

Generates a file sequence number, up to the number defined by maxFiles, then start the sequence again and replace the first file in the sequence. For example: "Picture_#SEQ(300,5)" generates the following file names (assuming ImageType set to Png): Picture_000001.jpg, Picture_000002.jpg, ...

The minutes parameter specifies the timeout for each file in the sequence. However, it does not guarantee the validity of a filename for the specified period. If a file is recycled before its timeout period is exceeded, the file a warning message is inserted into the Application Event Log. You should set the maxFile parameter to a reasonably large number to avoid image files being overridden inappropriately.

#NOGUIDPARAM

Removes the GUID string from the image file's URL. For example: "Picture_#SEQ(300,5)#NOGUIDPARAM".

By default, the Chart control adds a GUID string to the image URL.

Image Type and Compression

To specify the image type when the chart images are saved in temporary files, use the Chart control's ImageType property. If you set this property to Jpeg, you can also specify the JPEG compression in the Chart control's Compression property.

See Also

Concepts

Chart Image Rendering

Other Resources

Using Chart Controls