What the Class Is Used For

Use Chilkat.Cache when an application needs a simple persistent disk cache. Each cached item is identified by a unique key. For web pages, the key is typically a canonicalized URL; for other uses, it can be any unique identifier chosen by the application.

Store Binary or Text Data Save byte arrays, BinData, or text strings with optional expiration and ETag metadata.

Fetch Cached Items Retrieve cached content as byte arrays, text strings, BinData, or StringBuilder.

Manage Expiration Store items with no expiration, RFC822 expiration strings, or CkDateTime expiration values.

Clean the Cache Delete a single item, all items, expired items, or items older than a specified date/time.

Typical Workflow

Create a Cache object.
Call AddRoot once for each cache root directory.
Optionally set Level to control whether cache files are stored directly in the root or distributed into subdirectories.
Save an item with one of the Save* methods, using a unique cache key, optional expiration, optional ETag, and item data.
Check whether an item exists with IsCached, or fetch it with a Fetch* method.
After fetching, inspect properties such as LastKeyFetched, LastEtagFetched, LastExpirationFetchedStr, and LastHitExpired.
Periodically remove expired or old cache entries using DeleteAllExpired, DeleteOlderDt, or DeleteOlderStr.
Check LastErrorText after failures or unexpected behavior.

Core Concepts

Concept	Meaning	Important Members
Cache Root	A root directory where cache files are stored. A cache can have one root or multiple roots.	AddRoot, GetRoot, NumRoots
Cache Key	A unique identifier for a cached item. It may be any length and may include any characters, but no two cached items should use the same key.	SaveToCache, Fetch, IsCached
Cache Level	Directory layout depth used to distribute cache files below the root.	Level
Expiration	Optional date/time metadata indicating when a cached item should be treated as expired.	SaveDt, SaveStr, Save*NoExpire, LastHitExpired
ETag	Optional entity-tag metadata associated with a cached item. Applications may use it to store additional information.	GetEtag, LastEtagFetched, Save*
Last Fetch Metadata	Properties populated when an item is fetched from the cache.	LastKeyFetched, LastExpirationFetchedStr, LastEtagFetched, LastHitExpired

Cache Root and Directory Layout

Member	Purpose	Guidance
AddRoot	Adds a cache root directory.	Call once for each root. A multi-root cache can spread roots across separate drives, such as D:\cacheRoot, E:\cacheRoot, and F:\cacheRoot.
NumRoots	Returns the number of root directories composing the cache.	Use to confirm how many roots have been configured.
GetRoot	Returns the Nth cache root directory path.	Indexing begins at 0.
Level	Controls how many subdirectory levels are used below the root.	Use higher levels to distribute many cache files across subdirectories.

Level	Directory Layout	Behavior
0	Single directory	All cache files are stored directly in the cache root.
1	One level of subdirectories	Cache files are located in 256 subdirectories numbered 0 through 255 directly under the root.
2	Two levels of subdirectories	The first level has 256 directories numbered 0 through 255. Each level-1 directory can contain up to 256 second-level directories, and cache files are stored in the leaf directories.

Core Properties

Property	Purpose	When It Is Useful
LastKeyFetched	Key of the last item fetched from cache.	Confirm which cache entry was returned.
LastEtagFetched	ETag of the last item fetched from cache.	Useful for HTTP-style cache validation or application-defined metadata.
LastExpirationFetchedStr	Expiration date/time of the last fetched item in RFC822 string format.	Inspect the cached item’s stored expiration.
LastHitExpired	Indicates whether the last fetched item is expired.	true means the fetched item’s expiration is before the current date/time.
Level	Number of directory levels in the cache.	Configure before relying on a specific cache file layout.
NumRoots	Number of root directories composing the cache.	Read-only count of configured cache roots.
LastErrorText	Diagnostic text for the last method or property access.	Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Saving Items to the Cache

Data Type	Expiration Type	Method	Notes
Binary byte array	CkDateTime	SaveToCacheDt	Inserts or replaces a binary item with a date/time object expiration.
Binary byte array	RFC822 string	SaveToCacheStr	Same as date/time save, but expiration is passed as an RFC822 string.
Binary byte array	No expiration	SaveToCacheNoExpire	Stores binary data without an expiration date/time.
BinData	RFC822 string or empty	SaveBd	Saves BinData. Use an empty expiration string for no expiration.
Text string	CkDateTime	SaveTextDt	Inserts or replaces a text item with a date/time object expiration.
Text string	RFC822 string	SaveTextStr	Same as text save, but expiration is passed as an RFC822 string.
Text string	No expiration	SaveTextNoExpire	Stores text data without an expiration date/time.

Key rule: The cache key may be any length and may include any characters, but it should uniquely identify the item. No two items in the cache should use the same key.

ETag rule: The ETag argument is optional and may be an empty string. Applications may use it to store additional metadata. When Chilkat.Http caches a page, it writes the HTTP response entity-tag to this field.

Fetching Items from the Cache

Method	Return / Target	Best Use
FetchFromCache	Byte array	Fetch binary data directly as bytes.
FetchBd	BinData	Fetch binary data into a supplied BinData object.
FetchText	String	Fetch text content directly as a string.
FetchSb	StringBuilder	Fetch text content into a supplied StringBuilder.

After fetching: Check LastHitExpired to determine whether the fetched item is expired, and inspect LastEtagFetched or LastExpirationFetchedStr when metadata is needed.

Cache Lookup and Metadata

Need	Method / Property	Behavior
Check whether an item exists	IsCached	Returns true if the item is found in the cache.
Get cache file path	GetFilename	Returns the absolute file path of the cache file associated with a key.
Get item ETag	GetEtag	Returns the ETag for an item in the cache.
Get item expiration	GetExpirationStr	Returns the expiration date/time for an item in RFC822 string format.
Get last fetched key	LastKeyFetched	Shows which key was most recently fetched.
Get last fetched ETag	LastEtagFetched	Shows the ETag of the most recently fetched cache item.
Check last fetch expiration status	LastHitExpired	Returns true when the last fetched item’s expiration is before the current date/time.

Updating Expiration

Method	Expiration Input	Purpose
UpdateExpirationDt	CkDateTime	Updates the expiration date/time for an existing cached item.
UpdateExpirationStr	RFC822 string	Same as UpdateExpirationDt, but the expiration date/time is passed as an RFC822 string.

Deleting and Cleaning Cache Items

Method	Deletes	Return Value
DeleteFromCache	A single cached item identified by key.	Returns false if the item exists but could not be deleted. Otherwise returns true.
DeleteAll	All cache items.	Returns the number of cache files deleted. In a multi-level cache, subdirectories are not deleted.
DeleteAllExpired	All expired cache items.	Returns the number of expired cache files deleted.
DeleteOlderDt	Items older than a specified CkDateTime.	Returns the number of cache files deleted, or -1 on error.
DeleteOlderStr	Items older than a specified RFC822 date/time string.	Returns the number of cache files deleted, or -1 on error.

Cleanup note: DeleteAll removes cache files, but existing subdirectories are not deleted when the cache uses multiple directory levels.

Method Summary by Category

Category	Methods	Purpose
Cache roots	AddRoot, GetRoot	Configure and inspect the root directories used by the disk cache.
Save binary data	SaveToCacheDt, SaveToCacheStr, SaveToCacheNoExpire, SaveBd	Store binary data with an expiration, RFC822 expiration string, no expiration, or BinData source.
Save text data	SaveTextDt, SaveTextStr, SaveTextNoExpire	Store text data with an expiration, RFC822 expiration string, or no expiration.
Fetch data	FetchFromCache, FetchBd, FetchText, FetchSb	Retrieve cached items as bytes, BinData, text, or StringBuilder.
Lookup and metadata	IsCached, GetFilename, GetEtag, GetExpirationStr	Check existence and retrieve file path, ETag, and expiration metadata.
Expiration update	UpdateExpirationDt, UpdateExpirationStr	Change the expiration date/time of a cached item.
Delete and cleanup	DeleteFromCache, DeleteAll, DeleteAllExpired, DeleteOlderDt, DeleteOlderStr	Remove one item, all items, expired items, or items older than a specified date/time.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
Cache item cannot be found	IsCached, GetFilename	Confirm the same unique key is used for saving and fetching, and inspect the cache filename associated with the key.
Fetched item is stale	LastHitExpired, LastExpirationFetchedStr	After fetching, check whether the cached item’s expiration is before the current date/time.
Expiration must be changed	UpdateExpirationDt, UpdateExpirationStr	Update the cached item’s expiration instead of rewriting the item data.
Cleanup deletes fewer files than expected	DeleteAll, DeleteAllExpired, DeleteOlder*	Review whether the cleanup method targets all files, expired files, or files older than a specific date/time.
Older-than cleanup reports an error	DeleteOlderDt, DeleteOlderStr	These methods return -1 on error. Check LastErrorText.
Unexpected cache directory layout	Level, AddRoot, GetRoot	Confirm the configured root directories and directory level setting.
Need details after a failure	LastErrorText	Check diagnostic text after failed or unexpected save, fetch, lookup, update, or delete operations.

Common Pitfalls

Pitfall	Better Approach
Using non-unique keys for different cached items.	Ensure every cached item has a unique key. Reusing a key inserts or replaces the item associated with that key.
Assuming IsCached means the item is fresh.	IsCached only tells whether the item exists. Fetch the item and check LastHitExpired or its expiration metadata when freshness matters.
Using the wrong expiration format.	Use Dt methods for CkDateTime values and Str methods for RFC822 date/time strings.
Expecting DeleteAll to remove subdirectories.	DeleteAll deletes cache files. In a multi-level cache, existing subdirectories are not deleted.
Ignoring the ETag field because the cache is not used for HTTP.	The ETag is optional metadata. Applications may use it to store additional information even outside HTTP caching scenarios.
Fetching text data with binary-only assumptions, or binary data as text.	Use FetchText or FetchSb for text, and FetchFromCache or FetchBd for binary data.

Best Practices

Recommendation	Reason
Call AddRoot before using the cache.	The cache needs at least one root directory to store cached files.
Choose Level based on expected cache size.	Larger caches benefit from distributing files into one or two levels of subdirectories.
Use stable, unique cache keys.	Fetching, updating, deleting, and metadata lookup all depend on the same key.
Store expiration and ETag metadata when freshness or validation matters.	Expiration enables stale-item detection and cleanup. ETag can preserve HTTP-style entity tags or application-specific metadata.
Use NoExpire methods only for items that should not expire.	Items without expiration will not be removed by expiration-based cleanup.
Run periodic cleanup for long-lived caches.	DeleteAllExpired and DeleteOlder* prevent stale cache files from accumulating indefinitely.
Check LastErrorText after failures.	It provides useful diagnostic detail for root setup, save, fetch, metadata, expiration update, and deletion problems.

Summary

Chilkat.Cache is a disk-cache class for storing and retrieving binary or text items by unique key. It supports configurable cache roots, optional multi-level directory layout, expiration metadata, ETag metadata, cache lookup, fetch status properties, expiration updates, and cleanup methods for deleting single items, all items, expired items, or items older than a specified date/time.

The most important practical guidance is to configure at least one cache root, choose a directory level appropriate for the number of cached files, use stable unique keys, store expiration metadata when freshness matters, and periodically remove expired or old cache items.

Chilkat.Cache Class Overview