TelemetrySession Class

Definition

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 hang 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

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

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

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

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.

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.

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).

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).

RegisterForReliabilityEvent()
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

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)

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, 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, 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, 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, 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)

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, 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, 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.

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)

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, 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)

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, 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, 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.

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.

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)

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, 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, 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.

Applies to