Added AppLifecycle Activation API spec. by andreww-msft · Pull Request #279 · microsoft/WindowsAppSDK

andreww-msft · 2020-11-06T21:53:36Z

No description provided.

aeloros · 2020-11-09T22:12:45Z

+{
+    // Get the AppLifecycle sub-object for activation registration.
+    ActivationRegistrationManager registrationManager = 
+        AppLifecycle::GetActivationRegistrationManager();


Do we have any state that requires an instance class, or would this make more sense as a static class with register methods on it?

I can imagine that at some point we might want a "get manager for sub application". Doing that is usually a breaking change unless it's already an instance, but in the spirit of Project Reunion, feel free to avoid complexity and make these static methods.

jonwis · 2020-11-10T05:37:38Z

@@ -0,0 +1,248 @@
+# AppLifecycle - Rich Activation
+
+Reunion introduces a new AppLifecycle component that provides a core set of functionality related to app activation and lifecycle. Much of this functionality is directly equivalent - or very similar - to existing functionality within the platform. However, there is value in abstracting this functionality so that all app types can use it, delivering it out-of-band from the OS, and making it available as open-source. The totality of AppLifecycle features in v1 is as follows (additional features may be added in later releases):


Same note on wrapping, please

Please clarify: you want hard returns at col 80?
BTW - I don't seen a option in Prettier or Markdown All In One to do word wrapping.

jonwis · 2020-11-10T05:39:54Z

+-	Which activation kinds will unpackaged apps be able to use?
+-	How does the app tell the system which activation kinds it wants to use?
+
+### Which activation kinds will unpackaged apps be able to use?


Nit on phrasing - consider just "Supported Activation kind for unpackaged apps"

jonwis · 2020-11-10T06:23:56Z

+
+UWP apps can only register for activation kinds via manifest declarations, and therefore this happens during app install. Conversely, traditional app types can write registry entries at any time.
+
+A key requirement is to enable unpackaged Win32 apps to use the set of rich activations using familiar designs, without any additional friction. Specifically, AppLifecycle will provide APIs which the app can call to register its interest in rich activations. The app is not required to have an MSIX manifest, nor an MSIX package. Using the API approach rather than the manifest approach has the added benefit that it also addresses a related customer request for dynamic activation registrations even for UWP apps.


It's a requirement on us, but what's this give to developers?

jonwis · 2020-11-10T06:25:36Z

+
+A key requirement is to enable unpackaged Win32 apps to use the set of rich activations using familiar designs, without any additional friction. Specifically, AppLifecycle will provide APIs which the app can call to register its interest in rich activations. The app is not required to have an MSIX manifest, nor an MSIX package. Using the API approach rather than the manifest approach has the added benefit that it also addresses a related customer request for dynamic activation registrations even for UWP apps.
+
+Ideally, if the app is installed per-machine then any activation registrations would also be per-machine; and if installed per-user then registrations would be per-user. The platform will not offer any additional API features for this - that is, the app doesn't get to choose whether its activation registrations are per-machine or per-user. Instead, the activations should be registered to match the way the app is installed. For v1, the platform will support only per-user registration.


This is a little confusing. Maybe lead off with "Currently all registered activation points are managed per-user. If your app is installed for multiple users via an MSI or elevated installer your app will need to re-register launch points for every user. Consider using {this sample technique} to ensure registrations only happen once per user."

jonwis · 2020-11-10T06:27:20Z

+{
+    // Get the AppLifecycle sub-object for activation registration.
+    ActivationRegistrationManager registrationManager = 
+        AppLifecycle::GetActivationRegistrationManager();


I can imagine that at some point we might want a "get manager for sub application". Doing that is usually a breaking change unless it's already an instance, but in the spirit of Project Reunion, feel free to avoid complexity and make these static methods.

jonwis · 2020-11-10T06:28:24Z

+            auto toastArgs = args.as<ToastNotificationActivatedEventArgs>();
+            DoSomethingWithToastArgs(toastArgs.Argument());
+        }
+    }


Maybe put a comment down here like "The app was launched for other reasons, or was not launched for one of our known types, so let the regular app launch behavior handle it."

The app can only be launched for the activation kinds it registers for (launch activation covers the case where it doesn't register for anything).

jonwis · 2020-11-10T06:29:26Z

+
+    // Unregister one or more registered filetypes.
+    registrationManager.UnregisterForFileTypeActivation(
+        new string[]{ ".jpg", ".png", ".bmp" });


C++ style would be to say { L".jpg", ...} - new string[] is a C#-ism :)

I'm pasting from my mocked C++ app, which builds ok...

ChrisGuzak · 2020-11-17T18:15:55Z

+- Calling a method to register activation.
+- Calling a method in their entrypoint to handle activation.
+
+From a Win32 app perspective, the 2 activation kinds that do not require any registration (Shortcut/Tile Launch and CommandLine) are effectively the same in terms of activation payload. Indeed, it is not possible to distinguish a launch activation of a Win32 app from a commandline activation. Therefore, the AppLifecycle implementation will merge Launch and CommandLine into one (Launch) activation kind. 


the shortcut file that launches the app can be retrieved and can be used to provide context for the launch. for example the console uses the shortcut to store configuration data, colors, window size, etc. given the property set stored in the shortcut this can be a general purpose configuration store.

consider providing access to the shortcut that launched the app, or its property store.

Is there an API for this already, or something we'd add as part of this effort? A little naive bing-ing doesn't lead me anywhere useful.

ChrisGuzak · 2020-11-17T18:16:31Z

+    // Register one or more supported image filetypes, an icon,
+    // and zero or more verbs for the File Explorer context menu.
+    ActivationRegistrationManager::RegisterForFileTypeActivation(
+        new string[]{ ".jpg", ".png", ".bmp" },


looks like C#.

Yes, but it's legal C++, right?

* Create .gitkeep * Create .gitkeep * Create .gitkeep * Create .gitkeep * Added AppLifecycle State/Power Notifications API spec. (#278) * Add files via upload Added AppLifecycle State/Power Notifications API spec. * Update AppLifecycle StateNotifications.md * Update AppLifecycle StateNotifications.md * Added AppLifecycle Activation API spec. (#279) * Add files via upload * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md (#401) * Update AppLifecycle Activation.md * Added AppLifecycle Single/Multi-instancing API spec. (#280) * Add files via upload * Update AppLifecycle SingleMulti-Instancing.md * Update AppLifecycle SingleMulti-Instancing.md Removed toast sample snippet. * Update AppLifecycle Activation.md (#434) * Update AppLifecycle Activation.md Added the exePath parameter to Register/Unregister methods. * Update AppLifecycle Activation.md Fixed the array declarations. * Update AppLifecycle Activation.md Changed RegisterForStartupActivation isEnabled to isDisabled. * Update AppLifecycle Activation.md Updated Startup registration to remove displayName, and add taskId to unregister. * Update AppLifecycle Activation.md Fixed array declarations again. * Update AppLifecycle Activation.md Removed isEnabled from StartupTask registration, as it makes no sense. * Update AppLifecycle Activation.md Fixed typo. * Update AppLifecycle Activation.md Dropped all the function overloads, added DisplayName to File & Protocol, added Logo to Protocol. * Update AppLifecycle SingleMulti-Instancing.md Removed toast sample snippet. * Update AppLifecycle Activation.md Renamed to AppInstance, and updated ExtendedActivationKind. * Update AppLifecycle SingleMulti-Instancing.md Renamed AppLifecycle to AppInstance, updated instancing APIs. * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md Made GetActivatedEventArgs an instance method instead of static. * Update AppLifecycle SingleMulti-Instancing.md Made GetActivatedEventArgs an instance method not static. * Update AppLifecycle Activation.md Added ProcessId. * Update AppLifecycle SingleMulti-Instancing.md Added ProcessId. * Update AppLifecycle Activation.md Added ProcessId example. * Tidy up app activation * Tidy up instancing * Tidy up power state * Update AppLifecycle Activation.md Resolved a number of review comments. * Update AppLifecycle SingleMulti-Instancing.md Fixed most review comments. * Update AppLifecycle SingleMulti-Instancing.md Additional review fixes. * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md * Update AppLifecycle SingleMulti-Instancing.md * Update AppLifecycle StateNotifications.md Updated per review comments. Co-authored-by: Jon Wiswall <jonwis@microsoft.com>

* Create .gitkeep * Create .gitkeep * Create .gitkeep * Create .gitkeep * Added AppLifecycle State/Power Notifications API spec. (microsoft#278) * Add files via upload Added AppLifecycle State/Power Notifications API spec. * Update AppLifecycle StateNotifications.md * Update AppLifecycle StateNotifications.md * Added AppLifecycle Activation API spec. (microsoft#279) * Add files via upload * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md (microsoft#401) * Update AppLifecycle Activation.md * Added AppLifecycle Single/Multi-instancing API spec. (microsoft#280) * Add files via upload * Update AppLifecycle SingleMulti-Instancing.md * Update AppLifecycle SingleMulti-Instancing.md Removed toast sample snippet. * Update AppLifecycle Activation.md (microsoft#434) * Update AppLifecycle Activation.md Added the exePath parameter to Register/Unregister methods. * Update AppLifecycle Activation.md Fixed the array declarations. * Update AppLifecycle Activation.md Changed RegisterForStartupActivation isEnabled to isDisabled. * Update AppLifecycle Activation.md Updated Startup registration to remove displayName, and add taskId to unregister. * Update AppLifecycle Activation.md Fixed array declarations again. * Update AppLifecycle Activation.md Removed isEnabled from StartupTask registration, as it makes no sense. * Update AppLifecycle Activation.md Fixed typo. * Update AppLifecycle Activation.md Dropped all the function overloads, added DisplayName to File & Protocol, added Logo to Protocol. * Update AppLifecycle SingleMulti-Instancing.md Removed toast sample snippet. * Update AppLifecycle Activation.md Renamed to AppInstance, and updated ExtendedActivationKind. * Update AppLifecycle SingleMulti-Instancing.md Renamed AppLifecycle to AppInstance, updated instancing APIs. * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md Made GetActivatedEventArgs an instance method instead of static. * Update AppLifecycle SingleMulti-Instancing.md Made GetActivatedEventArgs an instance method not static. * Update AppLifecycle Activation.md Added ProcessId. * Update AppLifecycle SingleMulti-Instancing.md Added ProcessId. * Update AppLifecycle Activation.md Added ProcessId example. * Tidy up app activation * Tidy up instancing * Tidy up power state * Update AppLifecycle Activation.md Resolved a number of review comments. * Update AppLifecycle SingleMulti-Instancing.md Fixed most review comments. * Update AppLifecycle SingleMulti-Instancing.md Additional review fixes. * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md * Update AppLifecycle SingleMulti-Instancing.md * Update AppLifecycle StateNotifications.md Updated per review comments. Co-authored-by: Jon Wiswall <jonwis@microsoft.com>

Add files via upload

dc3d394

ghost added the needs-triage label Nov 6, 2020

andreww-msft requested review from aeloros and jonwis November 8, 2020 00:10

aeloros reviewed Nov 9, 2020

View reviewed changes

jonwis requested changes Nov 10, 2020

View reviewed changes

andreww-msft requested a review from timkur November 11, 2020 20:37

andreww-msft added 2 commits November 16, 2020 14:06

Update AppLifecycle Activation.md

7cb34ad

Update AppLifecycle Activation.md

d42d77a

ChrisGuzak reviewed Nov 17, 2020

View reviewed changes

EHO-makai removed the needs-triage label Dec 2, 2020

andreww-msft added 2 commits January 28, 2021 12:25

Update AppLifecycle Activation.md (#401)

0f7b479

Update AppLifecycle Activation.md

973adfc

andreww-msft merged commit 52f97ef into user/andreww-msft Jan 29, 2021

andreww-msft deleted the andreww-msft-patch-2 branch January 29, 2021 21:17

		@@ -0,0 +1,248 @@
		# AppLifecycle - Rich Activation

		Reunion introduces a new AppLifecycle component that provides a core set of functionality related to app activation and lifecycle. Much of this functionality is directly equivalent - or very similar - to existing functionality within the platform. However, there is value in abstracting this functionality so that all app types can use it, delivering it out-of-band from the OS, and making it available as open-source. The totality of AppLifecycle features in v1 is as follows (additional features may be added in later releases):


		UWP apps can only register for activation kinds via manifest declarations, and therefore this happens during app install. Conversely, traditional app types can write registry entries at any time.

		A key requirement is to enable unpackaged Win32 apps to use the set of rich activations using familiar designs, without any additional friction. Specifically, AppLifecycle will provide APIs which the app can call to register its interest in rich activations. The app is not required to have an MSIX manifest, nor an MSIX package. Using the API approach rather than the manifest approach has the added benefit that it also addresses a related customer request for dynamic activation registrations even for UWP apps.


		A key requirement is to enable unpackaged Win32 apps to use the set of rich activations using familiar designs, without any additional friction. Specifically, AppLifecycle will provide APIs which the app can call to register its interest in rich activations. The app is not required to have an MSIX manifest, nor an MSIX package. Using the API approach rather than the manifest approach has the added benefit that it also addresses a related customer request for dynamic activation registrations even for UWP apps.

		Ideally, if the app is installed per-machine then any activation registrations would also be per-machine; and if installed per-user then registrations would be per-user. The platform will not offer any additional API features for this - that is, the app doesn't get to choose whether its activation registrations are per-machine or per-user. Instead, the activations should be registered to match the way the app is installed. For v1, the platform will support only per-user registration.

Conversation

andreww-msft commented Nov 6, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants