Share via


ServiceExtensions.GetServiceAsync Method

Definition

Overloads

GetServiceAsync<TService,TInterface>(IAsyncServiceProvider)

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

GetServiceAsync<TService,TInterface>(IAsyncServiceProvider, Boolean)

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

GetServiceAsync<TService,TInterface>(IAsyncServiceProvider, CancellationToken)

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

GetServiceAsync<TService,TInterface>(IAsyncServiceProvider, Boolean, CancellationToken)

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

GetServiceAsync<TService,TInterface>(IAsyncServiceProvider)

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

public:
generic <typename TService, typename TInterface>
 where TInterface : class[System::Runtime::CompilerServices::Extension]
 static System::Threading::Tasks::Task<TInterface> ^ GetServiceAsync(Microsoft::VisualStudio::Shell::IAsyncServiceProvider ^ asp);
public static System.Threading.Tasks.Task<TInterface> GetServiceAsync<TService,TInterface> (this Microsoft.VisualStudio.Shell.IAsyncServiceProvider asp) where TInterface : class;
static member GetServiceAsync : Microsoft.VisualStudio.Shell.IAsyncServiceProvider -> System.Threading.Tasks.Task<'Interface (requires 'Interface : null)> (requires 'Interface : null)
<Extension()>
Public Function GetServiceAsync(Of TService, TInterface) (asp As IAsyncServiceProvider) 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

Returns

Task<TInterface>

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

Exceptions

asp is null

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). This method delegates onto IAsyncServiceProvider3 if asp implements it.

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

This method is safe to access from any thread.

Applies to

GetServiceAsync<TService,TInterface>(IAsyncServiceProvider, Boolean)

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

public static System.Threading.Tasks.Task<TInterface?> GetServiceAsync<TService,TInterface> (this Microsoft.VisualStudio.Shell.IAsyncServiceProvider asp, bool throwOnFailure = true) where TInterface : class;
public static System.Threading.Tasks.Task<TInterface?> GetServiceAsync<TService,TInterface> (this Microsoft.VisualStudio.Shell.IAsyncServiceProvider asp, bool throwOnFailure) where TInterface : class;
static member GetServiceAsync : Microsoft.VisualStudio.Shell.IAsyncServiceProvider * bool -> System.Threading.Tasks.Task<'Interface (requires 'Interface : null)> (requires 'Interface : null)
<Extension()>
Public Function GetServiceAsync(Of TService, TInterface) (asp As IAsyncServiceProvider, Optional throwOnFailure As Boolean = true) As Task(Of TInterface)
<Extension()>
Public Function GetServiceAsync(Of TService, TInterface) (asp As IAsyncServiceProvider, 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

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

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

asp is null

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). This method delegates onto IAsyncServiceProvider3 if asp implements it.

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

This method is safe to access from any thread.

Applies to

GetServiceAsync<TService,TInterface>(IAsyncServiceProvider, CancellationToken)

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

public static System.Threading.Tasks.Task<TInterface> GetServiceAsync<TService,TInterface> (this Microsoft.VisualStudio.Shell.IAsyncServiceProvider asp, System.Threading.CancellationToken cancellationToken) where TInterface : class;
static member GetServiceAsync : Microsoft.VisualStudio.Shell.IAsyncServiceProvider * System.Threading.CancellationToken -> System.Threading.Tasks.Task<'Interface (requires 'Interface : null)> (requires 'Interface : null)
<Extension()>
Public Function GetServiceAsync(Of TService, TInterface) (asp As IAsyncServiceProvider, 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

asp is null

cancellationToken has been canceled.

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). This method delegates onto IAsyncServiceProvider3 if asp implements it.

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

This method is safe to access from any thread.

Applies to

GetServiceAsync<TService,TInterface>(IAsyncServiceProvider, 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?> GetServiceAsync<TService,TInterface> (this Microsoft.VisualStudio.Shell.IAsyncServiceProvider asp, bool throwOnFailure, System.Threading.CancellationToken cancellationToken) where TInterface : class;
static member GetServiceAsync : Microsoft.VisualStudio.Shell.IAsyncServiceProvider * bool * System.Threading.CancellationToken -> System.Threading.Tasks.Task<'Interface (requires 'Interface : null)> (requires 'Interface : null)
<Extension()>
Public Function GetServiceAsync(Of TService, TInterface) (asp As IAsyncServiceProvider, 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

asp is null

cancellationToken has been canceled.

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). This method delegates onto IAsyncServiceProvider3 if asp implements it.

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

This method is safe to access from any thread.

Applies to