Extended Keys
Most message types allow user-defined data (in the form of key-value pairs) to be gathered and sent along with the message.
The injected code may obtain Extended Keys from an application source and/or from the annotated method's arguments.
Extended Key settings are always optional. If they are omitted, the resulting message does not include extended key information.
Sending Extended Keys Obtained from a Source
Configure the IDictionary<string,string>
(or IDictionary
) source called ExtendedKeySource on the attribute corresponding to the message you wish to send.
Injected code obtains the key-value pairs from this source at runtime and adds them to the Extended Keys; you should ensure that the dictionary is populated and available via the source at the time the annotated method is executed.
Sample Feature attribute usage with an ExtendedKeySource defined as a method called GetDictionary
:
[Feature(
..."Click"
ExtendedKeySourceElement = SourceElements.Method,
ExtendedKeySourceName = "GetDictionary",
)]
private void button1_Click(object sender, EventArgs e) {
...
}
// Creates and populates a dictionary with custom data
public IDictionary<string, string> GetDictionary() {
Dictionary<string, string> dict = new Dictionary<string, string>();
dict.Add("key1", "val1");
dict.Add("key2", "val2");
return dict;
}
Automatically Sending Method Arguments as Extended Keys
In addition to source-supplied Extended Keys, the parameter names and values of instrumented methods can be automatically gathered and added to the set of Extended Keys.
Attributes that support Extended Keys provide an ExtendedKeyMethodArguments property. To add these method arguments to the Extended Keys, specify this property on the attribute decorating the method whose parameters and values you wish to send.
The ExtendedKeyMethodArguments property is configured by a string that defines which parameters will be included and, optionally, what the reported keys should be named in the message data.
ExtendedKeyMethodArguments values can consist of any combination of the following patterns:
* | All parameters |
---|---|
<param1>,<param2> | Only the names and values of param1 and param2 |
<param1>=<key1>,<param2>=<key2> | Only the values of param1 and param2 with the key names key1 and key2 respectively |