.netCHARTING v10.5 Documentation
File Handling

Overview

.netCHARTING includes advanced file handling designed to ensure your charting applications works reliably without the need for special settings.  For most users, the default file handling options will meet your needs.  Those with advanced requirements can go beyond the intelligent defaults and finely tune their file and image handling for their specific needs.  In addition to common properties at the chart level, .netCHARTING includes a file manager class for more advanced file handling.


Cleanup management

Typically .netCHARTING creates a new chart image dynamically for each request.  This image is written to disk in a temporary (temp) directory on your web server and an image reference is returned.  The result is that the client (web browser) requests the aspx page from the server which renders the chart image and then returns an image reference in HTML.  The browser will then request the image file which is served from the web server.  This scenario outlines the highest performing option for dynamic chart deployment.  Since each request generates a unique chart file which could over time result in wasted space .netCHARTING includes an automated cleanup system which will delete automatically generated files on a regular basis.  The default period is 15 minutes and it can be set to any value in minutes through the Chart.CleanUpPeriod property.  If set to 0 the cleanup feature will be disabled.  Cleanup management is based on 2 settings and can be set independently on a per temp directory basis.  As a result, each temp directory setting can have its own independent cleanup period if required.  If you mistakenly set different cleanup periods for different scripts that reference the same temp directory the last setting would be used and it would not cause any problems.


Filename generation

When not specified with the Chart.FileName property a random filename is generated to ensure using .netCHARTING is a easy and seamless as possible.  All file names generated by the system will be prefixed with dnc and followed by a series of letters and numbers e.g. dnc-5irim3i3.png


Temporary Directory Support

Using the Chart.TempDirectory property you can specify the relative, absolute or physical path which is used for a given charts images.

Examples:

The following examples assume you have a web site (www.site.com) located at c:\inetpub\wwwroot\site1 and an aspx page at c:\inetpub\wwwroot\site1\app1\sub\chart.aspx

 

 

Setting  Writes file to Returns link of Loading image from
/temp c:\inetpub\wwwroot\site1\temp /temp/dnc-123.png www.site.com/temp/dnc-123.png
temp c:\inetpub\wwwroot\site1\app1\sub\temp temp/dnc-123.png www.site.com/app1/sub/temp/dnc-123.png
../temp c:\inetpub\wwwroot\site1\app1\temp ../temp/dnc-123.png www.site.com/app1/temp/dnc-123.png
../../temp c:\inetpub\wwwroot\site1\temp ../../temp/dnc-123.png www.site.com/temp/dnc-123.png
C:\temp C:\temp C:\temp C:\temp


This latter case (C:\temp) would not work in a web environment unless the
physical path is within the web root and accessible to the site.  Typically
physical paths such as c:\temp should not be used.


Browser Cache Defeating

Since it is possible a fixed file name could used for dynamic content, the browser could show an older version because of image caching at the client (browser) level.  To prevent this .netCHARTING defeats the browsers image cache by returning a random query string with the image reference.  This ensures that clients will load the latest image generated by .netCHARTING even if the same filename is used.


Static filename support

A static filename enables you to select the name used for the chart.  When setting a static filename with Chart.FileName each generation will override the last and only a single file will be used for that chart.  The filename is provided without extension, which is determined based on the image format selected (see “Multiple image output formats” below for more information).

Output and Fragment caching integration

ASP.NET includes powerful caching features integrated deeply with  the architecture of Internet Information Server 6.0 (web server software).  .netCHARTING works seamlessly with both output and fragment caching and samples are provided working with both.  Output caching enables your entire page including charts to be cached, to work with output caching you need only implement it in your page and set your charts to a specific filename with static filename support.  For cases where you only wish to cache the chart and not the other page content fragment caching may be used.  Please see outputcache.aspx and fragmentcache.aspx in the feature samples for usage details.


Direct streaming (no file) support

Since disk based charts offer higher performance and more flexibility they are the preferred method of chart image generation.  However, in addition to advanced file handling support it is also possible to stream charts directly to the browser.  In this case no physical file is written to disk. 

There are differences in the way the control can be used between these two image return methods. When using a file reference, you are free to treat the page as you normally would, including HTML and any other web content on the page.

If you are streaming the image back, only the control call should exist on the page because no other HTML will render. This is not a limitation of .netCHARTING but rather specific to the way the HTTP protocol works. Each request is served separately (as such a request to a web site with 3 images is actually 4 unique requests to the web server and the browser does the job of assembling those 4 items into the single web page you see.

Because streaming images does not allow HTML, setting url and tooltip properties of elements on the chart will have no effect.  See streaming.aspx for sample usage.  Also see streamingusage.aspx for a page which consumes the streaming image.  When you request streaming.aspx it is the same as requesting an image file directly.  Streamingusage.aspx shows how this aspx page can be referenced as an image within a page so other HTML elements can be included.

Note: Disk based charts offer higher performance and more flexibility -
they are the preferred method of chart image generation.  Streaming
should only be used if you have a specific need for it.


Multiple image output formats

.netCHARTING supports multiple image formats for output, set with the Chart.ImageFormat property.  PNG is most commonly used as it provides high quality lossless charts.  Jpg is useful when using image backgrounds as it can generate a smaller file size.  When using jpg you can adjust the quality and level of compression with File Quality property of the file manager which accepts values from 0 to 100.  Other supported types include vector output (wmf and emf), tif, and bmp.

Tip: PNG tends to produce the best looking output for most charts however
if your chart includes an image background , consider JPG as it will produce
a smaller file size.  See sample bevel.aspx for an example.


Direct bitmap access

In addition to having the chart control return a built in reference to the generated image, you can directly access the chart bitmap for your own advanced uses.  See sample postrenderdrawing.aspx which demonstrates obtaining the chart bitmap, making changes to the bitmap and saving the results with the file manager.  Using the file manager enables complex tasks to be nearly as simple as using the built in file management since it handles creating a file name and returning a control referencing the newly generated chart image.


Legend and chart area image splitting

In addition to returning the entire chart image as a bitmap, you can also return just the legend with GetLegendBitmap.  The advanced image map functionality even allows you to use .netCHARTING generated image maps for tool tips and URL’s on images returned independently from the control so you can place them freely in your page.  See imagemaptext.aspx for a complete sample.