Skip to content

Commit 0065bb9

Browse files
drewbatgitdrewbatgit
committed
Initial draft of action framework docs for Build
1 parent 225a64c commit 0065bb9

File tree

3 files changed

+195
-0
lines changed

3 files changed

+195
-0
lines changed

‎hub/apps/develop/action-framework/action-json.md

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
title: Action JSON schema for Action Framework providers
3+
description: Describes the format of the action definition JSON file format for Action Framework.
4+
ms.topic: article
5+
ms.date: 02/04/2025
6+
ms.localizationpriority: medium
7+
---
8+
9+
10+
11+
# Action JSON schema for Action Framework providers
12+
13+
Describes the format of the action definition JSON file format for Action Framework.
14+
15+
## Example action definition JSON file
16+
17+
```json
18+
"version": 1,
19+
"actions": [
20+
{
21+
"id": "Contoso.SampleGreeting",
22+
"description": "A simple greeting action.",
23+
"icon": "ms-resource//...",
24+
"inputs": [
25+
{
26+
"name": "UserFriendlyName",
27+
"kind": "Text"
28+
},
29+
{
30+
"name": "PetName",
31+
"kind": "Text",
32+
"required": false
33+
}
34+
],
35+
"inputCombinations": [
36+
{
37+
"inputs": ["UserFriendlyName"],
38+
"description": "Greet ${UserFriendlyName.Text}"
39+
},
40+
{
41+
"inputs": ["UserFriendlyName", "PetName"],
42+
"description": "Greet ${UserFriendlyName.Text} and their pet ${PetName.Text}"
43+
}
44+
],
45+
"contentAgeRating": "child",
46+
"invocation":
47+
{
48+
{
49+
"type": "Uri",
50+
"uri": "contoso://greetUser? userName=${UserFriendlyName.Text}&petName=${PetName.Text}",
51+
},
52+
"where": [
53+
"${UserFriendlyName.Text.Length > 3}"
54+
]
55+
}
56+
},
57+
{
58+
"id": "Contoso.SampleGetText",
59+
"description": "Summarize a file",
60+
"icon": "ms-resource://...",
61+
"inputs": [
62+
{
63+
"name": "FileToSummarize",
64+
"kind": "File"
65+
}
66+
],
67+
"inputCombinations": [
68+
{
69+
"inputs": ["FileToSummarize"],
70+
"description": "Summarize ${FileToSummarize.Path}"
71+
},
72+
],
73+
"outputs": [
74+
{
75+
"name": "Summary",
76+
"kind": "Text"
77+
}
78+
],
79+
"contentAgeRating": "child",
80+
"invocation": {
81+
"type": "COM",
82+
"clsid": "{...}"
83+
}
84+
}
85+
]
86+
}
87+
```
88+
89+
## Action definition JSON properties
90+
91+
The tables below describe the properties of the action definition JSON file.
92+
93+
### Document root
94+
95+
| Property | Type | Description | Required |
96+
|----------|------|-------------|----------|
97+
| version | string | Schema version. When new functionality added, the version increments by one. | Yes. |
98+
| actions | Action[] | Defines the actions provided by the app. | Yes. |
99+
100+
### Action
101+
102+
| Property | Type | Description | Required |
103+
|----------|------|-------------|----------|
104+
| id | string | Action identifier. Must be unique per app package. This value is not localizable. | Yes |
105+
| description | string | User-facing description for this action. This value is localizable. | Yes |
106+
| icon | string | Localizable icon for the action. This value is an *ms-resource* string for an icon deployed with the app. | No |
107+
| inputs | Inputs[] | List of entities that this action accepts as input. | Yes |
108+
| inputCombinations | InputCombination[] | Provides descriptions for different combinations of inputs. | Yes |
109+
| outputs | Output[] | If specified, must be an empty string in the current release. | No |
110+
| invocation | Invocation | Provides information about how the action is invoked. | Yes |
111+
| contentAgeRating | string | A field name from the [UserAgeConsentGroup](/uwp/api/windows.system.userageconsentgroup)that specifies the appropriate age rating for the action. The allowed values are "Child", "Minor", "Adult". If no value is specified, the default behavior allows access to all ages. | No |
112+
113+
### Output
114+
115+
| Property | Type | Description | Required |
116+
|----------|------|-------------|----------|
117+
| name | string | The variable name of the entity. This value is not localizable. | Yes |
118+
| kind | string | A field name from the **ActionEntityKind** specifying the entity type. This value is not localizable. The allowed values are "None", "Document", "File", "Photo", "Text". | Yes |
119+
120+
### InputCombination
121+
122+
| Property | Type | Description | Required |
123+
|----------|------|-------------|----------|
124+
| inputs | string[] | A list of Input names for an action invocation. The list may be empty. | Yes |
125+
| description | string | Description for the action invocation. This value is localizable. | No |
126+
| where | string[] | One or more conditional statements determining the conditions under which the action applies. | No |
127+
128+
### Invocation
129+
130+
| Property | Type | Description | Required |
131+
|----------|------|-------------|----------|
132+
| type | string | The instantiation type for the action. The allowed values are "uri" and "com" | Yes |
133+
| uri | string | The absolute URI for launching the action. Entity usage can be included within the string. | Yes, for URI instantiated actions. |
134+
| clsid | string | The class ID for the COM class that implements **IActionProvider**. | Yes, for COM actions |
135+
| inputData | A list of name/value pairs specifying additional data for URI actions. | No. Only valid for URI actions. |
136+
137+
138+
## Related articles
139+
140+

‎hub/apps/develop/action-framework/action-provider-manifest.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: Action provider package manifest XML format
3+
description: Describes the package manifest XML format for action providers.
4+
ms.topic: article
5+
ms.date: 02/05/2024
6+
ms.localizationpriority: medium
7+
---
8+
9+
# Action provider package manifest XML format
10+
11+
This article describes the package manifest XML format for action providers.
12+
13+
## App extension
14+
15+
The app package manifest file supports many different extensions and features for Windows apps. The app package manifest format is defined by a set of schemas that are documented in the [Package manifest schema reference](/uwp/schemas/appxpackage/uapmanifestschema/schema-root). Action providers declare their registration information within the [uap3:AppExtension](/uwp/schemas/appxpackage/uapmanifestschema/element-uap3-appextension-manual). The **Name** attribute of the extension must be set to "com.microsoft.windows.ai.actions".
16+
17+
Action providers should include the [uap3:Properties](/uwp/schemas/appxpackage/uapmanifestschema/element-uap3-properties-manual) as the child of **uap3:AppExtension**. The package manifest schema does not enforce the structure of the **uap3:Properties** element other than requiring well-formed XML.
18+
19+
Action providers must provide a **Registration** element which specifies the path to the action definition JSON file. For more information, see [Action JSON schema for Action Framework providers](action-json.md).
20+
21+
```xml
22+
<uap3:Extension Category="windows.appExtension">
23+
<uap3:AppExtension
24+
Name="com.microsoft.windows.ai.actions"
25+
DisplayName="..."
26+
Id="..."
27+
PublicFolder="Assets">
28+
<uap3:Properties>
29+
<Registration>path\to\registration.json</Registration>
30+
</uap3:Properties>
31+
</uap3:AppExtension>
32+
</uap3:Extension>
33+
34+
```

‎hub/apps/develop/action-framework/index.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Action Framework providers
3+
description: Learn about Action Framework providers for Windows apps.
4+
ms.topic: article
5+
ms.date: 02/05/2025
6+
ms.localizationpriority: medium
7+
---
8+
9+
# Action Framework providers
10+
11+
TBD - Overview content
12+
13+
14+
15+
16+
17+
18+
## Related articles
19+
20+
[Action JSON schema for Action Framework providers](action-json.md)
21+

0 commit comments

Comments
 (0)