ChangeMonitor Class

Definition

Namespace:

System.Runtime.Caching

Assembly:

System.Runtime.Caching.dll

Package:

System.Runtime.Caching v9.0.0-rc.2.24473.5

Provides a base class for a derived custom type that monitors changes in the state of the data which a cache item depends on.

public ref class ChangeMonitor abstract : IDisposable

public abstract class ChangeMonitor : IDisposable

type ChangeMonitor = class
    interface IDisposable

Public MustInherit Class ChangeMonitor
Implements IDisposable

Inheritance

Object

ChangeMonitor

Derived

System.Runtime.Caching.CacheEntryChangeMonitor

System.Runtime.Caching.FileChangeMonitor

System.Runtime.Caching.SqlChangeMonitor

Implements

IDisposable

Remarks

The ChangeMonitor class is used as the base class for derived monitor classes that are specialized for particular cache implementations. A ChangeMonitor instance monitors changes in the state of data which a cache item depends on. For example, the item can be a file or data entity whose contents are cached. If the file or data entity is updated, the associated cache entry must be changed also. Common items that can be monitored include data entities (such as database fields, values, rows, or tables), another cache entry, and files and file attributes.

A dependency change is a change in the state of a dependency. In a typical cache implementation, after a ChangeMonitor instance notifies the cache that a dependency has changed, the cache performs the required action, such as invalidating the inserted cache entry.

Derived ChangeMonitor classes can be customized to monitor dependency changes for specific different data stores. For example, there are cache implementations for a file system, physical memory, or a database. The ChangeMonitor class examines changes that occur outside the cache, and then alerts the cache that changes have occurred.

The .NET Framework includes the following classes that derive from ChangeMonitor class:

• CacheEntryChangeMonitor

• FileChangeMonitor

• HostFileChangeMonitor

• SqlChangeMonitor

Each of these classes works with different types of dependencies. For example, the derived FileChangeMonitor class monitors changes to a cache for file system data (files and folders) that the cache item depends on.

Notes to Implementers

If you create a custom cache implementation or a derived change monitor type, you must follow certain guidelines. The following list summarizes these guidelines. For more information, see the documentation for individual methods or properties.

• The constructor of a derived class must set the UniqueId property, begin monitoring, and call InitializationComplete() method before the method returns. If a constructor encounters an error during constructions and must have to dispose of resources, the constructor can only call the Dispose overload after the InitializationComplete() method is called because the Dispose overload will throw an InvalidOperationException exception if initialization is not completed.

• If changes occur in the data that is being monitored before initialization is complete, the constructor must call the OnChanged(Object) method before calling the InitializationComplete() method.

• After a derived ChangeMonitor type is instantiated, you must insert the monitor into a custom ObjectCache implementation. Or if you are finished using the change monitor, call the Dispose method.

• After a ChangeMonitor instance is inserted into a ObjectCache implementation, the ObjectCache instance require that the change monitor is disposed. Even if the insertion is invalid and causes an exception, the ObjectCache implementation must call the Dispose overload.

• After a derived change monitor is inserted into a cache, the ObjectCache implementation must call NotifyOnChanged(OnChangedCallback), by passing a OnChangedCallback object. The NotifyOnChanged(OnChangedCallback) method can be called only one time. If a dependency change has already occurred, the OnChangedCallback instance will be called immediately when NotifyOnChanged(OnChangedCallback) is called. Otherwise, the OnChangedCallback instance will be called only one time. This one time call occurs either when the OnChanged(Object) method is called because the ChangeMonitor instance detected a change, or when the Dispose() method is called on the ChangeMonitor, whichever occurs first.

• The OnChangedCallback instance that is provided by an ObjectCache implementation should remove the associated cache entry and specify a reason by using the DependencyChanged enumeration.

• A ChangeMonitor instance can call the OnChanged(Object) method either before a cache implementation has called NotifyOnChanged(OnChangedCallback) method or after. If the OnChanged(Object) method is called before NotifyOnChanged(OnChangedCallback) is called, the base ChangeMonitor implementation will notify the cache that this has occurred and will trigger the callback to be passed to NotifyOnChanged(OnChangedCallback) immediately when NotifyOnChanged(OnChangedCallback) is invoked. Any state data that is passed to the OnChanged(Object) method is saved by the change monitor and subsequently passed to the NotifyOnChanged(OnChangedCallback) method when the NotifyOnChanged(OnChangedCallback) method is invoked.

• A change monitor must implement the Dispose(Boolean) method. For more information, see the Dispose(Boolean) method documentation.

• The Dispose() method overload must be called to dispose of the ChangeMonitor instance. The rules for calling Dispose are as follows:

  • Before an item is inserted into the cache, it is the responsibility of caller to dispose of a ChangeMonitor instance.

  • Once cache item and the ChangeMonitor instances that are associated with it are passed to a cache, the cache implementer must make sure that the Dispose method is called, even if the insert fails.

  • After an item and its associated ChangeMonitor instances are passed to a cache, the caller must not dispose the dependency because when the Dispose method is called, the call is treated as if the dependency has changed. As a result, the OnChanged(Object) method is automatically invoked.

• Taking these rules into consideration, the Dispose method must be called in one of the following ways:

  • Users must call the Dispose() method overload if they decide not to insert the derived change-monitor instance into a cache.

  • If the implementation tries to insert the change-monitor instance into an object cache but the insertion fails, the cache implementation is responsible for calling the Dispose() overload. When the insertion attempt causes an exception, the cache implementation must dispose of any associated dependencies.

  • If the cache entry is removed, the cache implementation must also dispose of the dependency.

  • The internal implementation of the OnChanged(Object) method automatically calls the Dispose method after it calls a callback that is registered through NotifyOnChanged(OnChangedCallback).

Note: This automatic call to the dispose method during the event firing only occurs if the initialization of the ChangeMonitor instance was previously completed.

When a derived change monitor's constructor calls the InitializationComplete() method, if the state of the change monitor has already changed (that is, the state that is monitored already changed when the constructor was still active) then the InitializationComplete() method will automatically dispose of the change monitor.

• The HasChanged property is set to true after the OnChanged(Object) method is called by the derived change-monitor instance, regardless of whether a OnChangedCallback object has been set by a call to the NotifyOnChanged(OnChangedCallback) method or not.

Constructors

ChangeMonitor()

Initializes a new instance of the ChangeMonitor class. This constructor is called from constructors in derived classes to initialize the base class.

Properties

HasChanged	Gets a value that indicates that the state that is monitored by the ChangeMonitor class has changed.
IsDisposed	Gets a value that indicates that the derived instance of a ChangeMonitor class is disposed.
UniqueId	Gets a value that represents the ChangeMonitor class instance.

Methods

Dispose()	Releases all resources that are used by the current instance of the ChangeMonitor class.
Dispose(Boolean)	Releases all managed and unmanaged resources and any references to the ChangeMonitor instance. This overload must be implemented by derived change-monitor classes.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetType()	Gets the Type of the current instance. (Inherited from Object)
InitializationComplete()	Called from the constructor of derived classes to indicate that initialization is finished.
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
NotifyOnChanged(OnChangedCallback)	Called by Cache implementers to register a callback and notify an ObjectCache instance through the OnChangedCallback delegate when a dependency has changed.
OnChanged(Object)	Called by derived classes to raise the event when a dependency changes.
ToString()	Returns a string that represents the current object. (Inherited from Object)

Thread Safety

This type is thread safe.

See also

• System.Web.Caching
• ObjectCache
• ASP.NET Caching