ServiceProvider.GetGlobalServiceAsync Method

Definition

Namespace:

Microsoft.VisualStudio.Shell

Assembly:

Microsoft.VisualStudio.Shell.Framework.dll

Package:

Microsoft.VisualStudio.Shell.Framework v17.12.40391

Overloads

GetGlobalServiceAsync(Type)	Retrieves a proffered service asynchronously.
GetGlobalServiceAsync(Type, Boolean)	Retrieves a proffered service asynchronously, specifying a hint whether to throw an exception if it could not be retrieved. It does not, however, guarantee exceptions will be thrown for all failure cases.
GetGlobalServiceAsync<TService,TInterface>(Boolean, CancellationToken)	Retrieves a proffered service asynchronously, specifying whether to throw an exception if it could not be retrieved.
GetGlobalServiceAsync<TService,TInterface>(Boolean)	Retrieves a proffered service asynchronously, specifying whether to throw an exception if it could not be retrieved.
GetGlobalServiceAsync<TService,TInterface>()	Retrieves a proffered service asynchronously, throwing an exception if it could not be retrieved.
GetGlobalServiceAsync<TService,TInterface>(CancellationToken)	Retrieves a proffered service asynchronously, throwing an exception if it could not be retrieved.

GetGlobalServiceAsync(Type)

Retrieves a proffered service asynchronously.

public:
 static System::Threading::Tasks::Task<System::Object ^> ^ GetGlobalServiceAsync(Type ^ serviceType);

public static System.Threading.Tasks.Task<object?> GetGlobalServiceAsync (Type serviceType);

static member GetGlobalServiceAsync : Type -> System.Threading.Tasks.Task<obj>

Public Shared Function GetGlobalServiceAsync (serviceType As Type) As Task(Of Object)

Parameters

serviceType

Type

The service identity of the proffered service to retrieve.

Returns

Task<Object>

A task whose result is one of the following:

• The service if the request was successful.
• null if the service threw an exception during activation.
• null if the associated package failed to load.
• null if the associated package proffered null.
• null if the associated package could not be found, or the package did not correctly proffer the service.
• null if the environment has starting shutting down and the retrieval would have resulted in a package load.
• Otherwise; null if there was any other failure retrieving the service.true.

Exceptions

ArgumentNullException

serviceType is null.

Remarks

Performing an explicit cast of the resulting service to a specific interface could perform a blocking RPC call if the underlying service is STA-bound, which can hang if the UI thread is blocked in a Run(Func<Task>) or Join(CancellationToken). Instead, prefer the generic equivalent GetGlobalServiceAsync<TService,TInterface>(), noting the difference in behavior around exceptions.

This method is safe to access from any thread.

GetGlobalServiceAsync(Type, Boolean)

Retrieves a proffered service asynchronously, specifying a hint whether to throw an exception if it could not be retrieved. It does not, however, guarantee exceptions will be thrown for all failure cases.

public:
 static System::Threading::Tasks::Task<System::Object ^> ^ GetGlobalServiceAsync(Type ^ serviceType, bool swallowExceptions);

public static System.Threading.Tasks.Task<object?> GetGlobalServiceAsync (Type serviceType, bool swallowExceptions);

static member GetGlobalServiceAsync : Type * bool -> System.Threading.Tasks.Task<obj>

Public Shared Function GetGlobalServiceAsync (serviceType As Type, swallowExceptions As Boolean) As Task(Of Object)

Parameters

serviceType

Type

The service identity of the proffered service to retrieve.

swallowExceptions

Boolean

true to return null on failure; otherwise, false to throw an exception if the service could not be retrieved. NOTE, specifying false does not does not guarantee exceptions will be thrown for all failures.

Returns

Task<Object>

A task whose result is one of the following:

• The service if the request was successful.
• null if the associated package proffered null.
• null if the associated package could not be found, or the package did not correctly proffer the service.
• null if the environment has starting shutting down and the retrieval would have resulted in a package load.
• Otherwise; null if there was any other failure retrieving the service and swallowExceptions is true.

Exceptions

ArgumentNullException

serviceType is null.

Exception

swallowExceptions is false and there was failure retrieving the service due to one of the following conditions:

• The service threw an exception during activation. InnerException may include details about the underlying failure.
• The associated package failed to load. InnerException may include details about the underlying failure.

Remarks

Performing an explicit cast of the resulting service to a specific interface could perform a blocking RPC call if the underlying service is STA-bound, which can hang if the UI thread is blocked in a Run(Func<Task>) or Join(CancellationToken). Instead, prefer the generic equivalent GetGlobalServiceAsync<TService,TInterface>(Boolean), noting the difference in behavior around exceptions.

This method is safe to access from any thread.

GetGlobalServiceAsync<TService,TInterface>(Boolean, CancellationToken)

Retrieves a proffered service asynchronously, specifying whether to throw an exception if it could not be retrieved.

public static System.Threading.Tasks.Task<TInterface?> GetGlobalServiceAsync<TService,TInterface> (bool throwOnFailure, System.Threading.CancellationToken cancellationToken) where TService : class where TInterface : class;

static member GetGlobalServiceAsync : bool * System.Threading.CancellationToken -> System.Threading.Tasks.Task<'Interface (requires 'Interface : null)> (requires 'Service : null and 'Interface : null)

Public Shared Function GetGlobalServiceAsync(Of TService As Class, TInterface As Class) (throwOnFailure As Boolean, cancellationToken As CancellationToken) As Task(Of TInterface)

Type Parameters

TService

The service identity of the proffered service to retrieve.

TInterface

The interface used to interact with the proffered service. If TService is not registered as async or free-threaded, then this cast will be performed on the main thread.

Parameters

throwOnFailure

Boolean

true to throw an exception if the service could not be retrieved; otherwise, false to return null on failure.

cancellationToken

CancellationToken

A token whose cancellation indicates that the caller no longer is interested in the result. This will not cancel the in-progress loading of packages and/or creation of services as a result of the service retrieval, but this token will result in an expediant cancellation of the returned Task.

Returns

Task<TInterface>

A task representing the service retrieval whose result is the service or null if there was a failure and throwOnFailure is false.

Exceptions

OperationCanceledException

cancellationToken has been canceled.

ServiceUnavailableException

throwOnFailure is true and there was a failure retrieving the service due to one of the following conditions:

• The service threw an exception during activation. InnerException may include details about the underlying failure.
• The associated package failed to load. InnerException may include details about the underlying failure.
• The associated package could not be found, or the package did not correctly proffer the service.
• The associated package proffered null.
• The service does not support the requested interface specified by TInterface.
• The environment has starting shutting down and the retrieval would have resulted in a package load.

Remarks

Prefer this method over an explicit cast to TInterface to avoid a blocking RPC call if the underlying service is STA-bound, which can hang if the UI thread is blocked in a Run(Func<Task>) or Join(CancellationToken).

Note the difference in behavior this method has around exceptions to its non-generic equivalents GetGlobalServiceAsync(Type) and GetGlobalServiceAsync(Type, Boolean).

This method is safe to access from any thread.

GetGlobalServiceAsync<TService,TInterface>(Boolean)

Retrieves a proffered service asynchronously, specifying whether to throw an exception if it could not be retrieved.

public:
generic <typename TService, typename TInterface>
 where TService : class where TInterface : class static System::Threading::Tasks::Task<TInterface> ^ GetGlobalServiceAsync(bool swallowExceptions);

public static System.Threading.Tasks.Task<TInterface?> GetGlobalServiceAsync<TService,TInterface> (bool throwOnFailure) where TService : class where TInterface : class;

static member GetGlobalServiceAsync : bool -> System.Threading.Tasks.Task<'Interface (requires 'Interface : null)> (requires 'Service : null and 'Interface : null)

Public Shared Function GetGlobalServiceAsync(Of TService As Class, TInterface As Class) (throwOnFailure As Boolean) As Task(Of TInterface)

Type Parameters

TService

The service identity of the proffered service to retrieve.

TInterface

The interface used to interact with the proffered service. If TService is not registered as async or free-threaded, then this cast will be performed on the main thread.

Parameters

throwOnFailure

Boolean

When this parameter is true GetServiceAsync will swallow exceptions thrown during the GetServiceAsync call and return null. When this is false exceptions thrown during the get service call may be thrown out of the method. A setting of false does not guarantee exceptions will be thrown for all services failures, or all service types.

Returns

Task<TInterface>

A task representing the service retrieval whose result is the service or null if there was a failure and throwOnFailure is true.

Exceptions

ServiceUnavailableException

throwOnFailure is true and there was a failure retrieving the service due to one of the following conditions:

• The service threw an exception during activation. InnerException may include details about the underlying failure.
• The associated package failed to load. InnerException may include details about the underlying failure.
• The associated package could not be found, or the package did not correctly proffer the service.
• The associated package proffered null.
• The service does not support the requested interface specified by TInterface.
• The environment has starting shutting down and the retrieval would have resulted in a package load.

Remarks

Prefer this method over an explicit cast to TInterface to avoid a blocking RPC call if the underlying service is STA-bound, which can hang if the UI thread is blocked in a Run(Func<Task>) or Join(CancellationToken).

Note the difference in behavior this method has around exceptions to its non-generic equivalents GetGlobalServiceAsync(Type) and GetGlobalServiceAsync(Type, Boolean).

This method is safe to access from any thread.

GetGlobalServiceAsync<TService,TInterface>()

Retrieves a proffered service asynchronously, throwing an exception if it could not be retrieved.

public:
generic <typename TService, typename TInterface>
 where TService : class where TInterface : class static System::Threading::Tasks::Task<TInterface> ^ GetGlobalServiceAsync();

public static System.Threading.Tasks.Task<TInterface> GetGlobalServiceAsync<TService,TInterface> () where TService : class where TInterface : class;

static member GetGlobalServiceAsync : unit -> System.Threading.Tasks.Task<'Interface (requires 'Interface : null)> (requires 'Service : null and 'Interface : null)

Public Shared Function GetGlobalServiceAsync(Of TService As Class, TInterface As Class) () As Task(Of TInterface)

Type Parameters

TService

The service identity of the proffered service to retrieve.

TInterface

The interface used to interact with the proffered service. If TService is not registered as async or free-threaded, then this cast will be performed on the main thread.

Returns

Task<TInterface>

A task representing the service retrieval whose result is the service.

Exceptions

ServiceUnavailableException

There was a failure retrieving the service due to one of the following conditions:

• The service threw an exception during activation. InnerException may include details about the underlying failure.
• The associated package failed to load. InnerException may include details about the underlying failure.
• The associated package could not be found, or the package did not correctly proffer the service.
• The associated package proffered null.
• The service does not support the requested interface specified by TInterface.
• The environment has starting shutting down and the retrieval would have resulted in a package load.

Remarks

Prefer this method over an explicit cast to TInterface to avoid a blocking RPC call if the underlying service is STA-bound, which can hang if the UI thread is blocked in a Run(Func<Task>) or Join(CancellationToken).

Note the difference in behavior this method has around exceptions to its non-generic equivalents GetGlobalServiceAsync(Type) and GetGlobalServiceAsync(Type, Boolean).

This method is safe to access from any thread.

GetGlobalServiceAsync<TService,TInterface>(CancellationToken)

Retrieves a proffered service asynchronously, throwing an exception if it could not be retrieved.

public static System.Threading.Tasks.Task<TInterface> GetGlobalServiceAsync<TService,TInterface> (System.Threading.CancellationToken cancellationToken) where TService : class where TInterface : class;

static member GetGlobalServiceAsync : System.Threading.CancellationToken -> System.Threading.Tasks.Task<'Interface (requires 'Interface : null)> (requires 'Service : null and 'Interface : null)

Public Shared Function GetGlobalServiceAsync(Of TService As Class, TInterface As Class) (cancellationToken As CancellationToken) As Task(Of TInterface)

Type Parameters

TService

The service identity of the proffered service to retrieve.

TInterface

The interface used to interact with the proffered service. If TService is not registered as async or free-threaded, then this cast will be performed on the main thread.

Parameters

cancellationToken

CancellationToken

A token whose cancellation indicates that the caller no longer is interested in the result. This will not cancel the in-progress loading of packages and/or creation of services as a result of the service retrieval, but this token will result in an expediant cancellation of the returned Task.

Returns

Task<TInterface>

A task representing the service retrieval whose result is the service.

Exceptions

OperationCanceledException

cancellationToken has been canceled.

ServiceUnavailableException

There was a failure retrieving the service due to one of the following conditions:

• The service threw an exception during activation. InnerException may include details about the underlying failure.
• The associated package failed to load. InnerException may include details about the underlying failure.
• The associated package could not be found, or the package did not correctly proffer the service.
• The associated package proffered null.
• The service does not support the requested interface specified by TInterface.
• The environment has starting shutting down and the retrieval would have resulted in a package load.

Remarks

Prefer this method over an explicit cast to TInterface to avoid a blocking RPC call if the underlying service is STA-bound, which can hang if the UI thread is blocked in a Run(Func<Task>) or Join(CancellationToken).

Note the difference in behavior this method has around exceptions to its non-generic equivalents GetGlobalServiceAsync(Type) and GetGlobalServiceAsync(Type, Boolean).

This method is safe to access from any thread.