API Spec for Reunion Deployment Information API #156

dkbennett · 2020-08-27T18:48:30Z

First cut at proposed API spec for feature proposal: #155

Feedback appreciated, thank you!

specs/projectreuniondeployment/reuniondeployment.md

specs/projectreuniondeployment/projectreuniondeployment.md

DrusTheAxe · 2020-08-31T23:28:57Z

specs/projectreuniondeployment/projectreuniondeployment.md

+        static ProjectReunionDeploymentStatus GetStatus(Windows.ApplicationModel.PackageVersion packageVersion);
+
+        /// Returns a URI for the direct install link for the latest Project Reunion Package.
+        static Windows.Foundation.Uri GetProjectReunionPackageLink();


Are Main+Framework package versions in lockstep? If not then this should be GetPackageLinks() returning 1+ links? 0+ links?

Assuming for now that they are kept updated in lock-step. Regardless, the InstallPackage link is a .appinstaller file. So perhaps this should actually be "AppInstallerLink" ? Or just "InstallLink" to fit with naming scheme?

If it's a URI to *.appinstaller then yes, it should be AppInstallerLink or AppIntallerUri

Or maybe AppInstallerInfo a la W.AM.Package.GetAppInstallerInfo?

specs/projectreuniondeployment/projectreuniondeployment.md

stevenbrix · 2020-09-18T23:16:53Z

specs/projectreuniondeployment/projectreuniondeployment.md

+
+This is the spec for proposal [Project Reunion Deployment Information API #155](https://github.com/microsoft/ProjectReunion/issues/https://github.com/microsoft/ProjectReunion/issues/155).
+
+Project Reunion's deployment consists of a Main package and Framework package published by


It would be worth describing what a "Main package" and "Framework Package" is for folks who aren't familiar with the terms. I don't even know what a Main package is 😊

stevenbrix · 2020-09-18T23:21:30Z

specs/projectreuniondeployment/projectreuniondeployment.md

+
+# Description
+
+When a Project Reunion-consuming package or app is deployed, it is expected to only have the App


is this a packaged or unpackaged app, or both?

stevenbrix · 2020-09-18T23:25:24Z

specs/projectreuniondeployment/projectreuniondeployment.md

+The API addresses #1 by a simple query of the version they seek and a possible check for OS
+updates. #2 has two possible answers. First is direct resolution by the developer by acquiring and
+installing the packages if possible. Some programs will not have permission or motivation to do
+this, so the second answer is providing a link up to the user where the user can take action to


By "user" are you referring to someone using Windows, or a developer? Popping up install messages to the user sounds icky. When and why would this happen?

stevenbrix · 2020-09-18T23:26:23Z

specs/projectreuniondeployment/projectreuniondeployment.md

+
+Provides a direct install link to deploy the latest version of Project Reunion. If no OS Updates
+are required and the program or app has permissions to deploy packages, this can directly resolve
+the missing dependency without burdening the user.


side note: we should never burden the user

I agree, though this is a special circumstance due to permissions. The app may not have permissions to install OS updates or other things required by Project Reunion on a downlevel device. This should be an at most 1 time deal for the typical user, and only on downlevel OSes. For future OSes, this can be mitigated by preinstalling Project Reunion, where it will be auto-updated by the store and required OS updates are already present.

A core goal of Reunion is to help apps work even when running "downlevel" without necessarily updating the underlying OS. Nobody wants a "thanks for paying your money and installing, now take these QFEs" popup during first launch. Let's talk (internally) about how we want to approach this.

Ideally, certain Reunion features have a Something.IsSupported or similar where the component says "I'm not supported on this OS/environment" and if that needs to expand to return a "yes/no/MaybeWithOSUpdate" combination we can discuss.

specs/projectreuniondeployment/projectreuniondeployment.md

stevenbrix · 2020-09-18T23:31:51Z

specs/projectreuniondeployment/projectreuniondeployment.md

+        /// are required.
+        Boolean IsOK { get; };
+
+        // Returns True if Windows Updates are required for Project Reunion.


What does this mean to a developer? What do I do if a Windows Update is required?

Is that a typo? Should be "Windows updates"?

it should be Windows updates (I come from a world where Windows Update is a proper noun). Anyway, the meaning to a developer is for one who wishes to provide a better user experience. If Windows Updates are required, it is unlikely the developer will be able to resolve that, but if Package updates are required, it is possible the developer could trigger an update using the appinstaller link. It's a crawl -> walk -> run experience. The crawl is the install instructions link. The walk is the developer triggering package updates by themselves for a better user experience. The run is none of this is required at all because it's already handled by the OS (which won't be possible on most downlevel OSes).

stevenbrix · 2020-09-18T23:39:57Z

How are developers getting bits on their machine to debug and test apps?

dotMorten · 2020-09-19T03:01:40Z

specs/projectreuniondeployment/projectreuniondeployment.md

+```C++
+Windows::ApplicationModel::PackageVersion version{1, 0, 0, 0};
+auto status =
+Microsoft::Management::Deployment::ProjectReunionDeployment::GetStatus(version);


I assume the "ProjectReunionDeployment" class name is temporary working name, and "ProjectReunion" will be dropped from these APIs?
Second. Why are there APIs for this? Why can't the installer just take care of all of this? I don't want to have to write any of this code, but want the installer tooling to take care of all of this at startup, so we can get a consistent experience across all apps.

What installer? How does it "do this"?

An app could do none of this in main(), rely on its installer to DoTheRightThing(TM) and main() just assumes the system's 'environmental soup' is correct. In which case this sample is what the installer would do.

But...why do you assume there's an installer? 'XCOPY-install' apps don't have an installer. And some devs want their app to 'check their environmental soup' (up front or if/when things go wrong).

NSIS or ClickOnce could do this, if they so choose. But apps can too, and some very much want or need to.

Name is working and open to better suggestions. The reason this exists was defined at the top of the spec, but we may have OS updates required, we may have package updates required. We may not have the package at all. The developer needs to know and should be calling this API to check that all their expected Project Reunion dependencies are met and at a version minimum that they expect, otherwise their app will not function properly. So this API really answers two key questions for a developer:

Is Project Reunion the correct version and in a good state for what I need? They call GetStatus() for this and provide the minimum version of Reunion they tested against.

If the status object returned is !IsOK(), what do I do about it? The obvious answer is their program should probably terminate and not try to continue without the dependency being satisfied, but the real question is how do they satisfy the dependency? There are two sub-options here for developers to resolve the problem:

a) They get the install instructions link and shell execute it and inform the user that there is action they need to take. While not great, this should be a 1-time deal for most situations. Sort of like needing to update DirectX or any other redist, but OS updates may be required here.

b) If OS updates are not required, and the are either a non-packaged medium-IL program, or a packaged app with Package Management capability, they can attempt to resolve the problem directly by getting the package (really appinstaller) install link and triggering the package install/update directly themselves.

stevenbrix · 2020-09-22T19:50:12Z

Last I heard, we were following the WinUI2.x model for shipping, which means that pre-release packages will ship the assemblies app-local, is this still the plan?

stevenbrix · 2020-09-22T20:51:10Z

This spec seems fairly light on "how do I use this" - can we get some more examples please?

DrusTheAxe · 2020-09-22T21:22:49Z

Last I heard, we were following the WinUI2.x model for shipping, which means that pre-release packages will ship the assemblies app-local, is this still the plan?

That's under active discussion

There's a strong intent to ship(1) as MSIX Framework packages. Supporting (in the technical as well as policy/sanctioned/official-Support-channels sense) 'app-local' aka the 'redist' model in addition to Framework packages is begin debated. There's also discussions under way re versioning strategy, 'prerelease' and like topics. Important but complex topics so please be patient.

And if you have thoughts on the subject, please share your feedback. Input to this repository is monitored by many directly involved in these (and other) topics. The dialogue(s) here help us understand and shape our efforts.

(1) I assume you mean install/runtime, not dev/build-time. Nuget packages are the plan for the latter, at least for the initial release. Gotta start somewhere :-)

jonwis · 2020-09-28T16:27:56Z

specs/projectreuniondeployment/projectreuniondeployment.md

+missing dependencies.
+
+The developer scenarios for this API is to answer the questions:
+1. Does this system have the min version of Project Reunion I require?


Nit: Put a newline here, some markdown renderers get confused by number lists without a blank line before.

Tip if you use VSCode, install the markdownlist extension and run it occasionally. It flags this sort of thing

jonwis · 2020-09-28T16:30:43Z

specs/projectreuniondeployment/projectreuniondeployment.md

+```C++
+Windows::ApplicationModel::PackageVersion version{1, 0, 0, 0};
+auto status =
+Microsoft::Management::Deployment::ProjectReunionDeployment::GetStatus(version);


Could this be made generic first, like GetPackageStatus that takes a string, and then layer the Project Reunion part over that with a known constant like ProjectReunionRuntime.FrameworkPackageName and ProjectReunionRuntime.MainPackageName (or similar)? Then if we ever have Electron or Flutter or Node or WebView2 as framework packages this code can be reused by their client apps easily?

jonwis · 2020-09-28T16:33:32Z

specs/projectreuniondeployment/projectreuniondeployment.md

+
+Provides a direct install link to deploy the latest version of Project Reunion. If no OS Updates
+are required and the program or app has permissions to deploy packages, this can directly resolve
+the missing dependency without burdening the user.


A core goal of Reunion is to help apps work even when running "downlevel" without necessarily updating the underlying OS. Nobody wants a "thanks for paying your money and installing, now take these QFEs" popup during first launch. Let's talk (internally) about how we want to approach this.

Ideally, certain Reunion features have a Something.IsSupported or similar where the component says "I'm not supported on this OS/environment" and if that needs to expand to return a "yes/no/MaybeWithOSUpdate" combination we can discuss.

jonwis · 2020-09-28T16:34:50Z

specs/projectreuniondeployment/projectreuniondeployment.md

+the missing dependency without burdening the user.
+
+```C++
+Windows::Foundation::Uri packageLink = Microsoft::Management::Deployment::ProjectReunionDeployment::GetInstallPackageLink();


General, per above - I think we should split "the mechanics of doing these" away from "the Project Reunion specific instances of stuff." So this URI would not be in MMD.PRD as a namespace, it would be in Microsoft.ProjectReunion.Common.GetPackageInstallUri or similar.

jonwis · 2020-09-28T16:35:23Z

specs/projectreuniondeployment/projectreuniondeployment.md

+the missing dependency without burdening the user.
+
+```C++
+Windows::Foundation::Uri packageLink = Microsoft::Management::Deployment::ProjectReunionDeployment::GetInstallPackageLink();


Nit on naming: GetPackageSourceUri instead of GetInstallPackageLink

jonwis · 2020-09-28T17:06:47Z

specs/projectreuniondeployment/projectreuniondeployment.md

+    {
+        /// Returns True if Project Reunion is the desired Version and no updates or packages
+        /// are required.
+        Boolean IsOK { get; };


This is returned from something, so I presume the OK-ness was computed during that operation.

jonwis · 2020-09-28T17:07:19Z

specs/projectreuniondeployment/projectreuniondeployment.md

+        Boolean IsOK { get; };
+
+        // Returns True if Windows Updates are required for Project Reunion.
+        Boolean WindowsUpdatesRequired { get; };


IsWindowsUpdateRequired or RequiresWindowsUpdate maybe.

jonwis · 2020-09-28T17:08:12Z

specs/projectreuniondeployment/projectreuniondeployment.md

+        Boolean WindowsUpdatesRequired { get; };
+
+        // Returns True if a Package install is required for Project Reunion.
+        Boolean PackageInstallRequired { get; };


Should this be PackageMissing ?

Is the intent of the set of bools to be "here are multiple problems you need to resolve"?

jonwis · 2020-09-28T17:08:56Z

specs/projectreuniondeployment/projectreuniondeployment.md

+    }
+
+    /// Used to query deployment information for Project Reunion
+    static runtimeclass ProjectReunionDeployment


Consider moving this up into Microsoft.ProjectReunion as the type ProjectReunionPackage maybe?

Add reunion deployment API spec draft

f365b4c

ghost added the needs-triage label Aug 27, 2020

DrusTheAxe reviewed Aug 28, 2020

View reviewed changes

specs/projectreuniondeployment/reuniondeployment.md Outdated Show resolved Hide resolved

DrusTheAxe reviewed Aug 28, 2020

View reviewed changes

specs/projectreuniondeployment/reuniondeployment.md Outdated Show resolved Hide resolved

Fix spec formatting and rename

e88a5df

DrusTheAxe reviewed Aug 31, 2020

View reviewed changes

API Feedback update

5c834c8

mevey removed the needs-triage label Sep 14, 2020

stevenbrix reviewed Sep 18, 2020

View reviewed changes

dotMorten reviewed Sep 19, 2020

View reviewed changes

jonwis requested changes Sep 28, 2020

View reviewed changes

DrusTheAxe mentioned this pull request Sep 30, 2020

MSIX Dynamic Dependencies - allow any process to use MSIX Framework packages #89

Closed

EHO-makai closed this Nov 11, 2020

EHO-makai deleted the branch master November 11, 2020 21:14

bpulliam deleted the user/dkbennett/reuniondeploymentspec branch February 6, 2023 13:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API Spec for Reunion Deployment Information API #156

API Spec for Reunion Deployment Information API #156

dkbennett commented Aug 27, 2020

DrusTheAxe Aug 31, 2020

dkbennett Sep 9, 2020 •

edited

Loading

DrusTheAxe Sep 21, 2020

stevenbrix Sep 18, 2020

stevenbrix Sep 18, 2020

stevenbrix Sep 18, 2020

stevenbrix Sep 18, 2020

dkbennett Sep 23, 2020

jonwis Sep 28, 2020

stevenbrix Sep 18, 2020

DrusTheAxe Sep 22, 2020

dkbennett Sep 23, 2020

stevenbrix commented Sep 18, 2020

dotMorten Sep 19, 2020 •

edited

Loading

DrusTheAxe Sep 22, 2020 •

edited

Loading

dkbennett Sep 23, 2020 •

edited

Loading

stevenbrix commented Sep 22, 2020

stevenbrix commented Sep 22, 2020

DrusTheAxe commented Sep 22, 2020

jonwis Sep 28, 2020

DrusTheAxe Sep 28, 2020

jonwis Sep 28, 2020

jonwis Sep 28, 2020

jonwis Sep 28, 2020

jonwis Sep 28, 2020

jonwis Sep 28, 2020

jonwis Sep 28, 2020

jonwis Sep 28, 2020

jonwis Sep 28, 2020


		This is the spec for proposal [Project Reunion Deployment Information API #155](https://github.com/microsoft/ProjectReunion/issues/https://github.com/microsoft/ProjectReunion/issues/155).

		Project Reunion's deployment consists of a Main package and Framework package published by


		# Description

		When a Project Reunion-consuming package or app is deployed, it is expected to only have the App

API Spec for Reunion Deployment Information API #156

API Spec for Reunion Deployment Information API #156

Conversation

dkbennett commented Aug 27, 2020

Choose a reason for hiding this comment

dkbennett Sep 9, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stevenbrix commented Sep 18, 2020

dotMorten Sep 19, 2020 • edited Loading

Choose a reason for hiding this comment

DrusTheAxe Sep 22, 2020 • edited Loading

Choose a reason for hiding this comment

dkbennett Sep 23, 2020 • edited Loading

Choose a reason for hiding this comment

stevenbrix commented Sep 22, 2020

stevenbrix commented Sep 22, 2020

DrusTheAxe commented Sep 22, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dkbennett Sep 9, 2020 •

edited

Loading

dotMorten Sep 19, 2020 •

edited

Loading

DrusTheAxe Sep 22, 2020 •

edited

Loading

dkbennett Sep 23, 2020 •

edited

Loading