Core​Application Core​Application Core​Application 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
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

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
Value
string string string

The package-relative app identifier for the process.

Attributes

Remarks

Windows Phone 8

This API is supported in native apps only.

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
Attributes

Remarks

A CoreApplicationView is the app window and its thread.

Windows Phone 8

This API is supported in native apps only.

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
Value
IPropertySet IPropertySet IPropertySet

The property set.

Attributes

Views Views Views

Gets all views for the app.

public static IVectorView<CoreApplicationView> Views { get; }public static IVectorView<CoreApplicationView> Views { get; }Public Static ReadOnly Property Views As IVectorView<CoreApplicationView>
Value

All of the app's views.

Attributes

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

Creates a new view for the app.

public static CoreApplicationView CreateNewView()public static CoreApplicationView CreateNewView()Public Static Function CreateNewView() As CoreApplicationView
Returns
Attributes

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

Creates a new view for the app.

public static CoreApplicationView CreateNewView(String runtimeType, String entryPoint)public static CoreApplicationView CreateNewView(String runtimeType, String entryPoint)Public Static Function CreateNewView(runtimeType As String, entryPoint As String) As CoreApplicationView
Parameters
runtimeType
System.String System.String System.String

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

entryPoint
System.String System.String System.String

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

Returns
Attributes

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
Parameters
viewSource
IFrameworkViewSource IFrameworkViewSource IFrameworkViewSource

The view provider for the new view.

Returns
Attributes

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
Attributes

Remarks

Windows Phone 8

This API is supported in native apps only.

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

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

public static void EnablePrelaunch(Boolean value)public static void EnablePrelaunch(Boolean value)Public Static Function EnablePrelaunch(value As Boolean) As void
Parameters
value
System.Boolean System.Boolean System.Boolean

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

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

Shuts down the app.

public static void Exit()public static void Exit()Public Static Function Exit() As void
Attributes

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

Gets the active view for the app.

public static CoreApplicationView GetCurrentView()public static CoreApplicationView GetCurrentView()Public Static Function GetCurrentView() As CoreApplicationView
Returns
Attributes

Remarks

A CoreApplicationView is an app window and its thread.

Windows Phone 8

This API is supported in native apps only.

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
Attributes

Remarks

Windows Phone 8

This API is supported in native apps only.

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

Prerelease.

public static IAsyncOperation<RestartResult> RequestRestartAsync(String launchArguments)public static IAsyncOperation<RestartResult> RequestRestartAsync(String launchArguments)Public Static Function RequestRestartAsync(launchArguments As String) As IAsyncOperation( Of RestartResult )
Parameters
launchArguments
System.String System.String System.String
Returns
Attributes
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.16190.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

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

Prerelease.

public static IAsyncOperation<RestartResult> RequestRestartForUserAsync(User user, 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 )
Parameters
user
User User User
launchArguments
System.String System.String System.String
Returns
Attributes
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.16190.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

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
Parameters
viewSource
IFrameworkViewSource IFrameworkViewSource IFrameworkViewSource

An implementation of a view provider factory.

Attributes

Remarks

Windows Phone 8

This API is supported in native apps only.

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
Parameters
activationFactoryCallback
IGetActivationFactory IGetActivationFactory IGetActivationFactory

An implementation of an activatable type factory.

Attributes

Remarks

Windows Phone 8

This API is supported in native apps only.

Events

BackgroundActivated BackgroundActivated BackgroundActivated

Fired when your app is activated by a background trigger.

public static event EventHandler BackgroundActivatedpublic static event EventHandler BackgroundActivatedPublic Static Event BackgroundActivated
Attributes
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

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

public static event EventHandler EnteredBackgroundpublic static event EventHandler EnteredBackgroundPublic Static Event EnteredBackground
Attributes
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

Occurs when the app is shutting down.

public static event EventHandler Exitingpublic static event EventHandler ExitingPublic Static Event Exiting
Attributes

Remarks

Windows Phone 8

This API is supported in native apps only.

LeavingBackground LeavingBackground LeavingBackground

Fired just before application UI becomes visible.

public static event EventHandler LeavingBackgroundpublic static event EventHandler LeavingBackgroundPublic Static Event LeavingBackground
Attributes
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

Occurs when an app is resuming.

public static event EventHandler Resumingpublic static event EventHandler ResumingPublic Static Event Resuming
Attributes

Remarks

Windows Phone 8

This API is supported in native apps only.

Suspending Suspending Suspending

Occurs when the app is suspending.

public static event EventHandler Suspendingpublic static event EventHandler SuspendingPublic Static Event Suspending
Attributes

Remarks

Windows Phone 8

This API is supported in native apps only.

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 UnhandledErrorDetectedpublic static event EventHandler UnhandledErrorDetectedPublic Static Event UnhandledErrorDetected
Attributes

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