VpnChannel.ActivateForeground(String, ValueSet) Method

Definition

Namespace:

Windows.Networking.Vpn

Activates the VPN app in the foreground. This is often used to let the user enter credentials. You can call ActivateForeground only from your implementation of IVpnPlugin.Connect. While the app is in the foreground, the regular Connect timeout is paused.

The ActivateForeground call will be cancelled if there's a long pause (about 10 minutes). If unable to launch, then the plugin should ideally support an authentication method that doesn't need user interface (UI).

Intended to support web-based authentication schemes such as Security Assertion Markup Language (SAML) and Azure Active Directory (AAD) authentication.

public:
 virtual ValueSet ^ ActivateForeground(Platform::String ^ packageRelativeAppId, ValueSet ^ sharedContext) = ActivateForeground;

ValueSet ActivateForeground(winrt::hstring const& packageRelativeAppId, ValueSet const& sharedContext);

public ValueSet ActivateForeground(string packageRelativeAppId, ValueSet sharedContext);

function activateForeground(packageRelativeAppId, sharedContext)

Public Function ActivateForeground (packageRelativeAppId As String, sharedContext As ValueSet) As ValueSet

Parameters

packageRelativeAppId

String

Platform::String

winrt::hstring

A string containing the package-relative application identifier (PRAID) of the foreground app to launch.

sharedContext

ValueSet

A ValueSet object used to pass information to the foreground app. The foreground app can access these from the activation event arguments.

Returns

ValueSet

A ValueSet object containing a Windows Runtime object of your choosing that's passed back from the foreground app to the VPN plugin, indicating the result of the foreground request.

Windows requirements

Device family	Windows 11 (introduced in 10.0.22000.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v14.0)
App capabilities	networkingVpnProvider

Remarks

Note

Calling this API outside of the IVpnPlugin.Connect method implementation in a VPN plug-in will fail.

Using the foreground activation mechanism requires handling the activation in several places.

In your IVpnPlugin.Connect method, you'll call ActivateForeground with the correct package-relative application identifier (PRAID), and a ValueSet that contains all of the values that you want to send to your foreground app.

In the foreground app, you need to catch the activation. The foreground app will be activated with a Windows.ApplicationModel.ActivationKind value of VpnForeground. The activation arguments will be of type Windows.Networking.Vpn.VpnForegroundActivatedEventArgs, and will include three fields.

1. ProfileName (String).
2. SharedContext (ValueSet).
3. ActivationOperation (Windows.Networking.Vpn.VpnForegroundActivationOperation.

The foreground app can then set up your app's user interface (UI) to handle the needed authorization (or whatever data is needed). When done, you must call the Complete method of the ActivationOperation, passing in a ValueSet of values that you want to be returned to the IVpnPlugin.Connect call.

Back in the IVpnPlugin.Connect call, use the ValueSet returned from ActivateForeground to decide whether the authentication was successful, and handle any errors.