Integrated data cache management lets you cache retrieved data into session state and then restore it to the DataWindow during a postback so that you do not need to connect to the database and retrieve the data again.
The saved data cache contains all the data in the DataWindow, including the contents of the primary, filter, and delete buffers and any child DataWindows, and the status flags. The data cache does not contain the presentation (the LibraryList, DataWindowObject, and other display characteristics) of the DataWindow object. The presentation is saved in ViewState.
Integrated cache management is based on the session, not the application. It uses the ASP.NET Page.Session property to save the data, which is in turn based on the SessionState property. To fully understand the implications of this, see your Microsoft ASP.NET documentation. For example, session data might be released if the browser does not revisit the application within a specified timeout period. If you expect this to affect your application, you can use the GetDataObject and SetDataObject methods to save the data cache into an application-level state object. (See “Managing the data cache without integrated management”).
You can use the SaveDataCache method to explicitly save the data cache into session state after retrieving data, or you can set the AutoSaveDataCacheAfterRetrieve property to true to specify that the DataWindow will automatically save the data as a data cache after a retrieve completes successfully.
If the DataWindow uses an external data source, you must use SaveDataCache to save the data cache explicitly:
dwExt.SaveDataCache()
During page postback, you can use the RestoreDataCache method to explicitly restore the data from session state into the DataWindow, or set the AutoRestoreDataCache property to true to restore the data cache if it exists in session state. You do not need to call RestoreDataCache explicitly for external DataWindows if the AutoRestoreDataCache property is set to true.
Use AutoSaveDataCacheAfterRetrieve together with AutoRestoreDataCache and AutoRestoreContext to simplify your coding tasks.
If saving or restoring the data cache fails when the automatic caching properties are set to true, the AutoDataCacheError event is triggered. SaveDataCache and RestoreDataCache throw an exception on failure.
When the data cache of a static DataWindow is restored, the DataWindow can be recreated because the data cache restores the data and ViewState restores the DataWindow object’s design. The data cache is not saved for dynamically created DataWindow objects because ViewState does not contain the information about the DataWindow’s design required to recreate the DataWindow.
Because the DataWindow object was created dynamically, there is no LibraryList or DataWindowObject associated with it. For a DataWindow dynamically constructed using DataWindowSyntaxFromSql, the DataWindow’s syntax is not saved when SaveViewState is called and therefore not restored when LoadViewState is called because saving the syntax would make the ViewState too large.
Setting AutoRestoreDataCache to true when you are using a dynamically created DataWindow results in an exception instead of triggering the AutoDataCacheError event, because there is no DataWindow object associated with the control.
If you are using a DataWindow created from syntax, you need to call the Create method to recreate the dynamic DataWindow in every request. Calling Create clears the DataWindowObject property setting.
If you use the Modify method on the server to modify the syntax of a DataWindow object at runtime, your changes are not restored when the DataWindow is recreated. To save these changes, use a mechanism such as saving them to Session state.
The GetDataObject and SetDataObject methods allow you to manage the DataWindow’s data cache object yourself. You can get the data cache object with GetDataObject and save it into the application-level Page.Cache. When the page is posted back, you can retrieve the data cache object from the page cache and set it back into the DataWindow using SetDataObject.
The ClearDataCache, RestoreDataCache, and SaveDataCache methods also allow you to manage the data in session state manually.
