This documentation is archived and is not being maintained.

ChangeMonitor Class

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

Namespace:  System.Runtime.Caching
Assembly:  System.Runtime.Caching (in System.Runtime.Caching.dll)

public abstract class ChangeMonitor : IDisposable

The ChangeMonitor type exposes the following members.

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

Public propertyHasChangedGets a value that indicates that the state that is monitored by the ChangeMonitor class has changed.
Public propertyIsDisposedGets a value that indicates that the derived instance of a ChangeMonitor class is disposed.
Public propertyUniqueIdGets a value that represents the ChangeMonitor class instance.

Public methodDispose()Releases all resources that are used by the current instance of the ChangeMonitor class.
Protected methodDispose(Boolean)Releases all managed and unmanaged resources and any references to the ChangeMonitor instance. This overload must be implemented by derived change-monitor classes.
Public methodEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodInitializationCompleteCalled from the constructor of derived classes to indicate that initialization is finished.
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodNotifyOnChangedCalled by Cache implementers to register a callback and notify an ObjectCache instance through the OnChangedCallback delegate when a dependency has changed.
Protected methodOnChangedCalled by derived classes to raise the event when a dependency changes.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)

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:

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 Inheritors

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 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, by passing a OnChangedCallback object. The NotifyOnChanged method can be called only one time. If a dependency change has already occurred, the OnChangedCallback instance will be called immediately when NotifyOnChanged is called. Otherwise, the OnChangedCallback instance will be called only one time. This one time call occurs either when the OnChanged 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 method either before a cache implementation has called NotifyOnChanged method or after. If the OnChanged method is called before NotifyOnChanged is called, the base ChangeMonitor implementation will notify the cache that this has occurred and will trigger the callback to be passed to NotifyOnChanged immediately when NotifyOnChanged is invoked. Any state data that is passed to the OnChanged method is saved by the change monitor and subsequently passed to the NotifyOnChanged method when the NotifyOnChanged method is invoked.

  • A change monitor must implement the Dispose method. For more information, see the Dispose 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 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 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 method automatically calls the Dispose method after it calls a callback that is registered through NotifyOnChanged.


      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.

.NET Framework

Supported in: 4

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

This type is thread safe.