Class JobDataMap

Namespace

Quartz

Assembly

Quartz.dll

Holds state information for IJob instances.

[Serializable]
public sealed class JobDataMap : IDictionary<string, object?>, ICollection<KeyValuePair<string, object?>>, IReadOnlyDictionary<string, object?>, IReadOnlyCollection<KeyValuePair<string, object?>>, IEnumerable<KeyValuePair<string, object?>>, IEnumerable, IEquatable<JobDataMap>, ISerializable

Inheritance

object

JobDataMap

Implements

IDictionary<string, object>

ICollection<KeyValuePair<string, object>>

IReadOnlyDictionary<string, object>

IReadOnlyCollection<KeyValuePair<string, object>>

IEnumerable<KeyValuePair<string, object>>

IEnumerable

IEquatable<JobDataMap>

ISerializable

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

JobDataMap instances are stored once when the IJob is added to a scheduler. They are also re-persisted after every execution of instances that have PersistJobDataAfterExecutionAttribute present.

JobDataMap instances can also be stored with a ITrigger. This can be useful in the case where you have a Job that is stored in the scheduler for regular/repeated use by multiple Triggers, yet with each independent triggering, you want to supply the Job with different data inputs.

The IJobExecutionContext passed to a Job at execution time also contains a convenience JobDataMap that is the result of merging the contents of the trigger's JobDataMap (if any) over the Job's JobDataMap (if any).

Update since 2.4.2 - We keep an dirty flag for this map so that whenever you modify(add/delete) any of the entries, it will set to "true". However if you create new instance using an existing map with constructor, then the dirty flag will NOT be set to "true" until you modify the instance.

The typed read accessors (GetInt, TryGetDateTime and friends) are extension members declared in DataMapExtensions; the PutAsString writers live here because they participate in the map's change tracking.

The binary-serialized form of this type — the entries named version, dirty and map, with a Dictionary<TKey, TValue> of string to object as the payload — is the shape 3.x wrote into JOB_DATA and BLOB_TRIGGERS blobs, and it is what the binary-to-JSON migration path reads. It must not change.

Constructors

JobDataMap()

Create an empty JobDataMap.

public JobDataMap()

JobDataMap(IDictionary<string, object?>)

Create a JobDataMap with the given data.

public JobDataMap(IDictionary<string, object?> map)

Parameters

map IDictionary<string, object>

Remarks

A ForceJobDataMapDirty entry is not copied; it instead leaves the new map flagged dirty, which is how the job store asks for the data blob to be rewritten.

JobDataMap(int)

Create JobDataMap with initial capacity.

public JobDataMap(int initialCapacity)

Parameters

initialCapacity int

Properties

Count

Gets the number of entries contained in the map.

public int Count { get; }

Property Value

int

IsEmpty

Gets a value indicating whether this instance is empty.

public bool IsEmpty { get; }

Property Value

bool

true if this instance is empty; otherwise, false.

this[string]

Gets or sets the object with the specified key.

public object? this[string key] { get; set; }

Parameters

key string

Property Value

object

Keys

Gets a collection containing the keys of the map.

public ICollection<string> Keys { get; }

Property Value

ICollection<string>

Values

Gets a collection containing the values in the map.

public ICollection<object?> Values { get; }

Property Value

ICollection<object>

Methods

Add(string, object?)

Adds an entry with the provided key and value to the map.

public void Add(string key, object? value)

Parameters

key string

The key of the entry to add.

value object

The value of the entry to add.

Exceptions

ArgumentNullException

key is null.

ArgumentException

An entry with the same key already exists in the map.

Clear()

Removes all entries from the map.

public void Clear()

ContainsKey(string)

Determines whether the map contains an entry with the specified key.

public bool ContainsKey(string key)

Parameters

key string

The key to locate.

Returns

bool

true if the map contains an entry with the key; otherwise, false.

Exceptions

ArgumentNullException

key is null.

ContainsValue(object?)

Determines whether the specified obj contains value.

public bool ContainsValue(object? obj)

Parameters

obj object

The obj.

Returns

bool

true if the specified obj contains value; otherwise, false.

CopyTo(KeyValuePair<string, object?>[], int)

Copies the elements of the ICollection<T> to an Array, starting at a particular Array index.

public void CopyTo(KeyValuePair<string, object?>[] array, int arrayIndex)

Parameters

array KeyValuePair<string, object>[]

The one-dimensional Array that is the destination of the elements copied from ICollection<T>. The Array must have zero-based indexing.

arrayIndex int

The zero-based index in array at which copying begins.

Exceptions

ArgumentNullException

array is null.

ArgumentOutOfRangeException

arrayIndex is less than 0.

ArgumentException

The number of elements in the source ICollection<T> is greater than the available space from arrayIndex to the end of the destination array.

Equals(JobDataMap?)

Two maps are equal when they hold the same keys with equal values. The dirty flag does not participate.

public bool Equals(JobDataMap? other)

Parameters

other JobDataMap

Returns

bool

Remarks

Until 4.0 this comparison looked at the key sets only, so two maps with the same keys but different values compared equal — and assigning such a map as a nested value did not mark the outer map dirty, silently skipping the job store rewrite.

Equals(object?)

Two maps are equal when they hold the same keys with equal values. The dirty flag does not participate.

public override bool Equals(object? obj)

Parameters

obj object

Returns

bool

Remarks

Until 4.0 this comparison looked at the key sets only, so two maps with the same keys but different values compared equal — and assigning such a map as a nested value did not mark the outer map dirty, silently skipping the job store rewrite.

GetEnumerator()

Returns an enumerator that iterates through the collection.

public IEnumerator<KeyValuePair<string, object?>> GetEnumerator()

Returns

IEnumerator<KeyValuePair<string, object>>

An enumerator that can be used to iterate through the collection.

GetHashCode()

A constant, consistent with Equals(JobDataMap?): equal maps trivially hash equally.

public override int GetHashCode()

Returns

int

Remarks

The map is mutable, so no hash derived from its content can honor the contract that an object's hash never changes while it sits in a hash-keyed collection — a map mutated after insertion would move out of reach of its own bucket and the entry would be silently lost. With a constant, hash-keyed use of maps degrades to an Equals scan instead of corrupting.

PutAsString(string, bool)

Adds the given bool value as "True" or "False" to the IJob's data map, which GetBoolean and TryGetBoolean read back.

public void PutAsString(string key, bool value)

Parameters

key string

value bool

Remarks

bool is not IFormattable — it has nothing to format for a culture — so it needs an overload of its own to stay writable this way.

PutAsString(string, char)

Adds the given char value as a one-character string to the IJob's data map.

public void PutAsString(string key, char value)

Parameters

key string

value char

Remarks

char, like bool, is not IFormattable.

PutAsString(string, DateOnly)

Adds the given DateOnly value as a round-trip ("O", yyyy-MM-dd) formatted string to the IJob's data map.

public void PutAsString(string key, DateOnly value)

Parameters

key string

value DateOnly

PutAsString(string, DateTime)

Adds the given DateTime value as a round-trip ("O") formatted string to the IJob's data map, preserving sub-second precision and Kind.

public void PutAsString(string key, DateTime value)

Parameters

key string

value DateTime

PutAsString(string, DateTimeOffset)

Adds the given DateTimeOffset value as a round-trip ("O") formatted string to the IJob's data map, preserving sub-second precision and the offset.

public void PutAsString(string key, DateTimeOffset value)

Parameters

key string

value DateTimeOffset

PutAsString(string, Guid)

Adds the given Guid value as a string version to the IJob's data map. The hyphens are omitted from the Guid.

public void PutAsString(string key, Guid value)

Parameters

key string

value Guid

PutAsString(string, TimeOnly)

Adds the given TimeOnly value as a round-trip ("O") formatted string to the IJob's data map.

public void PutAsString(string key, TimeOnly value)

Parameters

key string

value TimeOnly

PutAsString(string, TimeSpan)

Adds the given TimeSpan value as a string version to the IJob's data map.

public void PutAsString(string key, TimeSpan value)

Parameters

key string

value TimeSpan

PutAsString<T>(string, T)

Adds the given value as a string version using the default ToString operation.

public void PutAsString<T>(string key, T value) where T : IFormattable

Parameters

key string

value T

Type Parameters

T

Remarks

An enum lands here and stores its name (DayOfWeek.Monday stores "Monday"), which TryGetEnum reads back.

The constraint is IFormattable rather than the legacy IConvertible: formatting for a culture is what this does, and it lets through every modern numeric type that never implemented IConvertible. The types that have a round-trip format worth pinning — dates, times, Guid — have their own overloads below, which win over this one.

Remove(string)

Removes the entry with the specified key from the map.

public bool Remove(string key)

Parameters

key string

The key of the entry to remove.

Returns

bool

Exceptions

ArgumentNullException

key is null.

TryGetValue(string, out object?)

Gets the value associated with the specified key.

public bool TryGetValue(string key, out object? value)

Parameters

key string

Gets the value associated with the specified key.

value object

When this method returns, contains the value associated with the specified key, if the key is found; otherwise, the default value for the type of the value parameter. This parameter is passed uninitialized.

Returns

bool

true if the JobDataMap contains an element with the specified key; otherwise, false.

See Also

IJob

PersistJobDataAfterExecutionAttribute

ITrigger

IJobExecutionContext