forked from MicrosoftDocs/windows-dev-docs
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge remote-tracking branch 'upstream/docs' into powertoys-0.39-updates
- Loading branch information
Showing
118 changed files
with
3,301 additions
and
586 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
318 changes: 318 additions & 0 deletions
318
hub/apps/project-reunion/applifecycle/applifecycle-instancing.md
Large diffs are not rendered by default.
Oops, something went wrong.
186 changes: 186 additions & 0 deletions
186
hub/apps/project-reunion/applifecycle/applifecycle-rich-activation.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,186 @@ | ||
| --- | ||
| description: How to use AppLifecycle's rich activation features in unpackaged apps (Project Reunion) | ||
| title: Rich activation for unpackaged apps in AppLifecycle (Project Reunion) | ||
| ms.topic: article | ||
| ms.date: 05/25/2021 | ||
| keywords: AppLifecycle, Windows, activation, activation contracts, rich activation, win32, win32 activation, unpackaged app, unpackaged app activation | ||
| ms.author: hickeys | ||
| author: hickeys | ||
| ms.localizationpriority: medium | ||
| --- | ||
|
|
||
| # Rich activation in AppLifecycle | ||
|
|
||
| > [!IMPORTANT] | ||
| > AppLifecycle is an experimental feature that is currently supported only in the [preview release channel](../preview-channel.md). This feature is not supported for use by apps in production environments. | ||
| In Project Reunion, AppLifecycle brings support for UWP-style rich activation behavior to all apps, packaged and unpackaged alike. This first release focuses on bringing the most commonly-used activation kinds to unpackaged apps, and future releases aim to support more of UWP's [44 activation kinds](/windows/uwp/api/Windows.ApplicationModel.Activation.ActivationKind). | ||
|
|
||
| Supporting rich activations requires two steps: | ||
|
|
||
| - Tell the system that your app supports one or more rich activation kinds. | ||
| - Receive and process the rich activation payloads your app receives when it is activated. | ||
|
|
||
| ## Activation details for unpackaged apps | ||
|
|
||
| This release of Project Reunion brings support for the four most common activation kinds to unpackaged apps.: | ||
|
|
||
| | Activation kind | Description | | ||
| | --------------- | ------------------------------------------------------------ | | ||
| | Launch | Activate the app from the command line, when the user double-clicks the app's icon, or programmatically via ShellExecute/CreateProcess. | | ||
| | File | Activate an app that has registered for a file type when a file of tht type is opened via ShellExecute, LaunchFileAsync, or the command line. | | ||
| | Protocol | Activate an app that has registered for a protocol when a string of that protocol is executed via ShellExecute, LaunchUriAsync, or the command-line. | | ||
| | StartupTask | Activate the app when the user logs into Windows, either because of a registry key, or because of a shortcut in a well-known startup folder. | | ||
|
|
||
| Each type of unpackaged app retrieves its command line arguments in different ways. For example, **Win32** apps expect to receive activation arguments to be passed into WinMain in the form of a string (though they also have the option to call [GetCommandLineW](/windows/win32/api/processenv/nf-processenv-getcommandlinew)). **Windows Forms** apps, however, *must* call [Environment.GetCommandLineArgs](/dotnet/api/system.environment.getcommandlineargs), as arguments will not be automatically passed to them. | ||
|
|
||
| ## Activation details for packaged apps | ||
|
|
||
| Packaged Project Reunion apps support all 44 of UWP's [activation kinds](/uwp/api/Windows.ApplicationModel.Activation.ActivationKind). Each activation kind has its own corresponding implementation of [IActivatedEventArgs](/uwp/api/windows.applicationmodel.activation.iactivatedeventargs) which contain properties relevant to that specific kind of activation. | ||
|
|
||
| Packaged apps will always receive activation event arguments in their `Activation` event handler, and also have the option of calling `AppInstance.GetActivatedEventArgs`. | ||
|
|
||
| ### Activation registration | ||
|
|
||
| All apps support the Launch activation kind by default. Unlike UWP, the Project Reunion Launch activation kind includes command line launches. Apps can register for additional activation kinds in several ways. | ||
|
|
||
| - All Project Reunion apps can register (and unregister) for additional activation kinds via APIs in the Project Reunion version of AppLifecycle. | ||
| - Unpackaged apps can continue to register for additional activation kinds using the traditional method of writing registry keys. | ||
| - Packaged apps can register for additional activation kinds via entries in their application manifest. | ||
|
|
||
| Activation registrations are per-user. If your app is installed for multiple users, you will need to re-register activations for each user. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Register for rich activation | ||
|
|
||
| Though apps can call the registration APIs at any time, the most common scenario is checking registrations on app startup. | ||
|
|
||
| This example shows how an unpackaged app can use the registration APIs to register for several activation kinds when the app is launched. | ||
|
|
||
| > [!NOTE] | ||
| > This example registers associations with three image file types at once. This is convenient, but the outcome is the same as registering each file type individually; registering new image types does not overwrite previous registrations. However, if an app re-registers an already registered file type with a different set of verbs, the previous set of verbs will be overwritten for that file type. | ||
| ```c++ | ||
| int APIENTRY wWinMain( | ||
| _In_ HINSTANCE hInstance, | ||
| _In_opt_ HINSTANCE, | ||
| _In_ LPWSTR, | ||
| _In_ int nCmdShow) | ||
| { | ||
| // Initialize COM. | ||
| winrt::init_apartment(); | ||
|
|
||
| // Registering for rich activation kinds can be done in the | ||
| // app's installer or in the app itself. | ||
| RegisterForActivation(); | ||
|
|
||
| // When the app starts, it can get its activated eventargs, and perform | ||
| // any required operations based on the activation kind and payload. | ||
| RespondToActivation(); | ||
|
|
||
| /////////////////////////////////////////////////////////////////////////// | ||
| // Standard Win32 window configuration/creation and message pump: | ||
| // ie, whatever the app would normally do - nothing new here. | ||
| RegisterClassAndStartMessagePump(hInstance, nCmdShow); | ||
| return 1; | ||
| } | ||
|
|
||
| void RegisterForActivation() | ||
| { | ||
| // Register one or more supported image filetypes, | ||
| // an icon (specified by binary file path plus resource index), | ||
| // a display name to use in Shell and Settings, | ||
| // zero or more verbs for the File Explorer context menu, | ||
| // and the path to the EXE to register for activation. | ||
| // Note that localizable resource strings are not supported in v1. | ||
| std::wstring imageFileTypes[3] = { L".jpg", L".png", L".bmp" }; | ||
| std::wstring verbs[2] = { L"view", L"edit" }; | ||
| ActivationRegistrationManager::RegisterForFileTypeActivation( | ||
| imageFileTypes, | ||
| L"C:\\Program Files\\Contoso\\MyResources.dll, -123", | ||
| L"Contoso File Types", | ||
| verbs, | ||
| L"C:\\Program Files\\Contoso\\MyApp.exe"); | ||
|
|
||
| // Register some URI schemes for protocol activation, | ||
| // specifying the scheme name, icon, display name and EXE path. | ||
| ActivationRegistrationManager::RegisterForProtocolActivation( | ||
| L"foo", | ||
| L"C:\\Program Files\\Contoso\\MyResources.dll, -45", | ||
| L"Contoso Foo Protocol", | ||
| L"C:\\Program Files\\Contoso\\MyApp.exe"); | ||
|
|
||
| // Register for startup activation. | ||
| ActivationRegistrationManager::RegisterForStartupActivation( | ||
| L"MyTaskId", | ||
| L"C:\\Program Files\\Contoso\\MyApp.exe"); | ||
|
|
||
| ActivationRegistrationManager::RegisterForStartupActivation( | ||
| L"AnotherTaskId", | ||
| L""); | ||
| } | ||
| ``` | ||
| ### Get rich activation event arguments | ||
| Once activated, an app must retrieve its activation event arguments. In this example, an unpackaged app calls an AppLifecycle API to get the event args for the activation event. | ||
| > [!NOTE] | ||
| > Win32 apps typically get command-line arguments very early their WinMain method. Similarly, these apps should `AppInstance::GetActivatedEventArgs` in the same place where they previously would have used the supplied lpCmdLine parameter or GetCommandLineW. | ||
| ```c++ | ||
| void RespondToActivation() | ||
| { | ||
| AppActivationArguments args = AppInstance::GetCurrent().GetActivatedEventArgs(); | ||
| ExtendedActivationKind kind = args.Kind(); | ||
| if (kind == ExtendedActivationKind::Launch) | ||
| { | ||
| auto launchArgs = args.Data().as<LaunchActivatedEventArgs>(); | ||
| DoSomethingWithLaunchArgs(launchArgs.Arguments()); | ||
| } | ||
| else if (kind == ExtendedActivationKind::File) | ||
| { | ||
| auto fileArgs = args.Data().as<FileActivatedEventArgs>(); | ||
| DoSomethingWithFileArgs(fileArgs.Files()); | ||
| } | ||
| else if (kind == ExtendedActivationKind::Protocol) | ||
| { | ||
| auto protocolArgs = args.Data().as<ProtocolActivatedEventArgs>(); | ||
| DoSomethingWithProtocolArgs(protocolArgs.Uri()); | ||
| } | ||
| else if (kind == ExtendedActivationKind::StartupTask) | ||
| { | ||
| auto startupArgs = args.Data().as<StartupTaskActivatedEventArgs>(); | ||
| DoSomethingWithStartupArgs(startupArgs.TaskId()); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Unregister | ||
|
|
||
| This example demonstrates how an unpackaged app can unregister for specific activation kinds dynamically, using the AppLifecycle APIs. | ||
|
|
||
| > [!NOTE] | ||
| > When unregistering for startup activation, the app must use the same taskId that it used when it originally registered. | ||
| ```c++ | ||
| void UnregisterForActivation() | ||
| { | ||
| // Unregister one or more registered filetypes. | ||
| std::wstring imageFileTypes[3] = { L".jpg", L".png", L".bmp" }; | ||
| ActivationRegistrationManager::UnregisterForFileTypeActivation( | ||
| imageFileTypes, | ||
| L"C:\\Program Files\\Contoso\\MyApp.exe"); | ||
|
|
||
| // Unregister a protocol scheme. | ||
| ActivationRegistrationManager::UnregisterForProtocolActivation( | ||
| L"foo", | ||
| L""); | ||
|
|
||
| // Unregister for startup activation. | ||
| ActivationRegistrationManager::UnregisterForStartupActivation( | ||
| L"AnotherTaskId", | ||
| L""); | ||
| } | ||
| ``` |
126 changes: 126 additions & 0 deletions
126
hub/apps/project-reunion/check-project-reunion-versions.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,126 @@ | ||
| --- | ||
| title: Check for installed versions of the Project Reunion runtime | ||
| description: This article provides instructions for verifying the version of the Project Reunion runtime installed on your development computer. | ||
| ms.topic: article | ||
| ms.date: 05/21/2021 | ||
| keywords: windows win32, windows app development, project reunion | ||
| ms.author: zafaraj | ||
| author: zaryaf | ||
| ms.localizationpriority: medium | ||
| --- | ||
|
|
||
| # Check for installed versions of the Project Reunion runtime | ||
|
|
||
| To check which versions of the Project runtime are installed on your development computer, open a **PowerShell** window and run this command. | ||
|
|
||
| ```Powershell | ||
| get-appxpackage *reunion* | ||
| ``` | ||
|
|
||
| You should see output similar to the following, which includes the `x64` and `x86` architecture of the [Framework package](deployment-architecture.md#framework-packages-for-packaged-and-unpackaged-apps) and a single [Main package](deployment-architecture.md#main-package) and [Dynamic Dependency Lifetime Manager (DDLM) package](deployment-architecture.md#dynamic-dependency-lifetime-manager-ddlm), depending on your computer. | ||
|
|
||
| ```console | ||
| Name : Microsoft.ProjectReunion.0.8-preview | ||
| Publisher : CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US | ||
| Architecture : X86 | ||
| ResourceId : | ||
| Version : 8000.144.525.0 | ||
| PackageFullName : Microsoft.ProjectReunion.0.8-preview_8000.144.525.0_x86__8wekyb3d8bbwe | ||
| InstallLocation : C:\Program Files\WindowsApps\Microsoft.ProjectReunion.0.8-preview_8000.144.525.0_x86__8wekyb3d8bbwe | ||
| IsFramework : True | ||
| PackageFamilyName : Microsoft.ProjectReunion.0.8-preview_8wekyb3d8bbwe | ||
| PublisherId : 8wekyb3d8bbwe | ||
| IsResourcePackage : False | ||
| IsBundle : False | ||
| IsDevelopmentMode : False | ||
| NonRemovable : False | ||
| IsPartiallyStaged : False | ||
| SignatureKind : Store | ||
| Status : Ok | ||
|
|
||
| Name : Microsoft.ProjectReunion.0.8-preview | ||
| Publisher : CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US | ||
| Architecture : X64 | ||
| ResourceId : | ||
| Version : 8000.144.525.0 | ||
| PackageFullName : Microsoft.ProjectReunion.0.8-preview_8000.144.525.0_x64__8wekyb3d8bbwe | ||
| InstallLocation : C:\Program Files\WindowsApps\Microsoft.ProjectReunion.0.8-preview_8000.144.525.0_x64__8wekyb3d8bbwe | ||
| IsFramework : True | ||
| PackageFamilyName : Microsoft.ProjectReunion.0.8-preview_8wekyb3d8bbwe | ||
| PublisherId : 8wekyb3d8bbwe | ||
| IsResourcePackage : False | ||
| IsBundle : False | ||
| IsDevelopmentMode : False | ||
| NonRemovable : False | ||
| IsPartiallyStaged : False | ||
| SignatureKind : Store | ||
| Status : Ok | ||
|
|
||
| Name : Microsoft.ProjectReunion.Main.0.8-preview | ||
| Publisher : CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US | ||
| Architecture : X64 | ||
| ResourceId : | ||
| Version : 8000.144.525.0 | ||
| PackageFullName : Microsoft.ProjectReunion.Main.0.8-preview_8000.144.525.0_x64__8wekyb3d8bbwe | ||
| InstallLocation : C:\Program | ||
| Files\WindowsApps\Microsoft.ProjectReunion.Main.0.8-preview_8000.144.525.0_x64__8wekyb3d8bbwe | ||
| IsFramework : False | ||
| PackageFamilyName : Microsoft.ProjectReunion.Main.0.8-preview_8wekyb3d8bbwe | ||
| PublisherId : 8wekyb3d8bbwe | ||
| IsResourcePackage : False | ||
| IsBundle : False | ||
| IsDevelopmentMode : False | ||
| NonRemovable : False | ||
| Dependencies : {Microsoft.ProjectReunion.0.8-preview_8000.144.525.0_x64__8wekyb3d8bbwe} | ||
| IsPartiallyStaged : False | ||
| SignatureKind : Developer | ||
| Status : Ok | ||
|
|
||
| Name : Microsoft.ProjectReunion.DDLM.8000.144.525.0-x8-p | ||
| Publisher : CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US | ||
| Architecture : X86 | ||
| ResourceId : | ||
| Version : 8000.144.525.0 | ||
| PackageFullName : Microsoft.ProjectReunion.DDLM.8000.144.525.0-x8-p_8000.144.525.0_x86__8wekyb3d8bbwe | ||
| InstallLocation : C:\Program Files\WindowsApps\Microsoft.ProjectReunion.DDLM.8000.144.525.0-x8-p_8000.144.525.0_x86__ | ||
| 8wekyb3d8bbwe | ||
| IsFramework : False | ||
| PackageFamilyName : Microsoft.ProjectReunion.DDLM.8000.144.525.0-x8-p_8wekyb3d8bbwe | ||
| PublisherId : 8wekyb3d8bbwe | ||
| IsResourcePackage : False | ||
| IsBundle : False | ||
| IsDevelopmentMode : False | ||
| NonRemovable : False | ||
| Dependencies : {Microsoft.ProjectReunion.0.8-preview_8000.144.525.0_x86__8wekyb3d8bbwe} | ||
| IsPartiallyStaged : False | ||
| SignatureKind : Developer | ||
| Status : Ok | ||
|
|
||
| Name : Microsoft.ProjectReunion.DDLM.8000.144.525.0-x6-p | ||
| Publisher : CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US | ||
| Architecture : X64 | ||
| ResourceId : | ||
| Version : 8000.144.525.0 | ||
| PackageFullName : Microsoft.ProjectReunion.DDLM.8000.144.525.0-x6-p_8000.144.525.0_x64__8wekyb3d8bbwe | ||
| InstallLocation : C:\Program Files\WindowsApps\Microsoft.ProjectReunion.DDLM.8000.144.525.0-x6-p_8000.144.525.0_x64__ | ||
| 8wekyb3d8bbwe | ||
| IsFramework : False | ||
| PackageFamilyName : Microsoft.ProjectReunion.DDLM.8000.144.525.0-x6-p_8wekyb3d8bbwe | ||
| PublisherId : 8wekyb3d8bbwe | ||
| IsResourcePackage : False | ||
| IsBundle : False | ||
| IsDevelopmentMode : False | ||
| NonRemovable : False | ||
| Dependencies : {Microsoft.ProjectReunion.0.8-preview_8000.144.525.0_x64__8wekyb3d8bbwe} | ||
| IsPartiallyStaged : False | ||
| SignatureKind : Developer | ||
| Status : Ok | ||
| ``` | ||
|
|
||
| ## Related topics | ||
|
|
||
| - [Deploy apps that use Project Reunion](deploy-apps-that-use-project-reunion.md) | ||
| - [Runtime architecture and deployment scenarios](deployment-architecture.md) | ||
| - [Remove outdated Project Reunion runtime versions from your development computer](remove-project-reunion-versions.md) | ||
| - [Set up your development environment](set-up-your-development-environment.md) | ||
| - [Get started developing apps with Project Reunion](get-started-with-project-reunion.md) |
Oops, something went wrong.