TelemetrySession Class

Definition

Namespace:

Microsoft.VisualStudio.Telemetry

Assembly:

Microsoft.VisualStudio.Telemetry.dll

Package:

Microsoft.VisualStudio.Telemetry v17.12.48

Represents one telemetry session that can post telemetry events and session properties. The API makes the best effort to deliver telemetry data to the server. The requests are queued and sent in batches. The events will be saved locally if they cannot be sent before the process exits. Sending will resume when the next application instance calls the telemetry API. Telemetry may be lost in case of process unresponsiveness or fatal crash or no Internet connection for 30 days. All methods are thread-safe and return immediately.

public ref class TelemetrySession : Microsoft::VisualStudio::Telemetry::TelemetryDisposableObject

public class TelemetrySession : Microsoft.VisualStudio.Telemetry.TelemetryDisposableObject

type TelemetrySession = class
    inherit TelemetryDisposableObject

Public Class TelemetrySession
Inherits TelemetryDisposableObject

Inheritance

Object

TelemetryDisposableObject

TelemetrySession

Constructors

TelemetrySession(String)

Creates a new telemetry session based on a serialized string of a TelemetrySessionSettings instance. Use the SerializeSettings method of an instance of TelemetrySession to get such a string. This enables a process to post events to a telemetry session from another process. Use VSTelemetryService.DefaultSession to access the application session.

Fields

DefaultContextName	Default context name.
ValueNotAvailable	Constant for value which is not available.

Properties

AppId	Gets or sets application id for SQM
BucketFiltersToAddDumpsToFaults	Gets or sets a value indicating for which buckets process dumps should be added for fault events.
BucketFiltersToEnableWatsonForFaults	Gets or sets a value indicating for which buckets Watson reporting should be enabled for fault events.
CalculatedSamplings	Gets/Sets calculated sampling from the manifest file
CancellationToken	Gets the Telemetry Session's CancellationToken
CanCollectPrivateInformation	Gets a value indicating whether current session can collect PII information based on the answer from the User Information Manager
GlobalStorageUri	Gets the global storage URI from VS Code
HostName	Gets or sets telemetry host name, it affects on manifest file location
IsDisposed	Gets a value indicating whether session is deposed - to detect redundant calls (Inherited from TelemetryDisposableObject)
IsOptedIn	Gets or sets a value indicating whether user is opted in.
IsUserMicrosoftInternal	Gets a value indicating whether current session belongs to internal user thus can collect information based on the answer from the User Information Manager
MacAddressHash	Gets the MAC address hash. If the hash is not found in local storage, a 0 hash will be returned and the hashing process will be invoked
MachineId	Gets machine id (SQM Machine Id)
SessionId	Gets the session Id.
TimeSinceSessionStart	Gets TimeSinceSessionStart in case if customers want to use it to calculate custom delays based on the same algorithm Telemetry does.
UserId	Gets user id (SQM User Id)

Methods

AddCommonPropertyRange(IDictionary<String,Object>)	Add properties that may be common to all events for the session, but should not have the Default.Context prefix. Properties are not persisted between sessions. To add a single property see TryAddCommonProperty(String, Object)
AddSessionChannel(ISessionChannel)	Add new session channel to the list of active channels.
CreateContext(String)	Create context with the specific name.
Dispose()	This code added to correctly implement the disposable pattern. (Inherited from TelemetryDisposableObject)
DisposeManagedResources()	Protected implementation of Dispose pattern.
DisposeToNetworkAsync(CancellationToken)	Asynchronously dispose and try to send all telemetry over the network.
GetCommonPropertyDictionary()	Gets an IDictionary containing a copy of the CommonProperty keys and values currently in the session.
GetContext(String)	Gets a context by the given name.
GetPersistedSharedProperty(String)	Get persisted shared property by name.
GetPropertyBag(String)	Gets a property bag by the given name.
GetSharedProperty(String)	Get shared property by name.
GetSharedPropertyAsObject(String)	Get value of shared property by name as an object.
PostEvent(String)	Queues a telemetry event to be posted to a server. Choose this method for simplicity if the name is the only event property. You should consider choosing PostUserTask, PostOperation, PostFault or PostAsset. These will enable a richer telemetry experience with additional insights provided by Visual Studio Data Model. If your data point doesn't align with any VS Data Model entity, please don't force any association and continue to use this method. If you have any questions regarding VS Data Model, please email VS Data Model Crew (vsdmcrew@microsoft.com).
PostEvent(TelemetryEvent)	Queues a telemetry event to be posted to a server. Choose this method for flexibility. You should consider choosing PostUserTask, PostOperation, PostFault or PostAsset. These will enable a richer telemetry experience with additional insights provided by Visual Studio Data Model. If your data point doesn't align with any VS Data Model entity, please don't force any association and continue to use this method. If you have any questions regarding VS Data Model, please email VS Data Model Crew (vsdmcrew@microsoft.com).
PostMetricEvent(TelemetryMetricEvent)	Prepares the metric event by populating metric properties, then posts the event.
PostProperty(String, Object)	Queues an update to for a session-wide property. You may want to consider TelemetrySettingProperty or TelemetryMetricProperty These will enable a richer telemetry experience with additional insights provided by Visual Studio Data Model. If you have any questions regarding VS Data Model, please email VS Data Model Crew (vsdmcrew@microsoft.com).
PostRecurringProperty(String, Object)	Adds a property to be included on the regularly recurring VS/TelemetryApi/RecurringProperties event. Unlike PostProperty or TelemetryContext.PostProperty, PostRecurringProperty does not add the given property to every event. PostRecurringProperty is most useful for values that are constant for the lifetime of a TelemetrySession.
RegisterForReliabilityEvent()	Writes process and session information to the registry which is used by any host VS IDE to track and report the final shutdown status of this process.
RegisterPropertyBag(String, TelemetryPropertyBag)	Register the given property bag.
RemovePersistedSharedProperty(String)	Remove persisted shared property for all sessions means remove shared property from this default context, and for any future sessions on the machine.
RemoveSharedProperty(String)	Remove shared property for the session means remove shared property from the default context
RequiresNotDisposed()	This function throws an ObjectDisposedException if the object is disposed. (Inherited from TelemetryDisposableObject)
SerializeSettings()	Serializes the TelemetrySessionSettings object.
SetPersistedSharedProperty(String, Double)	Set persisted shared property for the session means set shared property for the default context for this session and any future sessions on the machine.
SetPersistedSharedProperty(String, String)	Set persisted shared property for the session means set shared property for the default context for this session and any future sessions on the machine.
SetSharedProperty(String, Object)	Set shared property for the session means set shared property for the default context You may want to consider TelemetrySettingProperty or TelemetryMetricProperty These will enable a richer telemetry experience with additional insights provided by Visual Studio Data Model. If you have any questions regarding VS Data Model, please email VS Data Model Crew (vsdmcrew@microsoft.com).
Start()	Start session means create default context for the session and add private information properties if it is allowed.
ToString()	ToString to make debugging easier: show in debug watch window
TryAddCommonProperty(String, Object)	Attempts to add a single property key and value that may be common to all events for the session but should not have the Context prefix. Properties are not persisted between sessions. To add multiple properties see AddCommonPropertyRange(IDictionary<String,Object>)
TryGetCommonPropertyValue(String, Object)	Gets the value associated with the specified property name that will be common to all events for the session, but should not have the context or reserved prefix.
UnregisterPropertyBag(String)	Unregister a property bag with the given name.
UseVsIsOptedIn()	Reads and set VS OptIn status. Calculate IsOptedIn status based on OptedIn status from all installed versions of VS. If all found OptedIn statuses are true we return true, otherwise we return false.
UseVsIsOptedIn(String)	Reads and set VS OptIn status.

Extension Methods

PostCorrelatedFaultEvent(TelemetrySession, TelemetryScope<OperationEvent>, String, String, FaultSeverity, Exception, Func<IFaultUtility,Int32>)	Posts a FaultEvent that is correlated with operation to session.
PostCorrelatedFaultEvent(TelemetrySession, TelemetryScope<OperationEvent>, String, String, Exception, Func<IFaultUtility,Int32>)	Posts a FaultEvent that is correlated with operation to session.
PostCommandLineFlags(TelemetrySession, IEnumerable<String>, IDictionary<String,Object>)	Queues a telemetry event with command line flags information with additional properties to be posted to the server. Only command line flags (identified by the given prefixes) will be included.
PostCommandLineFlags(TelemetrySession, String[])	Queues a telemetry event with command line flags information to be posted to the server. Only command line flags (identified by the given prefixes) will be included.
PostAsset(TelemetrySession, String, String, Int32, IDictionary<String,Object>, TelemetryEventCorrelation[])	Post an Asset event. Asset is the target of user task or operation, e.g., Solution, Project, File, Extension, License, Designer.
PostFault(TelemetrySession, String, String, FaultSeverity, Exception, Func<IFaultUtility,Int32>, TelemetryEventCorrelation[])	Post a fault event with an exception object and a callback. The callback can be used to calculate expensive data to be sent to the Watson back end, such as JScript callstacks, etc It becomes more useful when correlated with UserTaskEvent or OperationEvent which may have led to the fault occurence.
PostFault(TelemetrySession, String, String, FaultSeverity, Exception, Func<IFaultUtility,Int32>)	Post a fault event with an exception object and a callback. The callback can be used to calculate expensive data to be sent to the Watson back end, such as JScript callstacks, etc It becomes more useful when correlated with UserTaskEvent or OperationEvent which may have led to the fault occurence.
PostFault(TelemetrySession, String, String, FaultSeverity, Exception)	Post a Fault Event with a managed Exception object. The bucket parameters are created from the exception object. It becomes more useful when correlated with UserTaskEvent or OperationEvent which may have led to the fault occurence.
PostFault(TelemetrySession, String, String, FaultSeverity)	Post a Fault event. The event will always be sent to AppInsights, but if it passes sampling, it gets posted to Wason as well. It becomes more useful when correlated with UserTaskEvent or OperationEvent which may have led to the fault occurence.
PostFault(TelemetrySession, String, String, Exception, Func<IFaultUtility,Int32>, TelemetryEventCorrelation[])	Post a fault event with an exception object and a callback. The callback can be used to calculate expensive data to be sent to the Watson back end, such as JScript callstacks, etc It becomes more useful when correlated with UserTaskEvent or OperationEvent which may have led to the fault occurence.
PostFault(TelemetrySession, String, String, Exception, Func<IFaultUtility,Int32>)	Post a fault event with an exception object and a callback. The callback can be used to calculate expensive data to be sent to the Watson back end, such as JScript callstacks, etc It becomes more useful when correlated with UserTaskEvent or OperationEvent which may have led to the fault occurence.
PostFault(TelemetrySession, String, String, Exception)	Post a Fault Event with a managed Exception object. The bucket parameters are created from the exception object. It becomes more useful when correlated with UserTaskEvent or OperationEvent which may have led to the fault occurence.
PostFault(TelemetrySession, String, String)	Post a Fault event. The event will always be sent to AppInsights, but if it passes sampling, it gets posted to Wason as well. It becomes more useful when correlated with UserTaskEvent or OperationEvent which may have led to the fault occurence.
PostOperation(TelemetrySession, String, TelemetryResult, String, TelemetryEventCorrelation[])	Post an Operation event. An operation performs some work in application and comes with result (e.g., Success, Failure). If the operation is invoked by user directly, please use UserTaskEvent or related methods. A few examples of operations are, license check, package load, windows layout loading. This method is used for atomic operation that runs very fast or has little value to analyze the process duration. Caller calls this method when operation is complete. For long-time running or async operation, in order to understand what else happened during the time or track if it partially completes because of an error, use method StartOperation(TelemetrySession, String) which tracks both start and end points.
PostUserTask(TelemetrySession, String, TelemetryResult, String, TelemetryEventCorrelation[])	Post an event for user task. A user task is an application operation that is INVOKED BY USER directly and comes with result (e.g., Success, Failure). It is used for user behavior/intent analysis. User is aware of the operation and be able to execute. e.g. Open project and Show tool windows are user tasks; instead load VS package and Design time build are operations. This method is used for atomic user task that runs very fast or has little value to analyze the process duration. Caller calls this method when user task is complete. For long-time running or async user task, in order to understand what else happened during the time or track if it partially completes because of an error, use method StartUserTask(TelemetrySession, String) which tracks both start and end points.
StartOperation(TelemetrySession, String, TelemetryScopeSettings)	Start tracking operation by posting a OperationEvent with specified properties at the begining of operation work, and return a TelemetryScope<T> object. When the user task finishes, call method End(TelemetryResult, String) to post another OperationEvent for end point. Because the same event name is used by both start and end events, please don't use Start or End in event name.
StartOperation(TelemetrySession, String, TelemetrySeverity, IDictionary<String,Object>, TelemetryEventCorrelation[])	Start tracking operation by posting a OperationEvent with specified properties at the begining of operation work, and return a TelemetryScope<T> object. When the user task finishes, call method End(TelemetryResult, String) to post another OperationEvent for end point. Because the same event name is used by both start and end events, please don't use Start or End in event name.
StartOperation(TelemetrySession, String, TelemetrySeverity, IDictionary<String,Object>)	Start tracking operation by posting a OperationEvent with specified properties at the begining of operation work, and return a TelemetryScope<T> object. When the user task finishes, call method End(TelemetryResult, String) to post another OperationEvent for end point. Because the same event name is used by both start and end events, please don't use Start or End in event name.
StartOperation(TelemetrySession, String, TelemetrySeverity)	Start tracking operation by posting a OperationEvent at the begining of operation work, and return a TelemetryScope<T> object. When the user task finishes, call method End(TelemetryResult, String) to post another OperationEvent for end point. Because the same event name is used by both start and end events, please don't use Start or End in event name.
StartOperation(TelemetrySession, String)	Start tracking operation by posting a OperationEvent at the begining of operation work, and return a TelemetryScope<T> object. When the user task finishes, call method End(TelemetryResult, String) to post another OperationEvent for end point. Because the same event name is used by both start and end events, please don't use Start or End in event name.
StartUserTask(TelemetrySession, String, TelemetryScopeSettings)	Start tracking user task by posting a UserTaskEvent with specified properties at the beginning of user task work, and then return a TelemetryScope<T> object. When the user task finishes, call method End(TelemetryResult, String) to post another UserTaskEvent for end point. Because the same event name is used by both start and end events, please don't use Start or End in event name.
StartUserTask(TelemetrySession, String, TelemetrySeverity, IDictionary<String,Object>, TelemetryEventCorrelation[])	Start tracking user task by posting a UserTaskEvent with specified properties at the beginning of user task work, and then return a TelemetryScope<T> object. When the user task finishes, call method End(TelemetryResult, String) to post another UserTaskEvent for end point. Because the same event name is used by both start and end events, please don't use Start or End in event name.
StartUserTask(TelemetrySession, String, TelemetrySeverity, IDictionary<String,Object>)	Start tracking user task by posting a UserTaskEvent with specified properties at the beginning of user task work, and then return a TelemetryScope<T> object. When the user task finishes, call method End(TelemetryResult, String) to post another UserTaskEvent for end point. Because the same event name is used by both start and end events, please don't use Start or End in event name.
StartUserTask(TelemetrySession, String, TelemetrySeverity)	Start tracking user task by posting a UserTaskEvent at the beginning of user task work, and then return a TelemetryScope<T> object. When the user task finishes, call method End(TelemetryResult, String) to post another UserTaskEvent for end point. Because the same event name is used by both start and end events, please don't use Start or End in event name.
StartUserTask(TelemetrySession, String)	Start tracking user task by posting a UserTaskEvent at the beginning of user task work, and then return a TelemetryScope<T> object. When the user task finishes, call method End(TelemetryResult, String) to post another UserTaskEvent for end point. Because the same event name is used by both start and end events, please don't use Start or End in event name.