Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Namespace: Windows.UI.Shell.Tasks
Provides support for apps that execute long running tasks to provide a representation of the task in the Taskbar.
AppTaskState enum
Defines constants that specify the state of the app task.
[contract(TaskContract, 1)]
[experimental]
public enum AppTaskState
| Name | Value | Description |
|---|---|---|
Running |
0 | Task is created and running, we don't have a separate Created state. |
Completed |
1 | Task completed. |
NeedsAttention |
2 | Task is paused and needs user attention to continue. |
Paused |
3 | Task is paused, but can be resumed without user intervention. |
Error |
4 | Task stopped permanently because of an unrecoverable error. |
AppTaskResultAsset class
Represents an asset that is generated by the app task.
You can use this if your app creates a file, for example. This class is used as input into the AppTaskContent.CreateGeneratedAssetsResult method.
Constructor
AppTaskResultAsset(String name, String context, Uri iconUri, Uri assetUri);
Parameters
name String
The name of the generated asset.
context String
A description of the task context.
iconUri Uri
A path the icon that represents the task.
assetUri Uri
The path to the asset generated by the app task.
AppTaskContent class
Represents the task content shown in the UI that is displayed on hover over the app's taskbar icon.
Remarks
This class represents the task content and is used to create the UI that is displayed on hover. This can be constructed for the different supported representations and modified as the state of the task changes. Builder methods allow additional elements to be added (buttons or a text input field) when appropriate.
Properties
MaxButtons
Gets the maximum number of buttons.
static UInt32 MaxButtons{ get; };
Property value
The maximum number of buttons.
Methods
CreateSequenceOfSteps
Builds a sequence of steps being executed by the app task to display in the UI.
static AppTaskContent CreateSequenceOfSteps(String[] completedSteps, String executingStep);
Parameters
completedSteps String[]
An array of strings that describe the task steps that have been completed.
executingStep String
A string that describes the step that the task is currently working on.
Returns
An instance of AppTaskContent with the created sequence of steps.
CreatePreviewThumbnail
Creates a thumbnail preview of the task output for tasks that create images.
static AppTaskContent CreatePreviewThumbnail(Windows.Foundation.Uri imageUri, String executingStep);
Parameters
imageUri Uri
The path the image preview.
executingStep String
A string that describes the step that the task is currently working on.
Returns
An instance of AppTaskContent with the created image preview and step.
CreateTextSummaryResult
Creates a text summary of the task results.
static AppTaskContent CreateTextSummaryResult(String text);
Parameters
text String
Text that describes the result of the task.
Returns
An instance of AppTaskContent that contains the text description of the task results.
CreateGeneratedAssetsResult
Creates a display of assets generated by the app task.
static AppTaskContent CreateGeneratedAssetsResult(AppTaskResultAsset[] assets);
Parameters
assets AppTaskResultAsset[]
An array of AppTaskResultAsset objects that describe the assets generated by the task.
Returns
An instance of AppTaskContent with the created assets.
AddButton
Adds a button the content of the app task UI.
void AddButton(String text, Windows.Foundation.Uri actionUri);
Parameters
text String
The button label.
actionUri Uri
The path to an app action using an app-defined deep link URI scheme.
SetTextInput
Adds a text box to the app task UI that lets the user provide text input.
void SetTextInput(String placeholderText, String actionUriTemplate);
Parameters
placeholderText String
The placeholder text shown in the text box.
actionUriTemplate String
An app-defined deep link URI with a placeholder that is replaced by the user's input.
SetQuestion
Adds text to the app task UI that lets you ask the user a question.
void SetQuestion(String question);
Parameters
question String
The question that requires a user's response.
AppTaskInfo class
Represents an app task shown in the Taskbar.
Remarks
This class represents a task. It supports creating, updating, and deleting. For each task a new AppTaskInfo is created and modified to represent the task state. When the app decides that the task is no longer relevant to surface to the user, for example, the user removes the task within the app, it calls the Remove method. The Taskbar also provides a way to remove tasks. FindAll returns all tasks that the app has created that have not been removed by the user or the app.
Properties
Title
Gets the title of the task that's displayed in the UI.
String Title { get; };
Property value
The title of the task that's displayed in the UI.
Subtitle
Gets the subtitle of the task.
String Subtitle { get; };
Property value
The subtitle of the task.
DeepLink
Gets a URI that will be launched when the user clicks on the task's Shell representation.
Uri DeepLink { get; };
Property value
A URI that will be launched when the user clicks on the task's Shell representation.
IconUri
Gets the path to an icon that indicates the type of task that is running, which can be an MRT resource or an absolute path.
Uri IconUri { get; };
Property value
Path to an icon that indicates the type of task that is running.
State
Gets the current state of the task.
AppTaskState State { get; };
Property value
AppTaskState
A value of the enumeration that indicates the current state of the task.
StartTime
Gets the time when task was created.
DateTime StartTime { get; };
Property value
The time when task was created.
EndTime
Gets the time when task reached an ending state (Completed or Error).
Windows.Foundation.IReference<Windows.Foundation.DateTime> EndTime { get; };
Property value
The time when the task reached an ending state (Completed or Error).
Methods
IsSupported
Indicates whether app tasks are supported.
static Boolean IsSupported();
Returns
Boolean
true if app tasks are supported; otherwise, false.
FindAll
Retrieves all tasks that the app has created that have not been removed by the user or the app.
static AppTaskInfo[] FindAll();
Returns
AppTaskInfo[]
An array of all tasks that the app has created that have not been removed by the user or the app.
Create
Creates a new instance of AppTaskInfo with the values specified by the parameters.
static AppTaskInfo Create(
String title,
String subtitle,
Windows.Foundation.Uri deepLink,
Windows.Foundation.Uri iconUri,
AppTaskContent content);
Parameters
title String
The title of the app task.
subtitle String
The subtitle of the app task.
deepLink Uri
A URI that allows navigation to the full task view in the app or allows the app to silently handle user input from interaction with hover cards.
iconUri Uri
The path to an icon that represents the app task.
content AppTaskContent
The content of the app task.
Returns
AppTaskInfo
A new instance of AppTaskInfo with the values specified by the parameters.
Remove
Removes the task from the taskbar, but doesn't change it's state.
void Remove();
Update
Updates the state and content of the app task.
void Update(AppTaskState state, AppTaskContent content);
Parameters
state AppTaskState
A value of the enumeration that indicates the state of the app.
content AppTaskContent
The content of the app task.
UpdateState
Updates the state of the app task.
void UpdateState(AppTaskState state);
Parameters
state AppTaskState
A value of the enumeration that indicates the state of the app.
UpdateTitles
Updates the title and subtitle of the app task.
void UpdateTitles(String title, String subtitle);
Parameters
title String
The new title of the app task.
subtitle String
The new subtitle of the app task.
GetCompletedSteps
Retrieves the details of the sequence of steps.
String[] GetCompletedSteps();
Returns
The sequence of completed steps.
GetExecutingStep
Retrieves the details of the current step.
String GetExecutingStep();
Returns
Details of the current step.
Using shell tasks APIs
Apps that use these APIs needs to be published. You also need to add the com.microsoft.apptaskprovider AppExtension to your app manifest like this:
<Package
xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
IgnorableNamespaces="rescap uap uap3">
...
<uap3:Extension Category="windows.appExtension">
<uap3:AppExtension
Name="com.microsoft.apptaskprovider"
PublicFolder="Public"
Id="MyApp.AppTaskProvider"
DisplayName="AppTaskProvider for MyApp"/>
</uap3:Extension>
...
</Package>
Windows.UI.Shell.Tasks.idl
// Copyright (c) Microsoft Corporation. All rights reserved.
namespace Windows.UI.Shell.Tasks
{
[contractversion(1)] apicontract AppTaskContract {}
[contract(AppTaskContract, 1)]
[experimental]
enum AppTaskState
{
Running, // Task is created and running, we don't have a seperate Created state
Completed, // Task completed
NeedsAttention, // Task is paused and needs user attention to continue
Paused, // Task is paused, but can be resumed without user intervention
Error, // Task stopped permanently because of an unrecoverable error
};
[contract(AppTaskContract, 1)]
[default_interface]
[experimental]
runtimeclass AppTaskResultAsset
{
AppTaskResultAsset(String name, String context, Windows.Foundation.Uri iconUri, Windows.Foundation.Uri assetUri);
}
[contract(AppTaskContract, 1)]
[experimental]
runtimeclass AppTaskContent
{
static AppTaskContent CreateSequenceOfSteps(String[] completedSteps, String executingStep);
static AppTaskContent CreatePreviewThumbnail(Windows.Foundation.Uri imageUri, String executingStep);
static AppTaskContent CreateTextSummaryResult(String text);
static AppTaskContent CreateGeneratedAssetsResult(AppTaskResultAsset[] assets);
static UInt32 MaxButtons{ get; };
void AddButton(String text, Windows.Foundation.Uri actionUri);
void SetTextInput(String placeholderText, String actionUriTemplate);
void SetQuestion(String question);
}
[contract(AppTaskContract, 1)]
[experimental]
runtimeclass AppTaskInfo
{
static Boolean IsSupported();
// Returns all AppTaskInfo objects for the current application
static AppTaskInfo[] FindAll();
static AppTaskInfo Create(
String title,
String subtitle,
Windows.Foundation.Uri deepLink,
Windows.Foundation.Uri iconUri,
AppTaskContent content);
void Remove();
void Update(AppTaskState state, AppTaskContent content);
void UpdateState(AppTaskState state);
void UpdateTitles(String title, String subtitle);
// Retrieve the sequence of steps details
String[] GetCompletedSteps();
String GetExecutingStep();
String Title { get; };
String Subtitle { get; };
// A URI that will be launched when the user clicks on the task’s Shell representation
Windows.Foundation.Uri DeepLink { get; };
// Path to an icon that will be displayed to the user, can be an MRT resource or an absolute path
Windows.Foundation.Uri IconUri { get; };
// Current state
AppTaskState State { get; };
// Time when task was created
Windows.Foundation.DateTime StartTime { get; };
// Time when task reached ending states (Completed, Error)
Windows.Foundation.IReference<Windows.Foundation.DateTime> EndTime { get; };
}
} // namespace Windows.UI.Shell.Tasks
Windows requirements
| Device family | Windows 11, version 25H2 |
Collaborate with us on GitHub
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
Windows developer