CoreApplication CoreApplication CoreApplication Class

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

Syntax

Declaration

public static class CoreApplicationpublic static class CoreApplicationPublic Static Class CoreApplication

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 summary

Gets the package-relative app identifier for the process.

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

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

Gets all views for the app.

Methods summary

Creates a new view for the app.

Creates a new view for the app.

Creates a new view for the app.

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

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

Shuts down the app.

Gets the active view for the app.

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

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

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

Events summary

Fired when your app is activated by a background trigger.

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

Occurs when the app is shutting down.

Fired just before application UI becomes visible.

Occurs when an app is resuming.

Occurs when the app is suspending.

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

Properties

  • Id
    Id
    Id
    Id

    Gets the package-relative app identifier for the process.

    public static string Id { get; }public static string Id { get; }Public Static ReadOnly Property Id As stringpublic static string Id { get; }

    Property Value

    • 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 CoreApplicationViewpublic static CoreApplicationView MainView { get; }

    Property Value

    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 IPropertySetpublic static IPropertySet Properties { get; }

    Property Value

  • Views
    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>public static IVectorView<CoreApplicationView> Views { get; }

    Property Value

    • 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 CoreApplicationViewpublic static CoreApplicationView CreateNewView()

    Returns

  • CreateNewView(String, String)
    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 CoreApplicationViewpublic static CoreApplicationView CreateNewView(String runtimeType, String entryPoint)

    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

  • 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 CoreApplicationViewpublic static CoreApplicationView CreateNewView(IFrameworkViewSource viewSource)

    Parameters

    Returns

  • 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 voidpublic static void DecrementApplicationUseCount()

    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(Boolean value)public static void EnablePrelaunch(Boolean value)Public Static Function EnablePrelaunch(value As Boolean) As voidpublic static void EnablePrelaunch(Boolean value)

    Parameters

    • value
      System.Boolean
      System.Boolean
      System.Boolean

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

    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 voidpublic static void Exit()

    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 CoreApplicationViewpublic static CoreApplicationView GetCurrentView()

    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 voidpublic static void IncrementApplicationUseCount()

    Remarks

    Windows Phone 8

    This API is supported in native apps only.

  • 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 voidpublic static void Run(IFrameworkViewSource viewSource)

    Parameters

    Remarks

    Windows Phone 8

    This API is supported in native apps only.

  • 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 voidpublic static void RunWithActivationFactories(IGetActivationFactory activationFactoryCallback)

    Parameters

    Remarks

    Windows Phone 8

    This API is supported in native apps only.

Events

  • BackgroundActivated
    BackgroundActivated
    BackgroundActivated
    BackgroundActivated

    Fired when your app is activated by a background trigger.

    public static event EventHandler BackgroundActivatedpublic static event EventHandler BackgroundActivatedPublic Static Event BackgroundActivatedpublic static event EventHandler BackgroundActivated

    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 Run(IBackgroundTaskInstance) 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 EnteredBackgroundpublic static event EventHandler EnteredBackgroundPublic Static Event EnteredBackgroundpublic static event EventHandler EnteredBackground

    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 Exitingpublic static event EventHandler ExitingPublic Static Event Exitingpublic static event EventHandler Exiting

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

    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 Resumingpublic static event EventHandler ResumingPublic Static Event Resumingpublic static event EventHandler Resuming

    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 Suspendingpublic static event EventHandler SuspendingPublic Static Event Suspendingpublic static event EventHandler Suspending

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

    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.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.MuseAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.ApplicationModel.Core.dll