CoreApplication CoreApplication CoreApplication CoreApplication Class

Definition

Enables apps to handle state changes, manage windows, and integrate with a variety of UI frameworks.

public : static class CoreApplicationpublic static class CoreApplicationPublic Static Class CoreApplication// This API is not available in Javascript.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The system creates this object as a singleton when it runs the app. It is run as an Application Single-Threaded Apartment (ASTA). Threads created from the app singleton, such as the view provider (seen in the sample below), should be attributed as Multi-Threaded Apartment (MTAThread).

ref class MyFrameworkViewSource : IFrameworkViewSource
{
public:
    virtual IFrameworkView^ CreateView()
    {
        return ref new MyFrameworkView();
    }
};

// ...

[Platform::MTAThread]
int main(Platform::Array<Platform::String^>^)
{
    auto frameworkViewSource = ref new MyFrameworkViewSource();
    Windows::ApplicationModel::Core::CoreApplication::Run(frameworkViewSource);
    return 0;
}

Windows Phone 8

This API is supported in native apps only, except for the Properties property, which is always available.

Properties

Id Id Id Id

Gets the package-relative app identifier for the process.

public : static PlatForm::String Id { get; }public static string Id { get; }Public Static ReadOnly Property Id As string// This API is not available in Javascript.
Value
PlatForm::String string string string

The package-relative app identifier for the process.

Remarks

Windows Phone 8

This API is supported in native apps only.

MainView MainView MainView MainView

Gets the main CoreApplicationView instance for all running apps that use this CoreApplication instance.

public : static CoreApplicationView MainView { get; }public static CoreApplicationView MainView { get; }Public Static ReadOnly Property MainView As CoreApplicationView// This API is not available in Javascript.

Remarks

A CoreApplicationView is the app window and its thread.

Windows Phone 8

This API is supported in native apps only.

Properties Properties Properties Properties

Gets a property set that the app and UI frameworks can use to store info while the process is running.

public : static IPropertySet Properties { get; }public static IPropertySet Properties { get; }Public Static ReadOnly Property Properties As IPropertySet// This API is not available in Javascript.

Views Views Views Views

Gets all views for the app.

public : static IVectorView<CoreApplicationView> Views { get; }public static IReadOnlyList<CoreApplicationView> Views { get; }Public Static ReadOnly Property Views As IReadOnlyList<CoreApplicationView>// This API is not available in Javascript.
Value
IVectorView<CoreApplicationView> IReadOnlyList<CoreApplicationView> IReadOnlyList<CoreApplicationView> IReadOnlyList<CoreApplicationView>

All of the app's views.

Remarks

A view is an app window and its thread.

Windows Phone 8

This API is supported in native apps only.

Methods

CreateNewView() CreateNewView() CreateNewView() CreateNewView()

Creates a new view for the app.

public : static CoreApplicationView CreateNewView()public static CoreApplicationView CreateNewView()Public Static Function CreateNewView() As CoreApplicationView// This API is not available in Javascript.
Returns
See Also

CreateNewView(String, String) CreateNewView(String, String) CreateNewView(String, String) CreateNewView(String, String)

Creates a new view for the app.

public : static CoreApplicationView CreateNewView(PlatForm::String runtimeType, PlatForm::String entryPoint)public static CoreApplicationView CreateNewView(String runtimeType, String entryPoint)Public Static Function CreateNewView(runtimeType As String, entryPoint As String) As CoreApplicationView// This API is not available in Javascript.
Parameters
runtimeType
PlatForm::String String String String

The class ID of the view provider for the new view. If this parameter is null, use the current view provider.

entryPoint
PlatForm::String String String String

Additional info about the view, such as its class name in the app code.

Returns
See Also

CreateNewView(IFrameworkViewSource) CreateNewView(IFrameworkViewSource) CreateNewView(IFrameworkViewSource) CreateNewView(IFrameworkViewSource)

Creates a new view for the app.

public : static CoreApplicationView CreateNewView(IFrameworkViewSource viewSource)public static CoreApplicationView CreateNewView(IFrameworkViewSource viewSource)Public Static Function CreateNewView(viewSource As IFrameworkViewSource) As CoreApplicationView// This API is not available in Javascript.
Parameters
Returns
See Also

DecrementApplicationUseCount() DecrementApplicationUseCount() DecrementApplicationUseCount() DecrementApplicationUseCount()

Decrements the total count of running app instances that use this CoreApplication instance.

public : static void DecrementApplicationUseCount()public static void DecrementApplicationUseCount()Public Static Function DecrementApplicationUseCount() As void// This API is not available in Javascript.

Remarks

Windows Phone 8

This API is supported in native apps only.

EnablePrelaunch(Boolean) EnablePrelaunch(Boolean) EnablePrelaunch(Boolean) EnablePrelaunch(Boolean)

Enable or disable the operating system's ability to prelaunch your app.

public : static void EnablePrelaunch(bool value)public static void EnablePrelaunch(Boolean value)Public Static Function EnablePrelaunch(value As Boolean) As void// This API is not available in Javascript.
Parameters
value
bool Boolean Boolean Boolean

True to enable prelaunch for your app; false, otherwise.

Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

When available system resources allow, the startup performance of Windows Store apps is improved by proactively launching the user’s most frequently used Windows Store apps in the background. A prelaunched app is put into the suspended state shortly after it is launched. When the user invokes the app, the app is resumed by bringing it from the suspended state to the running state--which is faster than launching the app cold.

Windows 10 automatically prelaunched Windows Store apps. In Windows 10, version 1607, Windows Store apps must opt-in to be prelaunched. You will typically make this call during the first run of your app although you may call the function multiple times and with different values without harm.

Exit() Exit() Exit() Exit()

Shuts down the app.

public : static void Exit()public static void Exit()Public Static Function Exit() As void// This API is not available in Javascript.

Remarks

Starting with Windows 10, calling this method is no longer is treated as an app crash.

Don't call this method from within an activation event handler.

Windows Phone 8

This API is supported in native apps only.

GetCurrentView() GetCurrentView() GetCurrentView() GetCurrentView()

Gets the active view for the app.

public : static CoreApplicationView GetCurrentView()public static CoreApplicationView GetCurrentView()Public Static Function GetCurrentView() As CoreApplicationView// This API is not available in Javascript.
Returns

Remarks

A CoreApplicationView is an app window and its thread.

Windows Phone 8

This API is supported in native apps only.

IncrementApplicationUseCount() IncrementApplicationUseCount() IncrementApplicationUseCount() IncrementApplicationUseCount()

Increments the total count of running app instances that use this CoreApplication instance.

public : static void IncrementApplicationUseCount()public static void IncrementApplicationUseCount()Public Static Function IncrementApplicationUseCount() As void// This API is not available in Javascript.

Remarks

Windows Phone 8

This API is supported in native apps only.

RequestRestartAsync(String) RequestRestartAsync(String) RequestRestartAsync(String) RequestRestartAsync(String)

Restart the app.

public : static IAsyncOperation<RestartResult> RequestRestartAsync(PlatForm::String launchArguments)public static IAsyncOperation<RestartResult> RequestRestartAsync(String launchArguments)Public Static Function RequestRestartAsync(launchArguments As String) As IAsyncOperation( Of RestartResult )// This API is not available in Javascript.
Parameters
launchArguments
PlatForm::String String String String

The arguments to pass to the restarted instance.

Returns
Additional features and requirements
Device family
Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

Examples

private async void DoMajorAppReconfiguration()
{

    // Attempt restart, with arguments.

    AppRestartFailureReason result =

        await CoreApplication.RequestRestartAsync("-fastInit -level 1 -foo");



    // Restart request denied, send a toast to tell the user to restart manually.

    if (result == AppRestartFailureReason.NotInForeground

        || result == AppRestartFailureReason.Other)

    {

        SendToast("Please manually restart.");

    }

}

Remarks

  • The app must be visible and foreground when it calls this API.
  • If the restart fails, but the user subsequently launches the app manually, the app will launch normally and no restart arguments will be passed.
  • If the app wasn't launched in the normal way, but was launched by a share contract, file picker, app-service, and so on, the app should not call this API because the user will not expect the resulting behavior.
  • The app is responsible for ensuring the validity of the User object. The activation will fail if there is policy in place which prevents that user from executing the app.
  • The app should not request an Extended Execution session after it has called this API because that will result in a poor user experience.
  • If the app has any in-process background tasks running when it calls this API, those tasks will be cancelled in the normal way. Out-of-process background tasks will not be affected.
  • When the app is restarted, LaunchActivatedEventArgs.PreviousExecutionState will have the value Terminated so that the app can distinguish between a resume and a restart.
See Also

RequestRestartForUserAsync(User, String) RequestRestartForUserAsync(User, String) RequestRestartForUserAsync(User, String) RequestRestartForUserAsync(User, String)

Restart the app in the context of a different user.

public : static IAsyncOperation<RestartResult> RequestRestartForUserAsync(User user, PlatForm::String launchArguments)public static IAsyncOperation<RestartResult> RequestRestartForUserAsync(User user, String launchArguments)Public Static Function RequestRestartForUserAsync(user As User, launchArguments As String) As IAsyncOperation( Of RestartResult )// This API is not available in Javascript.
Parameters
user
User User User User

The user to restart the app as.

launchArguments
PlatForm::String String String String

The arguments to pass to the restarted instance.

Returns
Additional features and requirements
Device family
Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

Examples

private async void RestartAsAnotherUser(string selectedUser)
{

    IReadOnlyList<User> users = await User.FindAllAsync();

    foreach (User user in users)

    {

        object accountProperty =

            await user.GetPropertyAsync(KnownUserProperties.AccountName);

        string accountName = (string)accountProperty;

        if (accountName == selectedUser)

        {

            // Attempt restart, with arguments.

            AppRestartFailureReason result = await App.RequestRestartForUserAsync(

                user, "-fastInit -mainMenu");



            // Restart request denied, tell the user to restart manually.

            if (result== AppRestartFailureReason.InvalidUser)

            {

                SendToast(string.Format("Could not restart as user {0} - please manually restart.", user));

            }

        }

    }

}

Remarks

  • The app must be visible and foreground when it calls this API.
  • If the restart fails, but the user subsequently launches the app manually, the app will launch normally and no restart arguments will be passed.
  • If the app wasn't launched in the normal way, but was launched by a share contract, file picker, app-service, and so on, the app should not call this API because the user will not expect the resulting behavior.
  • The app is responsible for ensuring the validity of the User object. The activation will fail if there is policy in place which prevents that user from executing the app.
  • The app should not request an Extended Execution session after it has called this API because that will result in a poor user experience.
  • If the app has any in-process background tasks running when it calls this API, those tasks will be cancelled in the normal way. Out-of-process background tasks will not be affected.
  • When the app is restarted, LaunchActivatedEventArgs.PreviousExecutionState will have the value Terminated so that the app can distinguish between a resume and a restart.
See Also

Run(IFrameworkViewSource) Run(IFrameworkViewSource) Run(IFrameworkViewSource) Run(IFrameworkViewSource)

Runs an external view provider factory to obtain a view provider.

public : static void Run(IFrameworkViewSource viewSource)public static void Run(IFrameworkViewSource viewSource)Public Static Function Run(viewSource As IFrameworkViewSource) As void// This API is not available in Javascript.
Parameters
viewSource
IFrameworkViewSource IFrameworkViewSource IFrameworkViewSource IFrameworkViewSource

An implementation of a view provider factory.

Remarks

Windows Phone 8

This API is supported in native apps only.

See Also

RunWithActivationFactories(IGetActivationFactory) RunWithActivationFactories(IGetActivationFactory) RunWithActivationFactories(IGetActivationFactory) RunWithActivationFactories(IGetActivationFactory)

Runs an activatable type factory to obtain an external activatable type.

public : static void RunWithActivationFactories(IGetActivationFactory activationFactoryCallback)public static void RunWithActivationFactories(IGetActivationFactory activationFactoryCallback)Public Static Function RunWithActivationFactories(activationFactoryCallback As IGetActivationFactory) As void// This API is not available in Javascript.
Parameters
activationFactoryCallback
IGetActivationFactory IGetActivationFactory IGetActivationFactory IGetActivationFactory

An implementation of an activatable type factory.

Remarks

Windows Phone 8

This API is supported in native apps only.

See Also

Events

BackgroundActivated BackgroundActivated BackgroundActivated BackgroundActivated

Fired when your app is activated by a background trigger.

public : static event EventHandler BackgroundActivated<BackgroundActivatedEventArgs>public static event EventHandler BackgroundActivated<BackgroundActivatedEventArgs>Public Static Event BackgroundActivated<BackgroundActivatedEventArgs>// This API is not available in Javascript.
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

Register your background triggers with BackgroundTaskBuilder, but do not set the TaskEntryPoint. This will enable this event to fire when your trigger is signaled. The event handler has a BackgroundActivatedEventArgs parameter which contains everything that the IBackgroundTask.Run method delivers.

Tip

By the time an app enters the background state, none of its UI is visible.

EnteredBackground EnteredBackground EnteredBackground EnteredBackground

Fired when the app enters the running in the background state.

public : static event EventHandler EnteredBackground<EnteredBackgroundEventArgs>public static event EventHandler EnteredBackground<EnteredBackgroundEventArgs>Public Static Event EnteredBackground<EnteredBackgroundEventArgs>// This API is not available in Javascript.
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

This event is fired when your app is no longer visible in the foreground.

Previously your suspending callback was the best place to save state after a user finished a session with your app. However, now an application may continue running in the background and then move back to the foreground due to trigger activity without ever reaching the suspended state. The best place to save data after a user session is in your entered background event handler.

Memory limits also change as an app moves into the background. It is best to check the MemoryManager and release memory if needed to ensure your app does not get terminated.

Exiting Exiting Exiting Exiting

Occurs when the app is shutting down.

public : static event EventHandler Exiting<object>public static event EventHandler Exiting<object>Public Static Event Exiting<object>// This API is not available in Javascript.

Remarks

Windows Phone 8

This API is supported in native apps only.

LeavingBackground LeavingBackground LeavingBackground LeavingBackground

Fired just before application UI becomes visible.

public : static event EventHandler LeavingBackground<LeavingBackgroundEventArgs>public static event EventHandler LeavingBackground<LeavingBackgroundEventArgs>Public Static Event LeavingBackground<LeavingBackgroundEventArgs>// This API is not available in Javascript.
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

Previously the best location to load UI was in your activated or resuming event handler. Now your handler for the LeavingBackground event is the best place to do your final checks to ensure that the UI is ready for presentation. It is important to check that visual assets are ready by this time because this is the last opportunity to do work before your application is visible to the user.

Resuming Resuming Resuming Resuming

Occurs when an app is resuming.

public : static event EventHandler Resuming<object>public static event EventHandler Resuming<object>Public Static Event Resuming<object>// This API is not available in Javascript.

Remarks

Windows Phone 8

This API is supported in native apps only.

Suspending Suspending Suspending Suspending

Occurs when the app is suspending.

public : static event EventHandler Suspending<SuspendingEventArgs>public static event EventHandler Suspending<SuspendingEventArgs>Public Static Event Suspending<SuspendingEventArgs>// This API is not available in Javascript.

Remarks

Windows Phone 8

This API is supported in native apps only.

UnhandledErrorDetected UnhandledErrorDetected UnhandledErrorDetected UnhandledErrorDetected

Occurs when there is an underlying error that is routed to the CoreApplication instance, as part of global error handling logic.

public : static event EventHandler UnhandledErrorDetected<UnhandledErrorDetectedEventArgs>public static event EventHandler UnhandledErrorDetected<UnhandledErrorDetectedEventArgs>Public Static Event UnhandledErrorDetected<UnhandledErrorDetectedEventArgs>// This API is not available in Javascript.

Remarks

As part of an app's life cycle management code, developers can inspect error data (UnhandledError ) from an UnhandledErrorDetected event, and choose whether to mark the error as handled. If the error is marked handled in the event data, then execution can continue. If the error is not marked handled, the app and its process will be terminated.

Errors that can fire UnhandledErrorDetected include errors that are thrown by code within an async completed handler.

UnhandledErrorDetected will occur if an app-code event handler throws an error, but the reason that the handler was executed was that system code (not app code) raised the event. App code doesn't always see that error or see that the handler executed.

Returning a failure from any delegate clears the handled state of the error.

See Also