diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index 29aafc1d9b..1c633c1e22 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -61,7 +61,9 @@ } ], "notification_subscribers": [], - "sync_notification_subscribers": [], + "sync_notification_subscribers": [ + "quradic@microsoft.com" + ], "branches_to_filter": [], "git_repository_url_open_to_public_contributors": "https://github.com/MicrosoftDocs/windows-uwp", "git_repository_branch_open_to_public_contributors": "docs", @@ -111,4 +113,4 @@ "name": "docfx_v3" }, "need_generate_pdf": false -} +} \ No newline at end of file diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index ea26f17dca..89257859bb 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -5020,6 +5020,11 @@ "redirect_url": "https://docs.microsoft.com/partner-center/vat-info", "redirect_document_id": false }, + { + "source_path": "hub/apps/whats-new/build2020-docs.md", + "redirect_url": "/windows/apps/whats-new/build2021-docs", + "redirect_document_id": false + }, { "source_path": "windows-apps-src/publish/manage-account-settings-and-profile.md", "redirect_url": "https://docs.microsoft.com/partner-center/partner-center-account-setup", diff --git a/hub/apps/desktop/visual-studio-templates.md b/hub/apps/desktop/visual-studio-templates.md index f269ccdc45..495720ab95 100644 --- a/hub/apps/desktop/visual-studio-templates.md +++ b/hub/apps/desktop/visual-studio-templates.md @@ -22,7 +22,7 @@ The [Windows UI Library (WinUI)](../winui/index.md) is the modern native user in WinUI 3 is available as part of [Project Reunion](../project-reunion/index.md). It includes a VSIX package for Visual Studio 2019 that provides project and item templates that help you get started building apps with a WinUI-based interface. -For instructions to install the Project Reunion VSIX package and the WinUI project templates, see [Set up your development environment](../project-reunion/get-started-with-project-reunion.md#set-up-your-development-environment). For more information about the available WinUI project and item templates, see [Create WinUI 3 projects](../winui/winui3/winui-project-templates-in-visual-studio.md). +For instructions to install the Project Reunion VSIX package and the WinUI project templates, see [Set up your development environment](../project-reunion/set-up-your-development-environment.md). For more information about the available WinUI project and item templates, see [Create WinUI 3 projects](../winui/winui3/winui-project-templates-in-visual-studio.md). ## UWP templates diff --git a/hub/apps/get-started/enable-your-device-for-development.md b/hub/apps/get-started/enable-your-device-for-development.md index 1471575fe7..841067e1f6 100644 --- a/hub/apps/get-started/enable-your-device-for-development.md +++ b/hub/apps/get-started/enable-your-device-for-development.md @@ -5,7 +5,7 @@ description: Learn how to enable your Windows 10 device for development and debu keywords: Get started Developer license Visual Studio, developer license enable device ms.date: 10/13/2020 ms.topic: article -ms.localizationpriority: medium +ms.localizationpriority: high --- # Enable your device for development @@ -51,4 +51,4 @@ For more information on these features, or if you encounter difficulties in the ## See Also * [Sign up for Windows account](sign-up.md) -* [Developer mode features and debugging](developer-mode-features-and-debugging.md). \ No newline at end of file +* [Developer mode features and debugging](developer-mode-features-and-debugging.md). diff --git a/hub/apps/images/build-banner.jpeg b/hub/apps/images/build-banner.jpeg index db9b528922..e1b314fcf8 100644 Binary files a/hub/apps/images/build-banner.jpeg and b/hub/apps/images/build-banner.jpeg differ diff --git a/hub/apps/project-reunion/applifecycle/applifecycle-instancing.md b/hub/apps/project-reunion/applifecycle/applifecycle-instancing.md new file mode 100644 index 0000000000..fefcb14e63 --- /dev/null +++ b/hub/apps/project-reunion/applifecycle/applifecycle-instancing.md @@ -0,0 +1,318 @@ +--- +description: Instancing models available in Windows.ApplicationModel and how to use them (Project Reunion) +title: App instancing in AppLifecycle (Project Reunion) +ms.topic: article +ms.date: 05/25/2021 +keywords: AppLifecycle, Windows, ApplicationModel, instancing, single instance, multi instance +ms.author: hickeys +author: hickeys +ms.localizationpriority: medium +--- + +# App instancing 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. + +An app's instancing model determines whether multiple instances of your app's process can run at the same time. + +### Single-instance apps + +Apps are single-instanced if there can be only one main process running at a time. Attempting to launch a second instance of a single-instanced app typically results in the first instance's main window being activated instead. Note that this only applies to the main process. Single-instanced apps can create multiple background processes and still be considered single instanced. + +UWP apps are single-instanced by default. but have the ability to become multi-instanced by deciding at launch-time whether to create an additional instance or activate an existing instance instead. + +The Windows 10 Mail app is a good example of a single instanced app. When you launch Mail for the first time, a new window will be created. If you attempt to launch Mail again, the existing Mail window will be activated instead. + +### Multi-instanced apps + +Apps are multi-instanced if the main process can be run multiple times simultaneously. Attempting to launch a second instance of a multi-instanced app creates a new process and main window. + +Traditionally, unpacked apps are multi-instanced by default, but can implement single-instancing when necessarily. Typically this is done using a single named mutex to indicate if an app is already running. + +Notepad is a good example of a multi instanced app. Each time you attempt to launch Notepad, a new instance of Notepad will be created regardless of how many instances are already running. + +## How Project Reunion instancing differs from UWP instancing + +Instancing behavior in Project Reunion is based on UWP's model, class, but with some key differences: + +### AppInstance class + +- **UWP**: The [AppInstance](/windows/uwp/api/windows.applicationmodel.appinstance) class is focused purely on instance redirection scenarios. +- **Project Reunion**: The `AppInstance` class supports instance redirection scenarios, and contains additional functionality to support new features in later releases. + +### List of Instances + +- **UWP**: [GetInstances](/windows/uwp/api/windows.applicationmodel.appinstance.getinstances) returns only the instances that the app explicitly registered for potential redirection. +- **Project Reunion**: `GetInstances` returns all running instances of the app, including the current instance. Separate lists are maintained for different versions of the same app, as well as instances of apps launched by different users. + +### Registering Keys + +Each instance of a multi-instanced app can register an arbitrary key via the `FindOrRegisterForKey` API. Keys have no inherent meaning; apps can use keys in whatever form or way they wish. + +An instance of an app can set its key at any time, but only one key is allowed for each instance; setting a new value overwrites the previous value. + +An instance of an app cannot set its key to the same value that another instance has already registered. Attempting to register an existing key will result in `FindOrRegisterForKey` returning the app instance that has already registered that key. + +- **UWP**: An instance must register a key in order to be included in the list returned from [GetInstances](/windows/uwp/api/windows.applicationmodel.appinstance.getinstances). +- **Project Reunion**: Registering a key is decoupled from the list of instances. An instance does not need to register a key in order to be included in the list. + +### Unregistering keys + +An instance of an app can unregister its key. + +- **UWP**: When an instance unregisters its key, it is no longer available for activation redirection and is not included in the list of instances returned from [GetInstances](/windows/uwp/api/windows.applicationmodel.appinstance.getinstances). +- **Project Reunion**: An instance that has unregistered its key is still available for activation redirection and is still included in the list of instances returned from `GetInstances`. + +### Instance Redirection Targets + +Multiple instances of an app can activate each other, a process called "activation redirection". For example, an app might implement single instancing by only initializing itself if no other instances of the app are found at startup, and instead redirect and exit if another instance exists. Multi-instanced apps can redirect activations when appropriate according to that app's business logic. When an activation is redirected to another instance, it uses that instance's `Activated` callback, the same callback that's used in all other activation scenarios. + +- **UWP**: Only instances that have registered a key can be a target for redirection. +- **Project Reunion**: Any instance can be a redirection target, whether or not it has a registered key. + +### Post-Redirection Behavior + +- **UWP**: Redirection is a terminal operation; the app is terminated after redirecting the activation, even if the redirect failed. + +- **Project Reunion**: In Project Reunion, redirection is not a terminal operation. This in part reflects the potential problems in arbitrarily terminating a Win32 app that may have already allocated some memory, but also allows support of more sophisticated redirection scenarios. Consider a multi-instanced app where an instance receives an activation request while performing a large amount of CPU-intensive work. That app can redirect the activation request to another instance and continue its processing. That scenario would not be possible if the app was terminated after redirection. + +An activation request can be redirected multiple times. Instance A could redirect to instance B, which could in turn redirect to instance C. Project Reunion apps taking advantage of this functionality must guard against circular redirection - if C redirects to A in the example above, there is a potential infinite activation loop. It is up to the app to determine how to handle circular redirection depending on what makes sense for the workflows that app supports. + +### Activation Events + +In order to handle reactivation, the app can register for an Activated event. + +- **UWP**: The event passes an [IActivatedEventArgs](/windows/uwp/api/windows.applicationmodel.activation.iactivatedeventargs) to the app. +- **Project Reunion**: The event passes a `Microsoft.Windows.AppLifecycle.AppActivationArguments` instance to the app, which contains one of the `-ActivatedEventArgs` instances. + +## Examples + +### Handling activations + +This example demonstrates how an app registers for and handles an `Activated` event. When it receives an `Activated` event, this app uses the event arguments to determine what sort of action caused the activation, and responds appropriately. + +```cpp +int APIENTRY wWinMain( + _In_ HINSTANCE hInstance, _In_opt_ HINSTANCE hPrevInstance, + _In_ LPWSTR lpCmdLine, _In_ int nCmdShow) +{ + // Initialize COM. + winrt::init_apartment(); + + // First, hook up the Activated event, to allow for this instance of the app + // getting reactivated as a result of multi-instance redirection. + Microsoft::ProjectReunion::AppInstance::GetCurrent().Activated([]( + AppActivationArguments const& args) + { OnActivated(args); }); + + //...etc - the rest of WinMain as normal. +} + +void OnActivated(AppActivationArguments const& args) +{ + ExtendedActivationKind kind = args.Kind; + if (kind == ExtendedActivationKind::Launch) + { + auto launchArgs = args.Data().as(); + DoSomethingWithLaunchArgs(launchArgs.Arguments()); + } + else if (kind == ExtendedActivationKind::File) + { + auto fileArgs = args.Data().as(); + DoSomethingWithFileArgs(fileArgs.Files()); + } + else if (kind == ExtendedActivationKind::Protocol) + { + auto protocolArgs = args.Data().as(); + DoSomethingWithProtocolArgs(protocolArgs.Uri()); + } + else if (kind == ExtendedActivationKind::StartupTask) + { + auto startupArgs = args.Data().as(); + DoSomethingWithStartupArgs(startupArgs.TaskId()); + } +} +``` + +### Redirection logic based on activation kind + +In this example, the app registers a handler for the `Activated` event, but then immediately checks for the activation event args in the `wWinMain` method instead of waiting for an `Activated` callback. This allows the app to implement a single-instance model for certain scenarios. + +For most types of activations, the app continues with its regular initialization process. However, if the activation was caused by an associated file type being opened, and if another instance of this app already has the file opened, the current instance will redirect the activation to the existing instance and exit. + +This app uses key registration to determine which files are open in which instances. When an instance opens a file, it registers a key that includes that filename. Other instances can then examine the registered keys and look for particular filenames, and register themselves as that file's instance if no other instance already has. + +Note that, though key registration itself is part of Project Reunion's AppLifecycle API, the contents of the key are specified only within the app itself. An app does not need to register a file name, or any other meaningful data. This app, however, has decided to track open files via keys based on its particular needs and supported workflows. + +```cpp +int APIENTRY wWinMain( + _In_ HINSTANCE hInstance, _In_opt_ HINSTANCE hPrevInstance, + _In_ LPWSTR lpCmdLine, _In_ int nCmdShow) +{ + // Initialize COM. + winrt::init_apartment(); + + // First, we'll get our rich activation event args. + AppActivationArguments activationArgs = + AppInstance::GetCurrent().GetActivatedEventArgs(); + + // An app might want to set itself up for possible redirection in + // the case where it opens files - for example, to prevent multiple + // instances from working on the same file. + ExtendedActivationKind kind = activationArgs.Kind; + if (kind == ExtendedActivationKind::File) + { + auto fileArgs = activationArgs.Data.as(); + IStorageItem file = fileArgs.Files().GetAt(0); + + // Let's try to register this instance for this file. + AppInstance instance = + AppInstance::FindOrRegisterForKey(file.Name()); + if (instance.IsCurrent) + { + // If we successfully registered this instance, we can now just + // go ahead and do normal initialization. + RegisterClassAndStartMessagePump(hInstance, nCmdShow); + } + else + { + // Some other instance has already registered for this file, + // so we'll redirect this activation to that instance instead. + // This is an async operation: to ensure the target can get + // the payload before this instance terminates, we should + // wait for the call to complete. + instance.RedirectActivationToAsync(activationArgs).get(); + } + } + return 1; +} +``` + +### Arbitrary redirection + +This example expands on the previous example by adding more sophisticated redirection rules. The app still performs the open file check from the previous example. However, where the previous example would always create a new instance if it did not redirect based on the open file check, this example adds the concept of a "reusable" instance. If a reusable instance is found, the current instance redirects to the reusable instance and exits. Otherwise, it registers itself as reusable and continues with its normal initialization. + +Again, note that the concept of a "reusable" instance does not exist in the AppLifecycle API; it is created and used only within the app itself. + +```cpp +int APIENTRY wWinMain( + _In_ HINSTANCE hInstance, _In_opt_ HINSTANCE hPrevInstance, + _In_ LPWSTR lpCmdLine, _In_ int nCmdShow) +{ + // Initialize COM. + winrt::init_apartment(); + + AppActivationArguments activationArgs = + AppInstance::GetCurrent().GetActivatedEventArgs(); + + // As above, check for any specific activation kind we care about. + ExtendedActivationKind kind = activationArgs.Kind; + if (kind == ExtendedActivationKind::File) + { + // etc... as in previous scenario. + } + else + { + // For other activation kinds, we'll trawl all instances to see if + // any are suitable for redirecting this request. First, get a list + // of all running instances of this app. + auto instances = AppInstance::GetInstances(); + + // In the simple case, we'll redirect to any other instance. + AppInstance instance = instances.GetAt(0); + + // If the app re-registers re-usable instances, we can filter for these instead. + // In this example, the app uses the string "REUSABLE" to indicate to itself + // that it can redirect to a particular instance. + bool isFound = false; + for (AppInstance instance : instances) + { + if (instance.Key == L"REUSABLE") + { + isFound = true; + instance.RedirectActivationToAsync(activationArgs).get(); + break; + } + } + if (!isFound) + { + // We'll register this as a reusable instance, and then + // go ahead and do normal initialization. + winrt::hstring szKey = L"REUSABLE"; + AppInstance::FindOrRegisterForKey(szKey); + RegisterClassAndStartMessagePump(hInstance, nCmdShow); + } + } + return 1; +} +``` + +### Redirection orchestration + +This example again adds more sophisticated redirection behavior. Here, an app instance can register itself as the instance that handles all activations of a specific kind. When an instance of an app receives a `Protocol` activation, it first checks for an instance that has already registered to handle `Protocol` activations. If it finds one, it redirects the activation to that instance. If not, the current instance registers itself for `Protocol` activations, and then applies additional logic (not shown) which may redirect the activation for some other reason. + +```cpp +void OnActivated(AppActivationArguments const& args) +{ + const ExtendedActivationKind kind = args.Kind; + + // For example, we might want to redirect protocol activations. + if (kind == ExtendedActivationKind::Protocol) + { + auto protocolArgs = args.Data().as(); + Uri uri = protocolArgs.Uri(); + + // We'll try to find the instance that handles protocol activations. + // If there isn't one, then this instance will take over that duty. + auto instance = AppInstance::FindOrRegisterForKey(uri.AbsoluteUri()); + if (!instance.IsCurrent) + { + instance.RedirectActivationToAsync(args).get(); + } + else + { + DoSomethingWithProtocolArgs(uri); + } + } + else + { + // In this example, this instance of the app handles all other + // activation kinds. + DoSomethingWithNewActivationArgs(args); + } +} +``` + +Unlike the UWP version of RedirectActivationTo, Project Reunion's version requires explicitly passing event arguments when redirecting activations. This is necessary because whereas UWP tightly controls activations and can ensure the correct activation arguments are passed to the correct instances, Project Reunion's version supports many platforms, and cannot rely on UWP-specific features. One benefit of this model is that Project Reunion apps have the chance to modify or replace the arguments that will be passed to the target instance. + +### Unregister for redirection + +Apps that have registered a key can unregister that key at any time. This example assumes the current instance had previously registered a key indicating that it had a specific file opened, meaning subsequent attempts to open that file would be redirected to it. When that file is closed, the key that contains the filename must be deleted. + +```cpp +void CALLBACK OnFileClosed(HWND hDlg, UINT message, WPARAM wParam, LPARAM lParam) +{ + AppInstance::GetCurrent().UnregisterKey(); +} +``` + +> [!Warning] +> Although keys are automatically unregistered when their process terminates, race conditions are possible where another instance may have initiated a redirection to the terminated instance before the terminated instance was unregistered. To mitigate this possibility, an app can use `UnregisterKey` to manually unregister its key before it is terminated, giving the app a chance to redirect activations to another app that is not in the process of exiting. + +### Instance information + +The `AppInstance` class represents a single instance of an app. In this preview, `AppInstance` only includes the methods and properties necessary to support activation redirection. In later releases, `AppInstance` will expand to include other methods and properties relevant to an app instance. + +```cpp +void DumpExistingInstances() +{ + for (AppInstance const& instance : AppInstance::GetInstances()) + { + std::wostringstream sStream; + sStream << L"Instance: ProcessId = " << instance.ProcessId + << L", Key = " << instance.Key().c_str() << std::endl; + ::OutputDebugString(sStream.str().c_str()); + } +} +``` diff --git a/hub/apps/project-reunion/applifecycle/applifecycle-rich-activation.md b/hub/apps/project-reunion/applifecycle/applifecycle-rich-activation.md new file mode 100644 index 0000000000..e0f432d88d --- /dev/null +++ b/hub/apps/project-reunion/applifecycle/applifecycle-rich-activation.md @@ -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(); + DoSomethingWithLaunchArgs(launchArgs.Arguments()); + } + else if (kind == ExtendedActivationKind::File) + { + auto fileArgs = args.Data().as(); + DoSomethingWithFileArgs(fileArgs.Files()); + } + else if (kind == ExtendedActivationKind::Protocol) + { + auto protocolArgs = args.Data().as(); + DoSomethingWithProtocolArgs(protocolArgs.Uri()); + } + else if (kind == ExtendedActivationKind::StartupTask) + { + auto startupArgs = args.Data().as(); + 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""); +} +``` diff --git a/hub/apps/project-reunion/check-project-reunion-versions.md b/hub/apps/project-reunion/check-project-reunion-versions.md new file mode 100644 index 0000000000..b2608c12ce --- /dev/null +++ b/hub/apps/project-reunion/check-project-reunion-versions.md @@ -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) \ No newline at end of file diff --git a/hub/apps/project-reunion/deploy-apps-that-use-project-reunion.md b/hub/apps/project-reunion/deploy-apps-that-use-project-reunion.md index c8acc8beb4..f4a08ddd5d 100644 --- a/hub/apps/project-reunion/deploy-apps-that-use-project-reunion.md +++ b/hub/apps/project-reunion/deploy-apps-that-use-project-reunion.md @@ -2,63 +2,27 @@ title: Deploy apps that use Project Reunion description: This article provides instructions for deploying apps that use Project Reunion. ms.topic: article -ms.date: 03/19/2021 +ms.date: 05/21/2021 keywords: windows win32, windows app development, project reunion -ms.author: mcleans -author: mcleanbyron +ms.author: zafaraj +author: zaryaf ms.localizationpriority: medium --- -# Deploy apps that use Project Reunion +# Deploy apps that use Project Reunion -To deploy apps that use Project Reunion 0.5 to other computers, you must package the apps using [MSIX](/windows/msix). Project Reunion will support deploying unpackaged apps in a future release. For more information about our future plans, see our [roadmap](https://github.com/microsoft/ProjectReunion/blob/main/docs/roadmap.md). +Before configuring your apps for deployment, review [Project Reunion deployment architecture](deployment-architecture.md) to learn more about the dependencies your app takes when it uses Project Reunion. -By default, when you create a project using one of the [WinUI project templates](..\winui\winui3\winui-project-templates-in-visual-studio.md) that are provided with the Project Reunion extension for Visual Studio, your project includes a [Windows Application Packaging Project](/windows/msix/desktop/desktop-to-uwp-packaging-dot-net) that is configured to build the app into an MSIX package. For more information about configuring this project to build an MSIX package for your app, see [Package a desktop or UWP app in Visual Studio](/windows/msix/package/packaging-uwp-apps). +For instructions about deploying an app that uses Project Reunion, see these articles: -After you build an MSIX package for your app, you have several options for deploying it to other computers. For more information, see [Manage your MSIX deployment](/windows/msix/desktop/managing-your-msix-deployment-overview). - -> [!NOTE] -> Project Reunion 0.5 is supported for use in MSIX-packaged desktop apps (C# .NET 5 or C++ desktop) in production environments. Packaged desktop apps that use Project Reunion 0.5 can be published to the Microsoft Store. - -## Dependencies on the Project Reunion framework package - -When you build an app that uses Project Reunion, your app references a set of Project Reunion runtime components that are distributed to end users via a *framework package*. The framework package allows packaged apps to access Project Reunion components through a single shared source on the user's device, instead of bundling them into the app package. The framework package also carries its own resources, such as DLLs and API definitions (COM and Windows Runtime registrations). These resources run in the context of your app, so they inherit the capabilities and privileges of your app, and don't assert any capabilities or privileges of their own. - -The Project Reunion framework package is an MSIX package that is deployed to end users through the Microsoft Store. It can be easily and quickly updated with the latest releases, in addition to security and reliability fixes. All apps that use Project Reunion on a computer have a dependency on a shared instance of the framework package, as illustrated in the following diagram. - -![Diagram of how apps access the Project Reunion framework package](images/framework.png) - -The way that dependency is configured depends on whether you're using a prerelease or release version of Project Reunion in your app. Project Reunion will be available in prerelease and release versions, and these will include prerelease and release versions of the framework package. Apps must ensure they are referencing the correct package for the functionality they desire. - -## Configure dependencies on preview versions of the framework package - -Preview versions of Project Reunion are intended for investigation and feedback on new features. They are not licensed to be used in production environments and should not be published to the Microsoft Store. - -When you install a preview version of the Project Reunion extension for Visual Studio or the Project Reunion NuGet package on your development computer, the preview version of the framework package is deployed during build time as a NuGet package dependency. - -## Configure dependencies on release versions of the framework package - -Release versions of Project Reunion are supported for use in production environments. - -When you install a release version of the Project Reunion extension or the Project Reunion NuGet package on your development computer and you create a project using one of the provided WinUI 3 project templates, the generated package manifest contains a [PackageDependency](/uwp/schemas/appxpackage/uapmanifestschema/element-packagedependency) element that specifies a dependency on the framework package. - -```xml - - - -``` - -However, if you build your app package manually, you must add this **PackageDependency** element to your package manifest yourself to declare a dependency on the Project Reunion framework package. - -## Updates and versioning of the framework package - -When a new version of the Project Reunion framework package is released, all apps are updated to the new version without themselves having to redistribute a copy. Windows updates to the newest version of frameworks as they are released, and apps will automatically reference the latest framework package version during relaunch. Older framework package versions will not be removed from the system until they are no longer running or being actively used by apps on the system. - -![Diagram of how apps get updates to the Project Reunion framework package](images/framework-update.png) - -Because app compatibility is important to Microsoft and to apps that depend on Project Reunion, the Project Reunion framework package follows [Semantic Versioning 2.0.0](https://semver.org/) rules. This means that after we release version 1.0 of Project Reunion, the Project Reunion framework package will guarantee compatibility between minor and patch version changes, and breaking changes will occur only between major version updates. +- [Deploy MSIX-packaged apps that use Project Reunion](deploy-packaged-apps.md) +- [Deploy non-MSIX packaged apps that use Project Reunion](deploy-unpackaged-apps.md) (experimental feature) ## Related topics -- [Build desktop Windows apps with Project Reunion](index.md) -- [Get started with Project Reunion](get-started-with-project-reunion.md) +- [Tutorial: Build and deploy an unpackaged app that uses Project Reunion](tutorial-unpackaged-deployment.md) +- [Check for installed versions of the Project Reunion runtime](check-project-reunion-versions.md) +- [Remove outdated Project Reunion runtime versions from your development computer](remove-project-reunion-versions.md) +- [Release channels](release-channels.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) diff --git a/hub/apps/project-reunion/deploy-packaged-apps.md b/hub/apps/project-reunion/deploy-packaged-apps.md new file mode 100644 index 0000000000..ac41a8131a --- /dev/null +++ b/hub/apps/project-reunion/deploy-packaged-apps.md @@ -0,0 +1,44 @@ +--- +title: Deploy packaged apps that use Project Reunion +description: This article provides instructions for deploying packaged apps that use Project Reunion. +ms.topic: article +ms.date: 05/21/2021 +keywords: windows win32, windows app development, project reunion +ms.author: zafaraj +author: zaryaf +ms.localizationpriority: medium +--- + +# Deploy packaged apps that use Project Reunion + +This article provides guidance about deploying [MSIX](/windows/msix)-packaged apps that use Project Reunion to other computers. + +## Overview + +Before configuring your apps for deployment, review [Project Reunion deployment architecture](deployment-architecture.md) to learn more about the dependencies your app takes when it uses Project Reunion. + +By default, when you create a project using one of the [WinUI project templates](..\winui\winui3\winui-project-templates-in-visual-studio.md) that are provided with the Project Reunion extension for Visual Studio, your project includes a [Windows Application Packaging Project](/windows/msix/desktop/desktop-to-uwp-packaging-dot-net) that is configured to build the app into an MSIX package. For more information about configuring this project to build an MSIX package for your app, see [Package a desktop or UWP app in Visual Studio](/windows/msix/package/packaging-uwp-apps). + +After you build an MSIX package for your app, you have several options for deploying it to other computers. For more information, see [Manage your MSIX deployment](/windows/msix/desktop/managing-your-msix-deployment-overview). + +## Preview versions of Project Reunion + +When you install a [preview release channel](preview-channel.md) version of the Project Reunion extension for Visual Studio or the Project Reunion NuGet package on your development computer, the preview version of the [framework package](deployment-architecture.md#framework-packages-for-packaged-and-unpackaged-apps) is deployed during build time as a NuGet package dependency. + +## Stable versions of Project Reunion + +When you install a [stable release channel](stable-channel.md) version of the Project Reunion extension or the Project Reunion NuGet package on your development computer and you create a project using one of the provided WinUI 3 project templates, the generated package manifest contains a [PackageDependency](/uwp/schemas/appxpackage/uapmanifestschema/element-packagedependency) element that specifies a dependency on the framework package. + +```xml + + + +``` + +However, if you build your app package manually, you must add this **PackageDependency** element to your package manifest yourself to declare a dependency on the Project Reunion framework package. + +## Related topics + +- [Runtime architecture and deployment scenarios](deployment-architecture.md) +- [Deploy unpackaged apps that use Project Reunion](deploy-unpackaged-apps.md) +- [Release channels](release-channels.md) diff --git a/hub/apps/project-reunion/deploy-unpackaged-apps.md b/hub/apps/project-reunion/deploy-unpackaged-apps.md new file mode 100644 index 0000000000..d3f73c2a76 --- /dev/null +++ b/hub/apps/project-reunion/deploy-unpackaged-apps.md @@ -0,0 +1,86 @@ +--- +title: Deploy unpackaged apps that use Project Reunion +description: This article provides instructions for deploying unpackaged apps that use Project Reunion. +ms.topic: article +ms.date: 05/21/2021 +keywords: windows win32, windows app development, project reunion +ms.author: zafaraj +author: zaryaf +ms.localizationpriority: medium +--- + +# Deploy unpackaged apps that use Project Reunion + +This article provides guidance about deploying non-[MSIX](/windows/msix) packaged apps that use Project Reunion to other computers. + +> [!IMPORTANT] +> Unpackaged app deployment 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. + +## Overview + +Before configuring your apps for deployment, review [Project Reunion deployment architecture](deployment-architecture.md) to learn more about the dependencies your app takes when it uses Project Reunion, including dynamic dependencies. + +You can test deployment of unpackaged apps that use Project Reunion using the Project Reunion installer (.exe). The installer contains a copy of the MSIX packages for the Project Reunion run time components, which includes the [Framework](deployment-architecture.md#framework-packages-for-packaged-and-unpackaged-apps), [Main](deployment-architecture.md#main-package) and [Dynamic Dependency Lifetime Manager (DDLM)](deployment-architecture.md#dynamic-dependency-lifetime-manager-ddlm) packages. By default, the installer will automatically detect the system architecture and install the MSIX packages in either the `X64` or `X86` architectures. + +Alternatively, you can directly install the MSIX packages for the Project Reunion runtime components in your development environment or through your app's setup program. + +## Prerequisites + +- [Download the Project Reunion runtime Installer or MSIX packages](https://aka.ms/projectreunion/0.8preview) to your development computer. +- If your development computer or the deployment computer is running Windows 10 version 1909 or an earlier version, make sure sideloading is enabled. Sideloading is automatically enabled on Windows 10 version 2004 and later. + + > [!NOTE] + > The Project Reunion runtime for the version 0.8 Preview requires that sideloading is enabled to install. + +To confirm whether sideloading is enabled on Windows 10 version 1909 and earlier versions: + +1. Open **Settings**. +2. Click **Update & Security** > **For developers**. +3. In the **Use developer features** section, make sure the **Sideload apps** or **Developer mode** setting is selected (the **Developer mode** setting includes sideloading as well as other features). + + > [!NOTE] + > If the computer is managed in an enterprise environment, the computer may have a policy that disables the ability to modify these settings. If so, you may get an error when you or your app tries to install the Project Reunion runtime. In this case, you must contact your IT Professional to enable sideloading or **Developer mode**. + +## Run the Project Reunion installer in your development environment + +You can test deployment in your development environment by running the Project Reunion Installer with this command. + +```console +ProjectReunionInstall.exe +``` + +You can also run the installer with no user interaction and suppress all text output. + +```console +ProjectReunionInstall.exe --quiet +``` + +After the installation is complete, you can run your unpackaged app. For an example of how to build and run an unpackaged app that uses Project Reunion, see [Tutorial: Build and deploy an unpackaged app that uses Project Reunion](tutorial-unpackaged-deployment.md). + +## Launch the Project Reunion installer from your setup program + +To test deployment of your unpackaged app to end users, you can launch the .exe installer from your setup program or MSI by using [ShellExecute](/windows/win32/shell/launch). This is very similar to other runtime installers you may have used, like .NET, Visual C++, or DirectX. + +For a code example that demonstrates how to run the Project Reunion Installer from your setup program, see the **RunInstaller** function in [this example](https://aka.ms/testruninstaller). + +## Directly deploy the MSIX packages from your setup program + +As an alternative to using the Project Reunion installer for deployment to end users, you can manually deploy the MSIX packages through your app's program or MSI. This option can be best for developers who want more control or need offline installations. + +For an example that demonstrates how your setup program can install the MSIX packages, see [this example](https://aka.ms/testinstallpackages). + +## Using Project Reunion features at run time + +Unpackaged apps must use the [dynamic dependencies API](https://github.com/microsoft/ProjectReunion/blob/main/specs/dynamicdependencies/DynamicDependencies.md) to use Project Reunion features such as WinUI, App lifecycle, MRT Core, and DWriteCore. This feature enables unpackaged apps to dynamically take a dependency on the Project Reunion framework package and any other MSIX framework packages. For more information, see [Additional requirements for unpackaged apps](deployment-architecture.md#additional-requirements-for-unpackaged-apps). + +For more information about using the dynamic dependencies API in your unpackaged app, see [Tutorial: Build and deploy an unpackaged app that uses Project Reunion](tutorial-unpackaged-deployment.md). + + +## Related topics + +- [Runtime architecture and deployment scenarios](deployment-architecture.md) +- [Tutorial: Build and deploy an unpackaged app that uses Project Reunion](tutorial-unpackaged-deployment.md) +- [Check for installed versions of the Project Reunion runtime](check-project-reunion-versions.md) +- [Remove outdated Project Reunion runtime versions from your development computer](remove-project-reunion-versions.md) +- [Release channels](release-channels.md) +- [Deploy packaged apps that use Project Reunion](deploy-packaged-apps.md) diff --git a/hub/apps/project-reunion/deployment-architecture.md b/hub/apps/project-reunion/deployment-architecture.md new file mode 100644 index 0000000000..69aada3c11 --- /dev/null +++ b/hub/apps/project-reunion/deployment-architecture.md @@ -0,0 +1,99 @@ +--- +title: Runtime architecture and deployment scenarios for Project Reunion +description: This article provides a high level explanation of the Project Reunion deployment architecture and scenarios. +ms.topic: article +ms.date: 05/21/2021 +keywords: windows win32, windows app development, project reunion +ms.author: zafaraj +author: zaryaf +ms.localizationpriority: medium +--- + +# Runtime architecture and deployment scenarios for Project Reunion + +This article explains the basic building blocks and high-level architecture of Project Reunion deployment. For instructions to deploy apps that use Project Reunion, see these articles: + +- [Deploy MSIX-packaged apps that use Project Reunion](deploy-packaged-apps.md) +- [Deploy non-MSIX packaged apps that use Project Reunion](deploy-unpackaged-apps.md) (experimental feature) + +## Key terms + +| Term | Definition | +|------|------------| +| **Project Reunion runtime** | All the MSIX packages required by an app to be able to use Project Reunion. These packages include: Framework, Main, and DDLM. | +| **Framework package** | Contains binaries used at run time by apps. The framework includes a bootstrapper component that enables apps to automatically install the latest version of Project Reunion, which will be updated on a regular release cadence. | +| **Main package** | Contains the background tasks, services, app extensions, and other components not included in the Framework package. These are generally out-of-process services that are brokered between apps, such as push notifications and the Clipboard. | +| **Dynamic Dependency Lifetime Manager (DDLM)** | A main package that prevents the OS from performing servicing updates to the MSIX packages while an unpackaged app is in use. | +| **Bootstrapper** | An app-local binary used by unpackaged apps to locate and load the best Project Reunion version match as needed by the app. The bootstrapper is delivered through a redistributable named Microsoft.ProjectReunion.Bootstrap.dll. | +| **Provisioning** | The process of installing and registering packages (including files and registry keys) system-wide to eliminate the need for repeated installation by the other users. It can be done either as part of the OS or done during installation of an app. | +| **Installer** | An installation technology for installing an app, such an MSI, App Installer, or .exe setup. | +| **MSIX** | Modern installer technology that enables users to safely install an app per user, directly from the Microsoft Store or a web site. On Enterprise or shared PCs, apps can be installed for all users via PowerShell and MDM. | + +## Framework packages for packaged and unpackaged apps + +When you build an app that uses Project Reunion, your app references a set of Project Reunion runtime components that are distributed to end users via a *framework package*. The framework package allows packaged apps to access Project Reunion components through a single shared source on the user's device, instead of bundling them into the app package. The framework package also carries its own resources, such as DLLs and API definitions (COM and Windows Runtime registrations). These resources run in the context of your app, so they inherit the capabilities and privileges of your app, and don't assert any capabilities or privileges of their own. + +The Project Reunion framework package is an MSIX package that is deployed to end users through the Microsoft Store. It can be easily and quickly updated with the latest releases, in addition to security and reliability fixes. All apps that use Project Reunion on a computer have a dependency on a shared instance of the framework package, as illustrated in the following diagram. + +![Diagram of how apps access the Project Reunion framework package](images/framework.png) + +When a new version of the Project Reunion framework package is released, all apps are updated to the new version without themselves having to redistribute a copy. Windows updates to the newest version of frameworks as they are released, and apps will automatically reference the latest framework package version during relaunch. Older framework package versions will not be removed from the system until they are no longer running or being actively used by apps on the system. + +![Diagram of how apps get updates to the Project Reunion framework package](images/framework-update.png) + +Because app compatibility is important to Microsoft and to apps that depend on Project Reunion, the Project Reunion framework package follows [Semantic Versioning 2.0.0](https://semver.org/) rules. This means that after we release version 1.0 of Project Reunion, the Project Reunion framework package will guarantee compatibility between minor and patch version changes, and breaking changes will occur only between major version updates. + +## Additional requirements for unpackaged apps + +> [!IMPORTANT] +> [Unpackaged app deployment](deploy-unpackaged-apps.md) 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. + +Unpackaged apps must use the [dynamic dependencies API](https://github.com/microsoft/ProjectReunion/blob/main/specs/dynamicdependencies/DynamicDependencies.md) to use Project Reunion features such as WinUI, App lifecycle, MRT Core, and DWriteCore. This feature enables unpackaged apps to dynamically take a dependency on the Project Reunion framework package and any other MSIX framework packages. This allows unpackaged applications to keep their existing deployment mechanism, such as MSI or any installer, and be able to leverage Project Reunion or other frameworks in their application. Dynamic dependencies can be used by both packaged applications and unpackaged apps, although it is primarily intended to be used by unpackaged apps. + +There are three components to dynamic dependencies: the bootstrapper, the Dynamic Dependency Lifetime Manager (DDLM), and the Main package. + +### Bootstrapper + +The bootstrapper is a library that must be included with the main application. It provides the following behavior: + +- Initializes the Dynamic Dependency Lifetime Manager (DDLM) for the Project Reunion Framework package. +- Finds and loads the Project Reunion framework package to the app's package graph. + +To accomplish these tasks, the bootstrapper must be one of the first calls in an unpackaged app's startup code so it can properly initialize the system for the unpackaged app. + +### Dynamic Dependency Lifetime Manager (DDLM) + +The purpose of the DDLM is to prevent servicing of the Project Reunion Framework package while it is in use by an unpackaged app. It contains a server that must be initialized by the bootstrapper early in an app's startup to provide that functionality. + +There is one DDLM for each version and architecture of the Project Reunion Framework package. This means on an `x64` computer, you may have both an `x86` and an `x64` version of the DDLM to support apps of both architectures. + +#### Main package + +The Main package contains a short-lived server process that keeps track of dynamic dependencies that have been added. This is not used if an app's only dependency is on Project Reunion. + +## Deployment scenarios + +### Project Reunion MSIX packages are already installed on the computer + +If Project Reunion MSIX packages (Framework, Main, and DDLM) packages are already installed on the computer, no further installation is expected by a packaged or unpackaged app. MSIX packages are installed to a system-wide location with only one copy on disk. Therefore, if an app attempts installation of Project Reunion when there are no missing packages, then the installation is not performed. + +### Project Reunion Runtime is not installed on the computer + +When installing Project Reunion, all Project Reunion packages (Framework, Main, and DDLM) should be installed to ensure that all apps and the end-user avoid experiencing friction in the future. + +### Project Reunion Runtime needs to be provisioned system-wide + +Provisioning requires elevation and an admin user-token. If the app's MSI or setup program attempts to install the app system-wide, the user will see a UAC prompt requesting their permission. + +If the user does not grant full-trust access, then the Project Reunion Runtime will at least be installed for the current user doing the installation. If permission is granted, the Project Reunion Runtime will be registered for all users. + +In a managed Enterprise environment, the IT admin should be able to provision for everyone as usual. + +## Related topics + +- [Deploy apps that use Project Reunion](deploy-apps-that-use-project-reunion.md) +- [Check for installed versions of the Project Reunion runtime](check-project-reunion-versions.md) +- [Remove outdated Project Reunion runtime versions from your development computer](remove-project-reunion-versions.md) +- [Release channels](release-channels.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) diff --git a/hub/apps/project-reunion/get-started-with-project-reunion.md b/hub/apps/project-reunion/get-started-with-project-reunion.md index ef6aed6d66..e7d1f6fa7c 100644 --- a/hub/apps/project-reunion/get-started-with-project-reunion.md +++ b/hub/apps/project-reunion/get-started-with-project-reunion.md @@ -1,73 +1,26 @@ --- -description: This article provides instructions for installing the Project Reunion extension for Visual Studio 2019 on your development computer and using Project Reunion in new or existing projects. -title: Get started with Project Reunion +title: Get started developing apps with Project Reunion +description: This article provides instructions for using Project Reunion in new or existing projects. ms.topic: article -ms.date: 03/19/2021 +ms.date: 05/21/2021 keywords: windows win32, desktop development, project reunion ms.author: mcleans author: mcleanbyron ms.localizationpriority: medium --- -# Get started with Project Reunion +# Get started developing apps with Project Reunion -This article provides instructions for installing the Project Reunion extension for Visual Studio 2019 on your development computer and using Project Reunion in new or existing projects. Before you install and use Project Reunion, see the [limitations and known issues](index.md#limitations-and-known-issues). - -> [!NOTE] -> If you created a project with an earlier preview or release version of Project Reunion or WinUI 3, you can [update the project to use the latest release](update-existing-projects-to-the-latest-release.md). - -## Set up your development environment - -1. Ensure that your development computer has Windows 10, version 1809 (build 17763), or a later OS version installed. - -2. Install [Visual Studio 2019, version 16.9](https://visualstudio.microsoft.com/vs/) if you haven't done so already. - - > [!NOTE] - > Visual Studio 2019, version 16.9 does not currently support all WinUI 3 tooling features. To access the full suite of WinUI 3 tooling features, please use [Visual Studio 16.10 Preview](https://visualstudio.microsoft.com/vs/preview/). For more information about WinUI 3 tooling support, see [Windows UI Library 3 - Project Reunion 0.5](../winui/winui3/index.md#visual-studio-support). - - You must include the following components when installing Visual Studio: - - On the **Workloads** tab of the installation dialog, make sure **Universal Windows Platform development** is selected. - - On the **Individual components** tab of the installation dialog, make sure **Windows 10 SDK (10.0.19041.0)** is selected in the **SDKs, libraries, and frameworks** section. - - To build .NET apps, you must also include the following components: - - On the **Workloads** tab of the installation dialog, make sure **.NET Desktop Development** is selected. - - To build C++ apps, you must also include the following components: - - On the **Workloads** tab of the installation dialog, make sure **Desktop development with C++** is selected. - - In the **Installation details** pane on the right side of the installation dialog, make sure the **C++ (v142) Universal Windows Platform tools** optional component is selected in the **Universal Windows Platform development** section. - -3. If you previously installed the [WinUI 3 Preview extension for Visual Studio](https://marketplace.visualstudio.com/items?itemName=Microsoft-WinUI.WinUIProjectTemplates), uninstall the extension. For more information about how to uninstall an extension, see [Manage extensions for Visual Studio](/visualstudio/ide/finding-and-using-visual-studio-extensions). - -4. Make sure your system has a NuGet package source enabled for the official NuGet service index at `https://api.nuget.org/v3/index.json`. - - 1. In Visual Studio, select **Tools** -> **NuGet Package Manager** -> **Package Manager Settings** to open the **Options** dialog. - 2. In the left pane of the **Options** dialog, select the **Package Sources** tab, and make sure there is a package source for **nuget.org** that points to `https://api.nuget.org/v3/index.json` as the source URL. For more information, see [Common NuGet configurations](/nuget/consume-packages/configuring-nuget-behavior). - -5. Download and install the Project Reunion 0.5 extension for Visual Studio. There are two versions of the extension: one for desktop (C#/.NET 5 or C++/WinRT) apps and one for UWP apps. - - To use Project Reunion in desktop (C#/.NET 5 or C++/WinRT) apps: - - In Visual Studio 2019, click **Extensions** > **Manage Extensions**, search for **Project Reunion**, and install the **Project Reunion** extension. - - Alternatively, you can download and install the [Project Reunion 0.5 extension](https://marketplace.visualstudio.com/items?itemName=ProjectReunion.MicrosoftProjectReunion) directly from the Visual Studio Marketplace. - - To use Project Reunion in UWP apps, you must install a preview version of the extension that is not supported for production environments: - - Uninstall any existing versions of the Project Reunion VSIX. - - In Visual Studio 2019, click **Extensions** > **Manage Extensions**, and click **Change your settings for Extensions** in the bottom left corner. Turn off automatic updates for packages installed for all users before installing the older version. - - Download and install the [Project Reunion 0.5 Preview extension](https://download.microsoft.com/download/9/9/8/9981a84b-8fd8-4645-9dce-c62761601f17/ProjectReunion.Extension.vsix). - - For instructions about how to add the VSIX package to Visual Studio, see [Manage extensions for Visual Studio](/visualstudio/ide/finding-and-using-visual-studio-extensions). - - ![Screenshot of Project Reunion extension being installed](images/reunion-extension-install.png) - -6. To use WinUI 3 tooling such as Live Visual Tree, Hot Reload, and Live Property Explorer in Visual Studio 2019 16.10 Preview, you must enable WinUI 3 tooling with Visual Studio Preview Features. For instructions, see [How to Enable UI Tooling for WinUI 3](https://github.com/microsoft/microsoft-ui-xaml/issues/4140). +After you [set up your development environment](set-up-your-development-environment.md), you're ready to start developing with Project Reunion. This article provides instructions about using Project Reunion in new or existing projects. ## Create a new project that uses Project Reunion -The Project Reunion 0.5 extensions for Visual Studio 2019 (including the extension for desktop apps and the preview extension for UWP apps) provide project templates that generate projects with a WinUI 3-based UI layer and provide access to all other Project Reunion APIs. For more information about the available project templates, see [WinUI 3 project templates in Visual Studio](..\winui\winui3\winui-project-templates-in-visual-studio.md). +If you created a project with an earlier preview or release version of Project Reunion or WinUI 3, see [Update existing projects to the latest release of Project Reunion](update-existing-projects-to-the-latest-release.md) for instructions on updating to the latest version. > [!NOTE] -> The desktop (C#/.NET 5 and C++/WinRT) project templates are supported for use in production environments. The UWP project templates are available as a developer preview only, and cannot be used to build apps for production environments. +> The desktop (C#/.NET 5 and C++/WinRT) project templates included in the [stable release channel](stable-channel.md) of Project Reunion are supported for use in production environments. The UWP and other project templates included in the [preview release channel](preview-channel.md) Project Reunion (Preview) extension are available as a developer preview only, and should not be used to build apps for production environments. -To create a new project that uses Project Reunion 0.5: +To create a new project that uses Project Reunion: 1. Follow the instructions in the following articles: @@ -76,13 +29,9 @@ To create a new project that uses Project Reunion 0.5: - [Build a basic WinUI 3 desktop app](..\winui\winui3\desktop-build-basic-winui3-app.md) > [!NOTE] - > If you create a C#/.NET 5 project, make sure that your project's .NET SDK references are up to date using [these instructions](index.md#net-sdk-references). - -2. After you create your project, you have access to the following Project Reunion APIs and components in addition to all other Windows and .NET APIs that are typically available to desktop and UWP apps. + > If you create a C#/.NET 5 project, make sure that your project's .NET SDK references are up to date using [these instructions](release-channels.md#net-sdk-references). - - [Windows UI Library 3](../winui/winui3/index.md) - - [Manage resources MRT Core](mrtcore/mrtcore-overview.md) - - [Render text with DWriteCore](dwritecore.md) +2. After you create your project, you have access to the Project Reunion APIs and components in addition to all other Windows and .NET APIs that are typically available to desktop and UWP apps. For more information about the available APIs and components, see [stable release channel](stable-channel.md) and [preview release channel](preview-channel.md). To confirm that your new project uses Project Reunion, expand the **Dependencies** > **Packages** node under your project in **Solution Explorer**. You should see several **Microsoft.ProjectReunion** packages listed under this node, similar to the following image. @@ -90,7 +39,7 @@ To confirm that your new project uses Project Reunion, expand the **Dependencies ## Use Project Reunion in an existing project -If you have an existing project in which you want to use Project Reunion, you can install the Project Reunion 0.5 NuGet package in your project. This scenario has [some limitations](index.md#using-the-project-reunion-nuget-package-in-existing-projects). +If you have an existing project in which you want to use Project Reunion, you can install the latest stable or latest preview version of the Project Reunion NuGet package in your project. This scenario has [some limitations](release-channels.md#using-the-project-reunion-nuget-package-in-existing-projects). 1. Open an existing desktop project (either C#/.NET 5 or C++/WinRT) or UWP project in Visual Studio 2019. @@ -110,7 +59,7 @@ If you have an existing project in which you want to use Project Reunion, you ca ![Screenshot of Project Reunion NuGet package being installed](images/reunion-nuget-install.png) -6. **For C#/.NET 5 projects only**: In order to receive all of the fixes from the latest stable release of Project Reunion 0.5, you'll need to update your project file to explicitly set your .NET SDK to the latest version. For more information, see [.NET SDK references](index.md#net-sdk-references). +6. **For C#/.NET 5 projects only**: In order to receive all of the fixes from the latest stable release of Project Reunion 0.5, you'll need to update your project file to explicitly set your .NET SDK to the latest version. For more information, see [.NET SDK references](release-channels.md#net-sdk-references). 7. After you install the **Microsoft.ProjectReunion** package, you can use the following Project Reunion APIs and components in your project: @@ -121,12 +70,17 @@ If you have an existing project in which you want to use Project Reunion, you ca The following Project Reunion samples are currently available for you to explore. +> [!NOTE] +> These samples currently support Project Reunion version 0.5. New and updated samples for Project Reunion version 0.8 Preview are coming soon. + - [DWriteCore gallery sample](https://github.com/microsoft/Project-Reunion-Samples/tree/main/DWriteCore/DWriteCoreGallery): This sample application demonstrates the [DWriteCore](dwritecore.md) API. - [MRT Core sample](https://github.com/microsoft/Project-Reunion-Samples/tree/main/MrtCore): This sample application demonstrates the [MRT Core](mrtcore/mrtcore-overview.md) API. - [Hello World sample](https://github.com/microsoft/Project-Reunion-Samples/tree/main/HelloWorld/reunioncppdesktopsampleapp): This sample demonstrates a basic integration with the Project Reunion NuGet package. -- [Xaml Controls Gallery](https://aka.ms/winui3/xcg): This is a sample app that showcases all of the WinUI 3 controls in action. +- [Xaml Controls Gallery](https://aka.ms/winui3/xcg): This is a sample app that showcases all of the WinUI 3 controls in action. ## Related topics - [Build desktop Windows apps with Project Reunion](index.md) -- [Deploy apps that use Project Reunion](deploy-apps-that-use-project-reunion.md) +- [Release channels and release notes](release-channels.md) +- [Set up your development environment](set-up-your-development-environment.md) +- [Deploy apps that use Project Reunion](deploy-apps-that-use-project-reunion.md) \ No newline at end of file diff --git a/hub/apps/project-reunion/images/remove-reunion-packages-versions.png b/hub/apps/project-reunion/images/remove-reunion-packages-versions.png new file mode 100644 index 0000000000..7833c3085b Binary files /dev/null and b/hub/apps/project-reunion/images/remove-reunion-packages-versions.png differ diff --git a/hub/apps/project-reunion/images/tutorial-deploy-create-project.png b/hub/apps/project-reunion/images/tutorial-deploy-create-project.png new file mode 100644 index 0000000000..3b0b4ca147 Binary files /dev/null and b/hub/apps/project-reunion/images/tutorial-deploy-create-project.png differ diff --git a/hub/apps/project-reunion/images/tutorial-deploy-name-project.png b/hub/apps/project-reunion/images/tutorial-deploy-name-project.png new file mode 100644 index 0000000000..a129046408 Binary files /dev/null and b/hub/apps/project-reunion/images/tutorial-deploy-name-project.png differ diff --git a/hub/apps/project-reunion/images/tutorial-deploy-nuget-reference.png b/hub/apps/project-reunion/images/tutorial-deploy-nuget-reference.png new file mode 100644 index 0000000000..23a145b058 Binary files /dev/null and b/hub/apps/project-reunion/images/tutorial-deploy-nuget-reference.png differ diff --git a/hub/apps/project-reunion/index.md b/hub/apps/project-reunion/index.md index cccf2a6da6..32357e59db 100644 --- a/hub/apps/project-reunion/index.md +++ b/hub/apps/project-reunion/index.md @@ -1,38 +1,33 @@ --- +title: Build desktop Windows apps with Project Reunion description: Learn about Project Reunion, benefits it provides to developers, what is ready for developers now, and how to give feedback. -title: Build desktop Windows apps with Project Reunion 0.5 ms.topic: article -ms.date: 03/19/2021 +ms.date: 05/21/2021 keywords: windows win32, desktop development, project reunion ms.author: mcleans author: mcleanbyron ms.localizationpriority: medium --- -# Build desktop Windows apps with Project Reunion 0.5 +# Build desktop Windows apps with Project Reunion Project Reunion is a set of new developer components and tools that represent the next evolution in the Windows app development platform. Project Reunion provides a unified set of APIs and tools that can be used in a consistent way by any desktop app on a broad set of target Windows 10 OS versions. -Project Reunion does not replace the existing desktop Windows app platforms and frameworks such as .NET (including Windows Forms and WPF) and C++ desktop (Win32). Instead, it complements these existing platforms with a common set of APIs and tools that developers can rely on across these platforms. For more details, see [Benefits of Project Reunion](#benefits-of-project-reunion-for-windows-developers). +Project Reunion does not replace the existing desktop Windows app types such as .NET (including Windows Forms and WPF) and desktop Win32 with C++. Instead, it complements these existing platforms with a common set of APIs and tools that developers can rely on across these platforms. For more details, see [Benefits of Project Reunion](#benefits-of-project-reunion-for-windows-developers). > [!NOTE] -> Project Reunion 0.5 is supported for use in MSIX-packaged desktop apps (C# .NET 5 or C++ desktop) in production environments. Packaged desktop apps that use Project Reunion 0.5 can be published to the Microsoft Store. For UWP apps, Project Reunion 0.5 is available only as a preview. This release is not supported for UWP apps that are used in production environments. -> >**Project Reunion** is a code name that may change in a future release. -## Overview +## Get started with Project Reunion -Project Reunion provides an extension for Visual Studio 2019 that includes project templates configured to use Project Reunion components in new projects. The Project Reunion libraries are also available via a NuGet package that you can install in existing projects. For more information, see [Get started with Project Reunion](get-started-with-project-reunion.md). +Project Reunion provides an extension for Visual Studio 2019 that includes project templates configured to use Project Reunion components in new projects. The Project Reunion libraries are also available via a NuGet package that you can install in existing projects. -After you build an app that uses Project Reunion, you can deploy it to other computers. For more information, see [Deploy apps that use Project Reunion](deploy-apps-that-use-project-reunion.md). +For more information about getting started with Project Reunion, see these articles: -Project Reunion 0.5 includes the following sets of APIs and components you can use in your apps. You can learn more about the future plans to bring other components into Project Reunion [here](https://github.com/microsoft/ProjectReunion/blob/master/docs/README.md). - -| Component | Description | -|---------|-------------| -| [Windows UI Library 3](../winui/winui3/index.md) | Windows UI Library (WinUI) 3 is the next generation of the Windows user experience (UX) platform for Windows apps. This release includes Visual Studio project templates to help get started [building apps with a WinUI-based user interface](..\winui\winui3\winui-project-templates-in-visual-studio.md), and a NuGet package that contains the WinUI libraries. | -| [Manage resources with MRT Core](mrtcore/mrtcore-overview.md) | MRT Core provides APIs to load and manage resources used by your app. MRT Core is a streamlined version of the modern [Windows Resource Management System](/windows/uwp/app-resources/resource-management-system). | -| [Render text with DWriteCore](dwritecore.md) | DWriteCore provides access to all current DirectWrite features for text rendering, including a device-independent text layout system, hardware-accelerated text, multi-format text, and wide language support. | +- [Release channels and release notes](release-channels.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) +- [Deploy apps that use Project Reunion](deploy-apps-that-use-project-reunion.md) ## Benefits of Project Reunion for Windows developers @@ -54,43 +49,6 @@ Project Reunion APIs will work on Windows 10, version 1809, and all later versio New Windows APIs and features have typically been tied to OS releases that happen on a once or twice a year release cadence. Project Reunion will ship updates on a faster cadence, enabling you to get earlier and more rapid access to innovations in the Windows development platform as soon as they are created. -## Limitations and known issues - -The following limitations and known issues apply generally to Project Reunion 0.5. - -- **Desktop apps (C# .NET 5 or C++ desktop)**: Project Reunion 0.5 cannot be used in unpackaged desktop apps (C# .NET 5 or C++ desktop). This release is supported for use only in MSIX-packaged desktop apps. -- **UWP apps**: Project Reunion 0.5 is not supported for UWP apps that are used in production environments. To use Project Reunion in UWP apps, you must use a preview version of the Project Reunion 0.5 extension that is not supported for production environments. For more information about installing the preview extension, see [Set up your development environment](get-started-with-project-reunion.md#set-up-your-development-environment). -- The [WinUI 3 developer tool limitations](..\winui\winui3\index.md#developer-tools) also apply to any project that uses Project Reunion 0.5. - -The following limitations and known issues apply to specific developer scenarios. - -#### .NET SDK references - -In order to receive all of the fixes from the latest stable or preview release of Project Reunion in C# .NET 5 projects, you'll need to explicitly set your .NET SDK to the correct version. - -To determine the correct version for your app, locate the `` tag in your project file. Using the Windows SDK build number that your app is targeting in the `` tag (such as 18362 or 19041), add the following item to your project file, then save your project: - -```xml - - - - -``` - -Note this workaround is required for .NET SDK 5.0.203 and earlier, but will not be required for .NET SDK 5.0.204 or 5.0.300 - -#### Using the Project Reunion NuGet package in existing projects - -If you want to [use the Project Reunion 0.5 NuGet package in existing projects](get-started-with-project-reunion.md#use-project-reunion-in-an-existing-project), be aware of the following limitations: - -- The Project Reunion 0.5 NuGet package is supported for use with desktop (C# .NET 5 and C++ desktop) projects in production environments. It is available as a developer preview for UWP projects, and is not supported for use with UWP projects in production environments. -- The Project Reunion 0.5 NuGet package (named **Microsoft.ProjectReunion**) contains other sub-packages (including **Microsoft.ProjectReunion.Foundation** and **Microsoft.ProjectReunion.WinUI**) that contain the implementations for components including WinUI, MRT Core, and DWriteCore. You cannot install these sub-packages individually to reference only certain components in your project. You must install the **Microsoft.ProjectReunion** package, which includes all of the components. -- If you install the Project Reunion 0.5 NuGet package to an existing project, you can only use non-WinUI 3 components that are part of Project Reunion in your project. To use WinUI 3, you must create a new project using one of the WinUI 3 project templates as described in the previous section. - -#### ASTA to STA threading model - -If you're migrating code from an existing UWP app to a new C# .NET 5 or C++ desktop WinUI 3 project that uses Project Reunion, be aware that the new project uses the [single-threaded apartment (STA)](/windows/win32/com/single-threaded-apartments) threading model instead of the [Application STA (ASTA)](https://devblogs.microsoft.com/oldnewthing/20210224-00/?p=104901) threading model used by UWP apps. If your code assumes the non re-entrant behavior of the ASTA threading model, your code may not behave as expected. - ## Developer roadmap For the latest Project Reunion plans, see our [roadmap](https://github.com/microsoft/ProjectReunion/blob/main/docs/roadmap.md). @@ -101,9 +59,7 @@ We are building Project Reunion as an open source project. We have a lot more in ## Related topics -- [Build desktop Windows apps with Project Reunion](index.md) -- [Get started with Project Reunion](get-started-with-project-reunion.md) +- [Release channels and release notes](release-channels.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) - [Deploy apps that use Project Reunion](deploy-apps-that-use-project-reunion.md) -- [Windows UI Library 3](../winui/winui3/index.md) -- [Manage resources with MRT Core](mrtcore/mrtcore-overview.md) -- [Render text with DWriteCore](dwritecore.md) diff --git a/hub/apps/project-reunion/mrtcore/mrtcore-overview.md b/hub/apps/project-reunion/mrtcore/mrtcore-overview.md index a18b3b69d0..cded8724a2 100644 --- a/hub/apps/project-reunion/mrtcore/mrtcore-overview.md +++ b/hub/apps/project-reunion/mrtcore/mrtcore-overview.md @@ -24,7 +24,7 @@ A PRI file contains actual string resources. Embedded binary and file path resou PRI files contain only data, so they don't use the portable executable (PE) format. They are specifically designed to be data-only. > [!NOTE] -> Before you can use MRT Core to retrieve strings and images in a WinUI 3 project that uses C#/.NET 5, you must ensure that these resources are configured so that they can be indexed in the resources.pri file. Otherwise, these resources cannot be retrieved by MRT Core. +> In Project Reunion version 0.5, you must ensure that your string and images resources are configured so that they can be indexed in the resources.pri file. Otherwise, these resources cannot be retrieved by MRT Core. This is not required in Project Reunion 0.8. > > * Strings: Make sure the **Build Action** property for resources files (.resw) is set to **PRIResource**. This property is set automatically if you add a new **Resources File (.resw)** item to your project. > * Images: Make sure the **Build Action** property for image files are set to **Content**. This property is set automatically if you add an existing image to a folder named **Assets** in your project. diff --git a/hub/apps/project-reunion/preview-channel.md b/hub/apps/project-reunion/preview-channel.md new file mode 100644 index 0000000000..3ef0569fee --- /dev/null +++ b/hub/apps/project-reunion/preview-channel.md @@ -0,0 +1,92 @@ +--- +title: Preview release channel for Project Reunion +description: Provides information about the preview release channel for Project Reunion. +ms.topic: article +ms.date: 05/21/2021 +keywords: windows win32, windows app development, project reunion +ms.author: zafaraj +author: zaryaf +ms.localizationpriority: medium +--- + +# Preview release channel for Project Reunion + +The preview channel provides releases of Project Reunion that include experimental features. The preview channel is not supported for use in production environments, and apps that use the preview channel releases cannot be published to the Microsoft Store. + +The latest release of the preview channel is Project Reunion version 0.8 Preview. + +> [!div class="button"] +> [Download the latest preview release](https://aka.ms/projectreunion/previewdownload) + +## Features in the latest preview release + +The latest preview channel release includes the following sets of APIs and components you can explore and experiment with in your apps. + +| Component | Description | +|---------|-------------| +| [Windows UI Library 3](../winui/winui3/index.md) | Windows UI Library (WinUI) 3 is the next generation of the Windows user experience (UX) platform for Windows apps. This release includes Visual Studio project templates to help get started [building apps with a WinUI-based user interface](..\winui\winui3\winui-project-templates-in-visual-studio.md), and a NuGet package that contains the WinUI libraries. | +| [Manage resources with MRT Core](mrtcore/mrtcore-overview.md) | MRT Core provides APIs to load and manage resources used by your app. MRT Core is a streamlined version of the modern [Windows Resource Management System](/windows/uwp/app-resources/resource-management-system). | +| [Render text with DWriteCore](dwritecore.md) | DWriteCore provides access to all current DirectWrite features for text rendering, including a device-independent text layout system, hardware-accelerated text, multi-format text, and wide language support. | +| [AppLifecycle](applifecycle/applifecycle-instancing.md) | **Experimental feature**. Apps can use AppLifecycle APIs to manage their lifecycle behavior, such as retrieving activation information and defining your app's instancing model. | +| [Deploy unpackaged apps](deploy-unpackaged-apps.md) | **Experimental feature**. Unpackaged apps can dynamically take a dependency on the Project Reunion runtime packages so you can continue using your existing MSI or setup program for app deployment. | + +## Release notes + +This section lists new features, limitations and known issues for Project Reunion version 0.8 Preview. + +- **No support for Any CPU build configuration**: Project Reunion is written in native code and thus does not support **Any CPU** build configurations. The [WinUI project templates](../winui/winui3/winui-project-templates-in-visual-studio.md) only allow architecture-specific builds. When [adding Project Reunion](get-started-with-project-reunion.md#use-project-reunion-in-an-existing-project) to an existing .NET application or component that supports **Any CPU**, you must specify the desired architecture: `x86`, `x64` or `arm64`. + +#### WinUI 3 + +Project Reunion 0.8 Preview introduces critical bug fixes (including those fixed in Project Reunion 0.5 servicing releases) and other changes for WinUI. For a complete list, see the [WinUI 3 - Project Reunion 0.8 release notes](../winui/winui3/release-notes/release-notes-08-preview.md). + +#### AppLifecycle (experimental feature) + +This release introduces new experimental features related to managing the app lifecycle of your app. + +- All apps (packaged and unpackaged) can use **GetActivatedEventArgs** (although packaged apps can already use the implementation of this in the platform). +- Only unpackaged apps can use the **RegisterForXXXActivation** functions. +- Packaged desktop apps can use app lifecycle instancing. +- UWP apps cannot use app lifecycle features in the current release. + +For more information, see [App instancing in AppLifecycle](applifecycle/applifecycle-instancing.md) and [Rich activation in AppLifecycle](applifecycle/applifecycle-rich-activation.md). + +#### Deployment for unpackaged apps (experimental feature) + +This release introduces new experimental deployment features for unpackaged apps (that is, apps that are not deployed in an MSIX package). Unpackaged apps can now dynamically take a dependency on the Project Reunion runtime packages so you can continue using your existing MSI or setup program for app deployment. This is available through the following features: + +- Standalone installer for Project Reunion. +- MSIX package bundle that includes dynamic dependencies functionality. + +For more more information, see [Deploy unpackaged apps](deploy-unpackaged-apps.md). + +#### DWriteCore + +This release adds the following features: + +- Text decorations (underline and strikethrough in the text layout API) +- Vertical text layout +- Font face kerning API +- Experimental support for unpackaged apps + +For more more information, see [Render text with DWriteCore](dwritecore.md). + +#### MRT Core + +This release adds the following features: + +- The build action for resources is now automatically set, reducing the need for manual project configuration. +- Experimental support for unpackaged apps. + +For more more information, see [Manage resources with MRT Core](mrtcore/mrtcore-overview.md). + +#### Samples + +The [Project Reunion samples](https://github.com/microsoft/Project-Reunion-Samples) do not yet work with Project Reunion version 0.8 Preview. New and updated samples, including samples that demonstrate new features such as unpackaged app deployment, are coming soon. + +## Related topics + +- [Stable channel](stable-channel.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) +- [Deploy apps that use Project Reunion](deploy-apps-that-use-project-reunion.md) \ No newline at end of file diff --git a/hub/apps/project-reunion/release-channels.md b/hub/apps/project-reunion/release-channels.md new file mode 100644 index 0000000000..c2194c0bb7 --- /dev/null +++ b/hub/apps/project-reunion/release-channels.md @@ -0,0 +1,55 @@ +--- +title: Project Reunion release channels and release notes +description: Learn about Project Reunion release channels and what's in the latest releases. +ms.topic: article +ms.date: 05/21/2021 +keywords: windows win32, windows app development, project reunion +ms.author: zafaraj +author: zaryaf +ms.localizationpriority: medium +--- + +# Project Reunion release channels and release notes + +Project Reunion currently provides two release channels: **stable** and **preview**. For more details about the features and latest release notes for each channel, see these articles: + +- [Stable channel](stable-channel.md): This channel is supported for use by apps in production environments. +- [Preview channel](preview-channel.md): This channel includes experimental features, and is not supported for use in production environments. + +## Known issues and limitations for all release channels + +The following known issues and limitations apply to both stable channel and preview channel releases of Project Reunion. + +#### .NET SDK references + +In order to receive all of the fixes from the latest stable or preview release of Project Reunion in C# .NET 5 projects, you'll need to explicitly set your .NET SDK to the correct version. + +To determine the correct version for your app, locate the `` tag in your project file. Using the Windows SDK build number that your app is targeting in the `` tag (such as 18362 or 19041), add the following item to your project file, then save your project: + +```xml + + + + +``` + +Note this workaround is required for .NET SDK 5.0.203 and earlier, but will not be required for .NET SDK 5.0.204 or 5.0.300 + +#### Using the Project Reunion NuGet package in existing projects + +If you want to [use the Project Reunion NuGet package in existing projects](get-started-with-project-reunion.md#use-project-reunion-in-an-existing-project), be aware of the following limitations: + +- The Project Reunion NuGet package is supported for use with desktop (C# .NET 5 and C++ desktop) projects in production environments. It is available as a developer preview for UWP projects, and is not supported for use with UWP projects in production environments. +- The Project Reunion NuGet package (named **Microsoft.ProjectReunion**) contains other sub-packages (including **Microsoft.ProjectReunion.Foundation** and **Microsoft.ProjectReunion.WinUI**) that contain the implementations for components including WinUI, MRT Core, and DWriteCore. You cannot install these sub-packages individually to reference only certain components in your project. You must install the **Microsoft.ProjectReunion** package, which includes all of the components. + +#### ASTA to STA threading model + +If you're migrating code from an existing UWP app to a new C# .NET 5 or C++ desktop WinUI 3 project that uses Project Reunion, be aware that the new project uses the [single-threaded apartment (STA)](/windows/win32/com/single-threaded-apartments) threading model instead of the [Application STA (ASTA)](https://devblogs.microsoft.com/oldnewthing/20210224-00/?p=104901) threading model used by UWP apps. If your code assumes the non re-entrant behavior of the ASTA threading model, your code may not behave as expected. + +## Related topics + +- [Stable channel](stable-channel.md) +- [Preview channel](preview-channel.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) +- [Deploy apps that use Project Reunion](deploy-apps-that-use-project-reunion.md) \ No newline at end of file diff --git a/hub/apps/project-reunion/remove-project-reunion-versions.md b/hub/apps/project-reunion/remove-project-reunion-versions.md new file mode 100644 index 0000000000..11af774132 --- /dev/null +++ b/hub/apps/project-reunion/remove-project-reunion-versions.md @@ -0,0 +1,54 @@ +--- +title: Remove outdated Project Reunion runtime versions from your development computer +description: This article provides instructions for removing older versions of Project Reunion VSIX and runtime packages +ms.topic: article +ms.date: 05/21/2021 +keywords: windows win32, windows app development, project reunion +ms.author: zafaraj +author: zaryaf +ms.localizationpriority: medium +--- + +# Remove outdated Project Reunion runtime versions from your development computer + +As you install updated versions of the Project Reunion runtime over time, you may want to remove outdated versions from your development computer. In general, you only need the Project Reunion runtime and extension that you have chosen to reference and require in your application. Unless your application has specific reasons for earlier extensions or runtimes, you may safely remove older versions. + +The Project Reunion runtime includes the [Framework](deployment-architecture.md#framework-packages-for-packaged-and-unpackaged-apps), [Main](deployment-architecture.md#main-package) and [Dynamic Dependency Lifetime Manager (DDLM)](deployment-architecture.md#dynamic-dependency-lifetime-manager-ddlm) package. All of these packages can be uninstalled by using **PowerShell** commands. The Main package and DDLM package can alternatively be uninstalled in **Settings**. + +> [!IMPORTANT] +> We recommend that you do not remove Project Reunion runtime packages from end-user's machines after deployment. Doing so will break other applications that are taking a dependency on those packages. + +## Remove Project Reunion runtime components using PowerShell + +First, run the `get-appxpackage` command to list all versions of the Project Reunion runtime packages that are installed on your computer (including the Framework, Main, and DDLM packages). The list includes details about each runtime package, including the **PackageFullName** value. For an example of the output of this command, see [Check for installed versions of the Project Reunion runtime](check-project-reunion-versions.md). + +```Powershell +get-appxpackage *reunion* +``` + +Next, run the `remove-appxpackage` command to remove specific versions of the Project Reunion runtime packages from your development computer. For each package, specify the **PackageFullName** value of the runtime packages you want to remove, as provided by the preceding step. The following example removes the Framework, Main, and DDLM package, respectively. Make sure you specify the correct **PackageFullName** values for the packages on your computer. + +```Powershell +remove-appxpackage -Package Microsoft.ProjectReunion.0.8-preview_8000.144.525.0_x86__8wekyb3d8bbwe +remove-appxpackage -Package Microsoft.ProjectReunion.Main.0.8-preview_8000.144.525.0_x64__8wekyb3d8bbwe +remove-appxpackage -Package Microsoft.ProjectReunion.DDLM.8000.144.525.0-x8-p_8000.144.525.0_x86__8wekyb3d8bbwe +``` + +## Remove Main and DDLM packages in Settings + +To remove [Main](deployment-architecture.md#main-package) and [Dynamic Dependency Lifetime Manager (DDLM)](deployment-architecture.md#dynamic-dependency-lifetime-manager-ddlm) packages, you can alternatively use the **Apps & features** page in **Settings**. + +> [!NOTE] +> The Project Reunion Framework package will not show up in **Apps & features**, and will need to be uninstalled using the **PowerShell** commands described earlier in this article. + +On the **Apps & features** page, search for **reunion** to filter and show installed versions of Project Reunion packages. Select any versions you want to remove from your computer and click **Uninstall**. + +![Screenshot of Apps & Features page in Settings to remove Project Reunion packages](images/remove-reunion-packages-versions.png) + +## Related topics + +- [Deploy unpackaged apps](deploy-unpackaged-apps.md) +- [Runtime architecture and deployment scenarios](deployment-architecture.md) +- [Check for installed versions of the Project Reunion runtime](check-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) \ No newline at end of file diff --git a/hub/apps/project-reunion/set-up-your-development-environment.md b/hub/apps/project-reunion/set-up-your-development-environment.md new file mode 100644 index 0000000000..5f76c79da6 --- /dev/null +++ b/hub/apps/project-reunion/set-up-your-development-environment.md @@ -0,0 +1,92 @@ +--- +title: Set up your development environment +description: This article provides instructions for installing the Project Reunion extension for Visual Studio 2019 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 +--- + +# Set up your development environment + +This article provides instructions for installing and setting up the Project Reunion extension for Visual Studio 2019 on your development computer. Before you install and use Project Reunion, see the information about [release channels](release-channels.md). + +## 1. Verify that you meet OS version requirements + +Project Reunion is currently supported on Windows 10, version 1809 (build 17763), or later. + +## 2. Install Visual Studio + +Project Reunion requires Visual Studio 2019 version 16.9 or higher. + +> [!div class="button"] +> [Download Visual Studio 2019](https://visualstudio.microsoft.com/vs/) + +If you want to access the full suite of interactive and debugging features with Project Reunion, install the latest Visual Studio 2019 version 16.10 Preview. + +> [!div class="button"] +> [Download Visual Studio Preview](https://visualstudio.microsoft.com/vs/preview/) + +If you already have Visual Studio installed, you can check your version: + +1. Open Visual Studio. +2. Select **Help** > **About Microsoft Visual Studio**. +3. Read the version number from the **About** dialog. + +### Required workloads and components + +Project Reunion requires that the following workloads and components are installed with Visual Studio. These workloads and components are all selected by default. + +- On the **Workloads** tab of the installation dialog, these workloads are required: + - **Universal Windows Platform development** + - **Desktop development with C++** + - **.NET Desktop Development** + +- On the **Individual components** tab of the installation dialog, **Windows 10 SDK (10.0.19041.0)** is required in the **SDKs, libraries, and frameworks** section. + +- In the **Installation details** pane of the installation dialog, **C++ (v142) Universal Windows Platform tools** is required in the **Universal Windows Platform development** section. + +## 3. Enable NuGet Package source + +Make sure your system has a NuGet package source enabled for the official NuGet service index at `https://api.nuget.org/v3/index.json`. + + 1. In Visual Studio, select **Tools** -> **NuGet Package Manager** -> **Package Manager Settings** to open the **Options** dialog. + 2. In the left pane of the **Options** dialog, select the **Package Sources** tab, and make sure there is a package source for **nuget.org** that points to `https://api.nuget.org/v3/index.json` as the source URL. For more information, see [Common NuGet configurations](/nuget/consume-packages/configuring-nuget-behavior). + +## 4. Install the Project Reunion Extension for Visual Studio + +There are two versions of the Project Reunion extension available you can choose from: the stable channel and preview channel. + +> [!NOTE] +> If you previously installed the [WinUI 3 Preview extension for Visual Studio](https://marketplace.visualstudio.com/items?itemName=Microsoft-WinUI.WinUIProjectTemplates), uninstall the extension. For more information about how to uninstall an extension, see [Manage extensions for Visual Studio](/visualstudio/ide/finding-and-using-visual-studio-extensions). + +### Install the stable release + +To develop desktop (C#/.NET 5 or C++/WinRT) apps that can be used in production environments, install the latest extension from the [stable release channel](stable-channel.md). Choose one of these options to install: + +- In Visual Studio 2019, click **Extensions** > **Manage Extensions**, search for **Project Reunion**, and install the latest extension. +- Alternatively, you can download and install the extension directly from Visual Studio Marketplace. + + > [!div class="button"] + > [Download latest stable release](https://aka.ms/projectreunion/vsixdownload) + +![Screenshot of Project Reunion extension being installed](images/reunion-extension-install.png) + +### Install the preview release + +To develop desktop (C#/.NET 5 or C++/WinRT) apps or UWP apps that use the latest experimental Reunion features, install the latest extension from the [preview release channel](preview-channel.md). This version of Project Reunion cannot be used by apps in production environments. Choose one of these options to install: + +- In Visual Studio 2019, click **Extensions** > **Manage Extensions**, search for **Project Reunion (Preview)**, and install the latest extension. +- Alternatively, you can download and install the extension directly from Visual Studio Marketplace. + + > [!div class="button"] + > [Download latest preview release](https://aka.ms/projectreunion/previewdownload) + +## Related topics + +- [Build desktop Windows apps with Project Reunion](index.md) +- [Release channels and release notes](release-channels.md) +- [Get started developing apps with Project Reunion](get-started-with-project-reunion.md) +- [Deploy apps that use Project Reunion](deploy-apps-that-use-project-reunion.md) \ No newline at end of file diff --git a/hub/apps/project-reunion/stable-channel.md b/hub/apps/project-reunion/stable-channel.md new file mode 100644 index 0000000000..b8d6334276 --- /dev/null +++ b/hub/apps/project-reunion/stable-channel.md @@ -0,0 +1,45 @@ +--- +title: Stable release channel for Project Reunion +description: Provides information about the stable release channel for Project Reunion. +ms.topic: article +ms.date: 05/21/2021 +keywords: windows win32, windows app development, project reunion +ms.author: zafaraj +author: zaryaf +ms.localizationpriority: medium +--- + +# Stable release channel for Project Reunion + +The stable channel provides releases of Project Reunion that are supported for use by apps in production environments. Apps that use the release channel of Project Reunion can also be published to the Microsoft Store. + +The latest release of the stable channel is Project Reunion [version 0.5.7](https://github.com/microsoft/ProjectReunion/discussions/820). + +> [!div class="button"] +> [Download the latest stable release](https://aka.ms/projectreunion/vsixdownload) + +## Features in the latest stable release + +The latest stable channel release includes the following sets of APIs and components you can use in your apps. + +| Component | Description | +|---------|-------------| +| [Windows UI Library 3](../winui/winui3/index.md) | Windows UI Library (WinUI) 3 is the next generation of the Windows user experience (UX) platform for Windows apps. This release includes Visual Studio project templates to help get started [building apps with a WinUI-based user interface](..\winui\winui3\winui-project-templates-in-visual-studio.md), and a NuGet package that contains the WinUI libraries. | +| [Manage resources with MRT Core](mrtcore/mrtcore-overview.md) | MRT Core provides APIs to load and manage resources used by your app. MRT Core is a streamlined version of the modern [Windows Resource Management System](/windows/uwp/app-resources/resource-management-system). | +| [Render text with DWriteCore](dwritecore.md) | DWriteCore provides access to all current DirectWrite features for text rendering, including a device-independent text layout system, hardware-accelerated text, multi-format text, and wide language support. | + +## Release notes + +This section lists limitations and known issues for Project Reunion version 0.5.x. + +- **Desktop apps (C# .NET 5 or C++ desktop)**: This release cannot be used in unpackaged desktop apps (C# .NET 5 or C++ desktop). This release is supported for use only in MSIX-packaged desktop apps. +- **UWP apps**: This release is not supported for UWP apps that are used in production environments. To use Project Reunion in UWP apps, you must use a release from the [preview release channel](preview-channel.md). For more information about installing the preview extension, see [Set up your development environment](set-up-your-development-environment.md). +- **WinUI 3**: For a list of WinUI changes in this release, see the [WinUI 3 - Project Reunion 0.5 release notes](../winui/winui3/index.md). +- The [WinUI 3 developer tool limitations](..\winui\winui3\index.md#developer-tools) also apply to any project that uses this release. + +## Related topics + +- [Preview channel](preview-channel.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) +- [Deploy apps that use Project Reunion](deploy-apps-that-use-project-reunion.md) \ No newline at end of file diff --git a/hub/apps/project-reunion/tutorial-unpackaged-deployment.md b/hub/apps/project-reunion/tutorial-unpackaged-deployment.md new file mode 100644 index 0000000000..483832f783 --- /dev/null +++ b/hub/apps/project-reunion/tutorial-unpackaged-deployment.md @@ -0,0 +1,120 @@ +--- +title: Build and deploy an unpackaged app that uses Project Reunion +description: This article provides a walkthrough for building and deploying an unpackaged app that uses Project Reunion. +ms.topic: article +ms.date: 05/24/2021 +keywords: windows win32, windows app development, project reunion +ms.author: zafaraj +author: zaryaf +ms.localizationpriority: medium +--- + +# Tutorial: Build and deploy an unpackaged app that uses Project Reunion + +> [!IMPORTANT] +> [Unpackaged app deployment](deploy-unpackaged-apps.md) 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. + +This article provides a step-by-step tutorial for deploying a non-MSIX packaged app that uses Project Reunion. This tutorial demonstrates this scenario using a basic C++ Console app. + +Before completing this tutorial, we recommend that you review [Runtime architecture and deployment scenarios](deployment-architecture.md) to learn more about the Framework package dependency your app takes when it uses Reunion, and the additional components required to work in an unpackaged app. + +## Prerequisites + +- A supported version of Visual Studio 2019. For more information, see [Set up your development environment](set-up-your-development-environment.md). + > [!NOTE] + > Although we encourage you to install the Project Reunion extension for Visual Studio, you do not need to install the extension to perform this tutorial. In this tutorial, you will install the Project Reunion NuGet package directly in an existing project. +- Ensure all [dependencies for unpackaged apps](deployment-architecture.md#additional-requirements-for-unpackaged-apps) are installed. The simplest solution is to run the Project Reunion runtime installer: + + 1. Download [ReunionRuntimeInstaller.exe from GitHub](https://aka.ms/projectreunion/0.8preview). + 2. From a command prompt, run `ReunionRuntimeInstaller.exe` to install all the dependencies. + +## 1. Create a new C++ Console app in Visual Studio + +Create a new C++ **Console App** project. Name the project **DynamicDependenciesTest**. + +![Screenshot of creating a new C++ app in Visual Studio](images/tutorial-deploy-create-project.png) + +![Screenshot of naming a new C++ app in Visual Studio](images/tutorial-deploy-name-project.png) + +After you create the project, you should have a 'Hello World' C++ console app. + +## 2. Install the Project Reunion NuGet package + +Next, install the Project Reunion NuGet package to your Console project. + +1. In **Solution Explorer**, right-click the **References** node and choose **Manage Nuget Packages**. +2. Search for **Project Reunion**, and install the latest preview version of the **Microsoft.ProjectReunion** package. + +## 3. Initialize the Bootstrapper in your code + +You are now ready to use the [dynamic dependencies API](https://github.com/microsoft/ProjectReunion/blob/main/specs/dynamicdependencies/DynamicDependencies.md) to initialize the [Bootstrapper](deployment-architecture.md#bootstrapper) component in your app. + +1. Add the following include files to the top of your **DynamicDependenciesTest.cpp** file. + + ```cpp + #include + #include + ``` + +2. Add the following code to initialize the Bootstrapper at the top of your `main` method. This code defines what version of Project Reunion the app is dependent upon when initializing the Bootstrapper. + + ```cpp + const UINT32 majorMinorVersion{ 0x00000008 }; + PCWSTR versionTag{ L"preview" }; + const PACKAGE_VERSION minVersion{}; + HRESULT hr{ MddBootstrapInitialize(majorMinorVersion, versionTag, minVersion) }; + ``` + +3. Add error checking code and display the result. + + ```cpp + // Check the return code for errors. If there is an error, display the result. + if (FAILED(hr)) + { + wprintf(L"Error 0x%X in MddBootstrapInitialize(0x%08X, %s, %hu.%hu.%hu.%hu)\n", + hr, majorMinorVersion, versionTag, minVersion.Major, minVersion.Minor, minVersion.Build, minVersion.Revision); + return hr; + } + ``` + +4. Your final code should look like this. + + ```cpp + #include + #include + #include + + int main() + + { + // Take a dependency on Project Reunion preview + const UINT32 majorMinorVersion{ 0x00000008 }; + PCWSTR versionTag{ L"preview" }; + const PACKAGE_VERSION minVersion{}; + + HRESULT hr{ MddBootstrapInitialize(majorMinorVersion, versionTag, minVersion) }; + + // Check the return code. If there is a failure, display the result. + if (FAILED(hr)) + { + wprintf(L"Error 0x%X in MddBootstrapInitialize(0x%08X, %s, %hu.%hu.%hu.%hu)\n", + hr, majorMinorVersion, versionTag, minVersion.Major, minVersion.Minor, minVersion.Build, minVersion.Revision); + return hr; + } + + std::cout << "Hello World!\n"; + + // Release the DDLM and clean up. + MddBootstrapShutdown(); + } + ``` + +## 4. Run the app + +Press F5 to build and run your app. + +## Related topics + +- [Deploy unpackaged apps that use Project Reunion](deploy-unpackaged-apps.md) +- [Runtime architecture and deployment scenarios](deployment-architecture.md) +- [Get started with Project Reunion](get-started-with-project-reunion.md) diff --git a/hub/apps/project-reunion/update-existing-projects-to-the-latest-release.md b/hub/apps/project-reunion/update-existing-projects-to-the-latest-release.md index dbd097af0c..5ec81aa495 100644 --- a/hub/apps/project-reunion/update-existing-projects-to-the-latest-release.md +++ b/hub/apps/project-reunion/update-existing-projects-to-the-latest-release.md @@ -11,29 +11,34 @@ ms.localizationpriority: medium # Update existing projects to the latest release of Project Reunion -If you created a project with an earlier preview or release version of Project Reunion or WinUI 3, you can update the project to use the latest stable release (version 0.5.7). +If you created a project with an earlier preview or release version of Project Reunion or WinUI 3, you can update the project to use the latest stable release (version 0.5.7) or the latest preview release (version 0.8 preview). > [!NOTE] > These instructions may have issues due to the uniqueness of each app's individual scenario. Please carefully follow them and if you find issues, [file a bug on our GitHub repo](https://github.com/microsoft/microsoft-ui-xaml/issues/new/choose). ## Update from Project Reunion 0.5.0 or above -If you created a project using Project Reunion version 0.5.0 or above, you can follow these instructions to update your project to Project Reunion version 0.5.7 (the latest stable release). This version includes several important bug fixes. +If you created a project using Project Reunion version 0.5.0 or above, you can follow these instructions to update your project to Project Reunion version 0.5.7 (the latest stable release) or Project Reunion version 0.8 preview (the latest preview release). > [!NOTE] -> If you created a project using the Project Reunion 0.5 VSIX, you may be able to automatically update your project through the Visual Studio Extension Manager, without going through the manual steps below. In Visual Studio 2019, click on **Extensions** -> **Manage Extensions** and select **Updates** from the left menu bar. Select "Project Reunion" from the list and click **Update**. +> If you created a project using the Project Reunion 0.5 VSIX and want to update to a newer stable version, you may be able to automatically update your project through the Visual Studio Extension Manager, without going through the manual steps below. In Visual Studio 2019, click on **Extensions** -> **Manage Extensions** and select **Updates** from the left menu bar. Select "Project Reunion" from the list and click **Update**. -Before starting, make sure you have all the Project Reunion 0.5 prerequisites installed, including the latest Project Reunion VSIX and NuGet package. For more details, see the [installation instructions](get-started-with-project-reunion.md#set-up-your-development-environment). +> [!IMPORTANT] +> The following example shows how to update a project to use Project Reunion version 0.5.7. If you'd like to update your app to version 0.8 preview, replace the "0.5.7" version number with "0.8.0-preview". + +Before starting, make sure you have all the Project Reunion 0.5 prerequisites installed, including the latest Project Reunion VSIX and NuGet package. For more details, see the [installation instructions](set-up-your-development-environment.md). First, do the following: + - In the .wapproj file, if your **TargetPlatformMinVersion** is older than 10.0.17763.0, change it to 10.0.17763.0. Next, make these changes to your project: -1. In order to receive all of the fixes from the latest stable or preview release of Project Reunion in C# .NET 5 projects, you'll need to update your project file to explicitly set the .NET SDK to the latest version. For more information, see [.NET SDK references](index.md#net-sdk-references). -3. In Visual Studio, go to **Tools** -> **Nuget Package Manager** -> **Package Manager Console**. +1. To receive all of the fixes from the latest stable or preview release of Project Reunion in C# .NET 5 projects, you'll need to update your project file to explicitly set the .NET SDK to the latest version. For more information, see [.NET SDK references](release-channels.md#net-sdk-references). + +2. In Visual Studio, go to **Tools** -> **Nuget Package Manager** -> **Package Manager Console**. -4. Enter the following commands: +3. Enter the following commands: ```Console uninstall-package Microsoft.ProjectReunion -ProjectName {yourProject} @@ -42,7 +47,7 @@ Next, make these changes to your project: install-package Microsoft.ProjectReunion -Version 0.5.7 -ProjectName {yourProjectName} ``` -5. Make the following changes in your Application (package).wapproj: +4. Make the following changes in your Application (package).wapproj: 1. Add this section: @@ -54,20 +59,28 @@ Next, make these changes to your project: ``` - 2. Remove the following lines: + 2. Locate the following line: + + ```xml + net5.0-windows$(TargetPlatformVersion);$(AssetTargetFallback) + ``` + + Move this line and place it on a new line directly beneath the `` tag. + + 3. Remove this lines: ```xml $(MSBuildThisFileDirectory)build\ ``` - And: + And these lines: ```xml ``` - And this item group (if you're updating from a newer version than 0.5.0, replace 0.5.0 with your version number): + And this item group (if you're updating from a newer version than 0.5.0, you will see a later version number referenced in this item group): ```xml @@ -82,9 +95,12 @@ Next, make these changes to your project: ## Update from Project Reunion 0.5 Preview -If you created a project using Project Reunion 0.5 Preview, you can follow these instructions to update your project to Project Reunion version 0.5.7 (the latest stable release). +If you created a project using Project Reunion 0.5 Preview, you can follow these instructions to update your project to Project Reunion version 0.5.7 (the latest stable release) or Project Reunion version 0.8 preview (the latest preview release). + +> [!IMPORTANT] +> The following example shows how to update a project to use Project Reunion version 0.5.7. If you'd like to update your app to version 0.8 preview, replace the "0.5.7" version number with "0.8.0-preview". -Before starting, make sure you have all the Project Reunion 0.5 prerequisites installed, including the latest Project Reunion VSIX and NuGet package. For more details, see the [installation instructions](get-started-with-project-reunion.md#set-up-your-development-environment). +Before starting, make sure you have all the Project Reunion 0.5 prerequisites installed, including the latest Project Reunion VSIX and NuGet package. For more details, see the [installation instructions](set-up-your-development-environment.md). First, do the following: @@ -101,7 +117,8 @@ First, do the following: ``` Next, make these changes to your project: -1. In order to receive all of the fixes from the latest stable or preview release of Project Reunion in C# .NET 5 projects, you'll need to update your project file to explicitly set the .NET SDK to the latest version. For more information, see [.NET SDK references](index.md#net-sdk-references). + +1. To receive all of the fixes from the latest stable or preview release of Project Reunion in C# .NET 5 projects, you'll need to update your project file to explicitly set the .NET SDK to the latest version. For more information, see [.NET SDK references](release-channels.md#net-sdk-references). 2. In Visual Studio, go to **Tools** -> **Nuget Package Manager** -> **Package Manager Console**. 3. Enter the following commands: @@ -113,7 +130,7 @@ Next, make these changes to your project: install-package Microsoft.ProjectReunion -Version 0.5.7 -ProjectName {yourProjectName} ``` -4. Make the following changes in your Application (package).wapproj: +4. If you have a UWP app, your update process should be complete at this stage. If you have a desktop app, make the following changes in your Application (package).wapproj: 1. Add this section: @@ -125,13 +142,17 @@ Next, make these changes to your project: ``` - 2. Remove the following lines: + 2. Locate the `` tag, and add the following on a new line directly beneath that tag: + ```xml + net5.0-windows$(TargetPlatformVersion);$(AssetTargetFallback) + ``` + 3. Remove this line: ```xml $(MSBuildThisFileDirectory)build\ ``` - And + And these lines: ```xml @@ -153,9 +174,12 @@ Next, make these changes to your project: ## Update from WinUI 3 Preview 4 -If you created a project using WinUI 3 Preview 4, you can follow these instructions to update your project to Project Reunion version 0.5.7 (the latest stable release). +If you created a project using WinUI 3 Preview 4, you can follow these instructions to update your project to Project Reunion version 0.5.7 (the latest stable release) or Project Reunion version 0.8 preview (the latest preview release). + +> [!IMPORTANT] +> The following example shows how to update a project to use Project Reunion version 0.5.7. If you'd like to update your app to version 0.8 preview, replace the "0.5.7" version number with "0.8.0-preview". -Before starting, make sure you have all the Project Reunion 0.5 prerequisites installed, including the latest Project Reunion VSIX and NuGet package. For more details, see the [installation instructions](get-started-with-project-reunion.md#set-up-your-development-environment). +Before starting, make sure you have all the Project Reunion 0.5 prerequisites installed, including the latest Project Reunion VSIX and NuGet package. For more details, see the [installation instructions](set-up-your-development-environment.md). First, do the following: @@ -172,7 +196,8 @@ First, do the following: ``` Next, make these changes to your project: -1. In order to receive all of the fixes from the latest stable or preview release of Project Reunion in C# .NET 5 projects, you'll need to update your project file to explicitly set the .NET SDK to the latest version. For more information, see [.NET SDK references](index.md#net-sdk-references). + +1. To receive all of the fixes from the latest stable or preview release of Project Reunion in C# .NET 5 projects, you'll need to update your project file to explicitly set the .NET SDK to the latest version. For more information, see [.NET SDK references](release-channels.md#net-sdk-references). 2. In Visual Studio, go to **Tools** -> **Nuget Package Manager** -> **Package Manager Console**. 3. Enter the following commands: @@ -182,7 +207,7 @@ Next, make these changes to your project: install-package Microsoft.ProjectReunion -Version 0.5.7 -ProjectName {yourProjectName} ``` -4. Make the following changes in your Application (package).wapproj: +4. If you have a UWP app, your update process should be complete at this stage. If you have a desktop app, make the following changes in your Application (package).wapproj: 1. Add this section: @@ -204,4 +229,4 @@ Next, make these changes to your project: ``` -5. Delete the existing `Microsoft.WinUI.AppX.targets` file under the {YourProject}(package)/build/ folder of your project. \ No newline at end of file +5. Delete the existing `Microsoft.WinUI.AppX.targets` file under the {YourProject}(package)/build/ folder of your project. diff --git a/hub/apps/toc.yml b/hub/apps/toc.yml index ddb058de74..dd8fa72a31 100644 --- a/hub/apps/toc.yml +++ b/hub/apps/toc.yml @@ -88,30 +88,70 @@ href: desktop/modernize/modernize-wpf-tutorial-5.md - name: Grant identity to non-packaged desktop apps href: desktop/modernize/grant-identity-to-nonpackaged-apps.md - - name: Project Reunion 0.5 + - name: Project Reunion items: - name: "Overview" href: project-reunion/index.md - - name: "Get started with Project Reunion" - href: project-reunion/get-started-with-project-reunion.md - - name: "Update existing projects to the latest release of Project Reunion" - href: project-reunion/update-existing-projects-to-the-latest-release.md - - name: "Deploy apps that use Project Reunion" - href: project-reunion/deploy-apps-that-use-project-reunion.md - - name: "Manage resources with MRT Core" + - name: "Releases" + items: + - name: "Release channels and release notes" + href: project-reunion/release-channels.md + - name: "Stable release channel" + href: project-reunion/stable-channel.md + - name: "Preview release channel" + href: project-reunion/preview-channel.md + - name: "Get started" + items: + - name: "Set up your development environment" + href: project-reunion/set-up-your-development-environment.md + - name: "Get started developing apps" + href: project-reunion/get-started-with-project-reunion.md + - name: "Update existing projects to the latest release" + href: project-reunion/update-existing-projects-to-the-latest-release.md + - name: "Manage resources" href: project-reunion/mrtcore/mrtcore-overview.md - - name: "Render text with DWriteCore" + - name: "Render text" href: project-reunion/dwritecore.md + - name: Control app activation + items: + - name: App instancing + href: project-reunion/applifecycle/applifecycle-instancing.md + - name: Rich activation + href: project-reunion/applifecycle/applifecycle-rich-activation.md + - name: "Deploy apps" + items: + - name: "Overview" + href: project-reunion/deploy-apps-that-use-project-reunion.md + - name: "Runtime architecture and deployment scenarios" + href: project-reunion/deployment-architecture.md + - name: "Deploy packaged apps" + href: project-reunion/deploy-packaged-apps.md + - name: "Deploy unpackaged apps" + items: + - name: "Overview" + href: project-reunion/deploy-unpackaged-apps.md + - name: "Tutorial: Build and deploy an unpackaged app" + href: project-reunion/tutorial-unpackaged-deployment.md + - name: "Check for installed versions of the Project Reunion runtime" + href: project-reunion/check-project-reunion-versions.md + - name: "Remove outdated Project Reunion runtime versions" + href: project-reunion/remove-project-reunion-versions.md - name: Windows UI Library (WinUI) items: - name: "Overview" href: winui/index.md - name: "Comparison of WinUI 3 and WinUI 2" href: winui/winui3-winui2-comparison.md - - name: "Windows UI Library 3 - Project Reunion 0.5" + - name: "Windows UI Library 3" items: - - name: "Overview and release notes" - href: winui/winui3/index.md + - name: "Release notes" + items: + - name: "WinUI 3 - Project Reunion 0.8 Preview" + href: winui/winui3/release-notes/release-notes-08-preview.md + - name: "WinUI 3 - Project Reunion 0.5" + href: winui/winui3/index.md + - name: "WinUI 3 - Project Reunion 0.5 Preview" + href: winui/winui3/release-notes/winui3-project-reunion-0.5-preview.md - name: "Develop" items: - name: "WinUI project templates in Visual Studio" @@ -126,11 +166,6 @@ href: winui/winui3/xaml-templated-controls-cppwinrt-winui-3.md - name: "Templated XAML controls for WinUI 3 apps with C#" href: winui/winui3/xaml-templated-controls-csharp-winui-3.md - - name: "Release notes archive (WinUI 3)" - href: winui/winui3/release-notes/index.md - items: - - name: "Windows UI Library 3 - Project Reunion 0.5 Preview (March 2021)" - href: winui/winui3/release-notes/winui3-project-reunion-0.5-preview.md - name: "Windows UI 2.x Library" items: - name: "Overview" @@ -183,5 +218,5 @@ href: features-and-technologies.md - name: Latest doc updates href: whats-new/latest-doc-updates.md - - name: Docs related to Microsoft Build 2020 - href: whats-new/build2020-docs.md + - name: Docs related to Microsoft Build 2021 + href: whats-new/build2021-docs.md diff --git a/hub/apps/whats-new/build2020-docs.md b/hub/apps/whats-new/build2020-docs.md deleted file mode 100644 index 668a70cdcb..0000000000 --- a/hub/apps/whats-new/build2020-docs.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -description: Links to the Windows Developer Docs mentioned during the Build 2020 online event. -title: Documentation related to topics discussed during Build -ms.topic: article -ms.date: 05/11/2020 -ms.localizationpriority: medium -ms.author: jken -author: grantmestrength ---- - - - -# Microsoft Build - the Windows Documentation - -![Build hero image](../images/build-banner.jpeg) - -We've gathered together links to documentation that supports the talks given as part of [Microsoft Build 2020](https://mybuild.microsoft.com). We will update this page as the event continues, so check back to see what's new! - -## Project Reunion - -* [Project Reunion](https://blogs.windows.com/windowsdeveloper/2020/05/19/developing-for-all-1-billion-windows-10-devices-and-beyond/) is the future of Windows development. - -## Windows Terminal - -* [Install and set up Windows Terminal](/windows/terminal/get-started) -* [Set up custom key bindings](/windows/terminal/customize-settings/key-bindings) -* [Gallery of customized terminals](/windows/terminal/custom-terminal-gallery/retro-command-prompt) - -## Windows Subsystem for Linux (WSL) - -* [What is WSL? (What is WSL 2?)](/windows/wsl/about) -* [Install WSL 2](/windows/wsl/install-win10) -* [Comparing WSL2 and WSL 1](/windows/wsl/compare-versions) - -## Windows Package Manager - -* [Windows Package Manager](../../package-manager/index.md) -* [Submit your packages](../../package-manager/package/index.md) -* [Use the winget tool](../../package-manager/winget/index.md) - -## WinUI - -* [Overview of WinUI](../winui/index.md) -* [WinUI 3.0 Preview](../winui/winui3/index.md) -* [WinUI 3.0 for desktop apps](../winui/winui3/get-started-winui3-for-desktop.md) - -## Developing for Android on Windows - -* [Android development overview](../../android/overview.md) -* [Get started](../../android/native-android.md) -* [Test on an Android device](../../android/emulator.md) - -## Dual-screen device development - -* [Surface Duo introduction](https://www.microsoft.com/surface/devices/surface-duo) -* [Get the Surface Duo tools](/dual-screen/android/get-duo-sdk?tabs=windows) -* [Use the Surface Duo emulator](/dual-screen/android/use-emulator?tabs=java%252cwindows) diff --git a/hub/apps/whats-new/build2021-docs.md b/hub/apps/whats-new/build2021-docs.md new file mode 100644 index 0000000000..abb31997a5 --- /dev/null +++ b/hub/apps/whats-new/build2021-docs.md @@ -0,0 +1,86 @@ +--- +description: Links to the Windows Developer Docs mentioned during the Build 2021 online event. +title: Documentation related to topics discussed during Build +ms.topic: article +ms.date: 05/27/2021 +ms.localizationpriority: medium +ms.author: jken +author: grantmestrength +--- + + + +# Microsoft Build - the Windows Documentation + +![Build hero image](../images/build-banner.jpeg) + +We've gathered together links to documentation that supports the talks given as part of [Microsoft Build 2021](https://mybuild.microsoft.com). We will update this page as the event continues, so check back to see what's new! + +## Project Reunion + +- [Build desktop Windows apps with Project Reunion](/windows/apps/project-reunion/) +- [Get started with Project Reunion](/windows/apps/project-reunion/get-started-with-project-reunion) +- [Update existing projects to the latest release of Project Reunion](/windows/apps/project-reunion/update-existing-projects-to-the-latest-release) + + +## WinUI + +- [WinUI Introduction](/windows/apps/winui/) +- [Comparison of WinUI 3 and WinUI 2](/windows/apps/winui/winui3-winui2-comparison) +- [WinUI 3.0 - Project Reunion 0.5](/windows/apps/winui/winui3/) +- [Windows UI Library 2.x](/windows/apps/winui/winui2/) + + +## Windows Template Studio + +- [Windows Template Studio](/windows/uwp/design/windows-template-studio/) +- [Windows Template Studio on GitHub](https://github.com/microsoft/windowsTemplateStudio) + +## Performance + +- [Performance](/windows/uwp/debug-test-perf/performance-and-xaml-ui) + +## React Native + +- [React overview](/windows/dev-environment/javascript/react-overview) +- [Install React direct on Windows](/windows/dev-environment/javascript/react-on-windows) + +## Microsoft Store + +- [Publish Windows apps and games](/windows/uwp/publish/) + +## Windows Package Manager + +- [Windows Package Manager (preview)](/windows/package-manager/) +- [Using the winget tool to install and manage applications](/windows/package-manager/winget/) + +## Machine Learning + +- [Windows Machine Learning](/windows/ai/windows-ml/) + +## MSIX + +- [MSIX Documentation](/windows/msix/) +- [What is MSIX?](/windows/msix/overview) + +## Azure Communication Services + +- [Azure Communication Services](https://azure.microsoft.com/services/communication-services/) + +## Windows on ARM + +- [Snapdragon Developer Kit](https://developer.qualcomm.com/hardware/windows-on-snapdragon/snapdragon-developer-kit) +- [Windows on ARM](/windows/arm/) + +## Surface Duo + +- [Surface Duo Blog](https://devblogs.microsoft.com/surface-duo/surface-duo-at-microsoft-build-2021/) + + +## Windows AI Platform + +- [Windows AI Platform blog](https://devblogs.microsoft.com/windowsai/) + +## Windows Terminal + +- [Terminal Preview v1.9 announced](https://devblogs.microsoft.com/commandline/windows-terminal-preview-1-9-release) diff --git a/hub/apps/winui/reference/iwindownative-windowhandle.md b/hub/apps/winui/reference/iwindownative-windowhandle.md index 2e1fb0d0e2..48362cf9ed 100644 --- a/hub/apps/winui/reference/iwindownative-windowhandle.md +++ b/hub/apps/winui/reference/iwindownative-windowhandle.md @@ -51,7 +51,7 @@ If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error Before trying the following example, review the following topics: -- To use the WinUI 3 for desktop project templates, configure your development computer and [set up your development environment](../../project-reunion/get-started-with-project-reunion.md#set-up-your-development-environment). +- To use the WinUI 3 for desktop project templates, configure your development computer and [set up your development environment](../../project-reunion/set-up-your-development-environment.md). - Confirm your dev environment is functioning as expected by creating and running an initial template app as described in [Get started with WinUI 3 for desktop apps](../winui3/get-started-winui3-for-desktop.md). ### Customized window icon diff --git a/hub/apps/winui/winui3/get-started-winui3-for-desktop.md b/hub/apps/winui/winui3/get-started-winui3-for-desktop.md index 5fd713113e..193f4bea83 100644 --- a/hub/apps/winui/winui3/get-started-winui3-for-desktop.md +++ b/hub/apps/winui/winui3/get-started-winui3-for-desktop.md @@ -18,7 +18,7 @@ WinUI 3 ships as a part of the Project Reunion package. For more on Project Reun ## Prerequisites -To use the WinUI 3 for desktop project templates described in this article, configure your development computer and install the Project Reunion 0.5 Visual Studio extension. For details, see [Set up your development environment](../../project-reunion/get-started-with-project-reunion.md#set-up-your-development-environment). +To use the WinUI 3 for desktop project templates described in this article, configure your development computer and install the Project Reunion 0.5 Visual Studio extension. For details, see [Set up your development environment](../../project-reunion/set-up-your-development-environment.md). ## Create a WinUI 3 desktop app with C# and .NET 5 @@ -46,7 +46,7 @@ To use the WinUI 3 for desktop project templates described in this article, conf ![Screenshot of Visual Studio showing the Solution Explorer pane and the contents of the Package app x manifest file.](images/WinUI-csharp-packageproject.png) -7. In order to receive all of the fixes from the latest stable release of Project Reunion 0.5, you'll need to update your app's project file to explicitly set your .NET SDK to the latest version. For more information, see [.NET SDK references](../../project-reunion/index.md#net-sdk-references). +7. In order to receive all of the fixes from the latest stable release of Project Reunion 0.5, you'll need to update your app's project file to explicitly set your .NET SDK to the latest version. For more information, see [.NET SDK references](../../project-reunion/release-channels.md#net-sdk-references). 8. To add a new item to your app project, right-click the **_Project name_ (Desktop)** project node in **Solution Explorer** and select **Add** -> **New Item**. In the **Add New Item** dialog box, select the **WinUI** tab, choose the item you want to add, and then click **Add**. For more details about the available items, see [Item templates for WinUI 3](winui-project-templates-in-visual-studio.md#item-templates-for-winui-3). diff --git a/hub/apps/winui/winui3/get-started-winui3-for-uwp.md b/hub/apps/winui/winui3/get-started-winui3-for-uwp.md index 76b32271d1..d6f37b6f68 100644 --- a/hub/apps/winui/winui3/get-started-winui3-for-uwp.md +++ b/hub/apps/winui/winui3/get-started-winui3-for-uwp.md @@ -10,19 +10,19 @@ ms.custom: 19H1 # Get started with WinUI 3 for UWP apps (Preview) -You can create a Universal Windows Platform (UWP) app with a user interface built entirely on WinUI 3 using project templates included with [WinUI 3 - Project Reunion 0.5 Preview](release-notes/winui3-project-reunion-0.5-preview.md). When you create apps using these project templates, the entire user interface of your application is implemented using windows, controls, and styles provided by WinUI 3. For a complete list of supported WinUI 3 project templates, see [Project templates for WinUI 3](winui-project-templates-in-visual-studio.md#project-templates-for-winui-3). +You can create a Universal Windows Platform (UWP) app with a user interface built entirely on WinUI 3 using project templates included with [WinUI 3 - Project Reunion 0.8 Preview](release-notes/release-notes-08-preview.md). When you create apps using these project templates, the entire user interface of your application is implemented using windows, controls, and styles provided by WinUI 3. For a complete list of supported WinUI 3 project templates, see [Project templates for WinUI 3](winui-project-templates-in-visual-studio.md#project-templates-for-winui-3). -WinUI 3 ships as a part of the Project Reunion package. For more information about Project Reunion, see [Build desktop Windows apps with Project Reunion 0.5](../../project-reunion/index.md). +WinUI 3 ships as a part of the Project Reunion package. For more information about Project Reunion, see [Build desktop Windows apps with Project Reunion](../../project-reunion/index.md). > [!NOTE] > WinUI 3 support for building UWP apps is currently in preview, and is not production-ready. You will not be able to ship WinUI 3 UWP apps to the Microsoft Store. ## Prerequisites -To use the WinUI 3 for UWP Preview project templates, configure your development computer by following the directions found in the [Set up your development environment](../../project-reunion/get-started-with-project-reunion.md#set-up-your-development-environment) guide for Project Reunion. +To use the WinUI 3 for UWP Preview project templates, configure your development computer by following the directions found in the [Set up your development environment](../../project-reunion/set-up-your-development-environment.md) guide for Project Reunion. > [!NOTE] -> You cannot create WinUI 3 UWP apps with the Project Reunion 0.5 VSIX. You must download the [Project Reunion 0.5 **Preview** VSIX](https://aka.ms/projectreunion/previewdownload) to get the UWP Preview project templates and build UWP apps with WinUI 3. +> You must download the [Project Reunion (**Preview**) VSIX](https://aka.ms/projectreunion/previewdownload) to get the UWP Preview project templates and build UWP apps with WinUI 3. ## Create a "WinUI 3 app in UWP" for C# @@ -37,7 +37,7 @@ To use the WinUI 3 for UWP Preview project templates, configure your development 2. In the **Create a new project** dialog, select **C#**, **Windows**, and **WinUI**, respectively from the project drop-down filters. -3. Select the **Blank App (WinUI in UWP) - Preview** project type and click **Next**. +3. Select the **[Experimental] Blank App (WinUI in UWP)** project type and click **Next**. :::image type="content" source="images/WinUI-and-UWP/vs2019-create-new-project-dialog.png" alt-text="Visual Studio 2019 - Create a new project dialog"::: @@ -45,7 +45,7 @@ To use the WinUI 3 for UWP Preview project templates, configure your development :::image type="content" source="images/WinUI-and-UWP/vs2019-configure-new-project-dialog.png" alt-text="Screenshot of the Configure your new project dialog box with the Location text box and the Create option highlighted."::: -5. In the following dialog box, set the **Target version** to Windows 10, version 1903 (build 18362) and **Minimum version** to Windows 10, version 1809 (build 17763) and then click **OK**. +5. In the following dialog box, set the **Target version** to Windows 10, version 2004 (build 19041) and **Minimum version** to Windows 10, version 1809 (build 17763) and then click **OK**. :::image type="content" source="images/WinUI-min-target-version.png" alt-text="Target and Min Version dialog"::: diff --git a/hub/apps/winui/winui3/images/WinUI-and-UWP/vs2019-add-new-item-dialog.png b/hub/apps/winui/winui3/images/WinUI-and-UWP/vs2019-add-new-item-dialog.png index 2faf7a0745..c99ebb97de 100644 Binary files a/hub/apps/winui/winui3/images/WinUI-and-UWP/vs2019-add-new-item-dialog.png and b/hub/apps/winui/winui3/images/WinUI-and-UWP/vs2019-add-new-item-dialog.png differ diff --git a/hub/apps/winui/winui3/images/WinUI-and-UWP/vs2019-configure-new-project-dialog.png b/hub/apps/winui/winui3/images/WinUI-and-UWP/vs2019-configure-new-project-dialog.png index 5fa3c0ac85..5f0dd4fbe2 100644 Binary files a/hub/apps/winui/winui3/images/WinUI-and-UWP/vs2019-configure-new-project-dialog.png and b/hub/apps/winui/winui3/images/WinUI-and-UWP/vs2019-configure-new-project-dialog.png differ diff --git a/hub/apps/winui/winui3/images/WinUI-and-UWP/vs2019-create-new-project-dialog.png b/hub/apps/winui/winui3/images/WinUI-and-UWP/vs2019-create-new-project-dialog.png index 71c0ef39fb..30d198ec5d 100644 Binary files a/hub/apps/winui/winui3/images/WinUI-and-UWP/vs2019-create-new-project-dialog.png and b/hub/apps/winui/winui3/images/WinUI-and-UWP/vs2019-create-new-project-dialog.png differ diff --git a/hub/apps/winui/winui3/images/WinUI-min-target-version.png b/hub/apps/winui/winui3/images/WinUI-min-target-version.png index 7bdc3abd41..e468cd07f8 100644 Binary files a/hub/apps/winui/winui3/images/WinUI-min-target-version.png and b/hub/apps/winui/winui3/images/WinUI-min-target-version.png differ diff --git a/hub/apps/winui/winui3/index.md b/hub/apps/winui/winui3/index.md index 8730ff7aaa..e265f7965e 100644 --- a/hub/apps/winui/winui3/index.md +++ b/hub/apps/winui/winui3/index.md @@ -5,7 +5,7 @@ ms.date: 03/19/2021 ms.topic: article --- -# Windows UI Library 3 - Project Reunion 0.5 (March 2021) +# Overview and release notes: Windows UI Library 3 - Project Reunion 0.5 (March 2021) Windows UI Library (WinUI) 3 is a native user experience (UX) framework for building modern Windows apps. It ships independently from the Windows operating system as a part of [Project Reunion](../../project-reunion/index.md). The Project Reunion 0.5 release provides [Visual Studio project templates](https://aka.ms/projectreunion/vsixdownload) to help you start building apps with a WinUI 3-based user interface. @@ -16,16 +16,13 @@ Windows UI Library (WinUI) 3 is a native user experience (UX) framework for buil This new version of WinUI 3 is available as part of Project Reunion 0.5. To install, see: -**[Installation instructions for Project Reunion 0.5](../../project-reunion/get-started-with-project-reunion.md#set-up-your-development-environment)** +**[Installation instructions for Project Reunion 0.5](../../project-reunion/set-up-your-development-environment.md)** Now that WinUI ships as a part of Project Reunion, you'll download the Project Reunion Visual Studio Extension (VSIX) to get started, which includes a set of developer tools and components. For more on the Project Reunion package, see [Deploy apps that use Project Reunion](../../project-reunion/deploy-apps-that-use-project-reunion.md). The Project Reunion VSIX includes [WinUI Project Templates](winui-project-templates-in-visual-studio.md) that you'll use to build your WinUI 3 app. > [!NOTE] > To see WinUI 3 controls and features in action, you can clone and build the WinUI 3 version of the [XAML Controls Gallery](#winui-3-controls-gallery) from GitHub. -> [!NOTE] -> To use WinUI 3 tooling such as Live Visual Tree, Hot Reload, and Live Property Explorer, you must enable WinUI 3 tooling with Visual Studio Preview Features as described in the [instructions here](https://github.com/microsoft/microsoft-ui-xaml/issues/4140). - Once you've set up your development environment, see [WinUI 3 project templates in Visual Studio](winui-project-templates-in-visual-studio.md) to familiarize yourself with the available Visual Studio Project and Item templates. For more information about getting started with building a WinUI 3 app, see the following articles: @@ -55,7 +52,7 @@ The table below shows the compatibility of Visual Studio 2019 versions with WinU |---|---| | 16.8 | No | | 16.9 | Yes, but with no Hot Reload, Live Visual Tree, or Live Property Explorer | -| 16.10 Previews | Yes, with all WinUI 3 tooling (in preview - see [Known issues](#known-issues) for a limitation with VS 2019 16.10 Preview 2) | +| 16.10 Previews | Yes, with all WinUI 3 tooling (in preview) | ## Update your existing WinUI 3 app @@ -95,10 +92,10 @@ This release provides the stability and support to make WinUI 3 suitable for pro ### Preview features -As this is a stable release, preview features have been removed from this version of WinUI 3. You can still access these features by using the current [preview version of WinUI 3](release-notes/winui3-project-reunion-0.5-preview.md). Please note the following key features are still in preview, and work to stabilize them is ongoing: +As this is a stable release, preview features have been removed from this version of WinUI 3. You can still access these features by using the current [preview version of WinUI 3](release-notes/release-notes-08-preview.md). Please note the following key features are still in preview, and work to stabilize them is ongoing: - UWP support - - This means you cannot build or run a UWP app using the WinUI 3 - Project Reunion 0.5 VSIX. You'll need to use the [WinUI 3 - Project Reunion 0.5 Preview VSIX](https://aka.ms/projectreunion/previewdownload), and follow the rest of the instructions for setting up your development environment in [Get started with Project Reunion](../../project-reunion/get-started-with-project-reunion.md). See [Windows UI Library 3 - Project Reunion 0.5 Preview (March 2021) release notes](release-notes/winui3-project-reunion-0.5-preview.md) for more information. + - This means you cannot build or run a UWP app using the WinUI 3 - Project Reunion 0.5 VSIX. You'll need to use the [WinUI 3 - Project Reunion Preview VSIX](https://aka.ms/projectreunion/previewdownload), and follow the rest of the instructions for setting up your development environment in [Get started with Project Reunion](../../project-reunion/get-started-with-project-reunion.md). See [Overview and release notes: Windows UI Library 3 - Project Reunion 0.8 Preview](release-notes/release-notes-08-preview.md) for more information. - Multi-window support in desktop apps @@ -143,6 +140,7 @@ WinUI 3 - Project Reunion 0.5 is compatible with PCs running the Windows 10 Octo - MediaElement and MediaPlayerElement - MapControl - SwapChainPanel does not support transparency +- AcrylicBrush and other effects using a CompositionBackdropBrush can’t sample from a SwapChainPanel or WebView2. - Global Reveal uses fallback behavior, a solid brush - XAML Islands is not supported in this release - Using WinUI 3 directly in an existing non-WinUI desktop app has the following limitation: The currently available path for migrating an existing app is to add a **new** WinUI 3 project to your solution, and adjust or refactor your logic as needed. @@ -167,7 +165,7 @@ For more information on affected APIs as well as workarounds and replacements fo - Previously, to get a CompositionCapabilities instance you would call [CompositionCapabilites.GetForCurrentView()](/uwp/api/windows.ui.composition.compositioncapabilities.getforcurrentview). However, the capabilities returned from this call were *not* dependent on the view. To address and reflect this, we've deleted the GetForCurrentView() static in this release, so now you can create a [CompositionCapabilties](/uwp/api/windows.ui.composition.compositioncapabilities) object directly. -- You may recieve a build error due to mismatched versions of the .NET SDK and the winrt.runtime.dll. As a workaround, you can try the following: +- You may receive a build error due to mismatched versions of the .NET SDK and the winrt.runtime.dll. As a workaround, you can try the following: Explicitly set your .NET SDK to the correct version. To determine the correct version for your app, locate the `` tag in your project file. Using the Windows SDK build number that your app is targeting in the `` tag (such as 18362 or 19041), add the following item to your project file, then save your project: @@ -180,7 +178,7 @@ For more information on affected APIs as well as workarounds and replacements fo Note this workaround is required for .NET SDK 5.0.203 and earlier, but will not be required for .NET SDK 5.0.204 or 5.0.300. -- When using Visual Studio 2019 16.10 Preview 2, Live Visual Tree may cause a crash. This will be fixed in the upcoming VS 2019 16.10 Preview 3 release. In the meantime, you can revert to VS 2019 16.10 Preview 1, which does not have this issue, by downloading it directly [from this link](https://aka.ms/vs/16/pre/629027471_513181835/vs_Enterprise.exe). +- When using Visual Studio 2019 16.10 Preview 2, Live Visual Tree may cause a crash. To avoid this, update to the latest [Visual Studio 2019 16.10 Preview](https://visualstudio.microsoft.com/vs/preview/). ## WinUI 3 Controls Gallery diff --git a/hub/apps/winui/winui3/release-notes/release-notes-08-preview.md b/hub/apps/winui/winui3/release-notes/release-notes-08-preview.md new file mode 100644 index 0000000000..c4622fdfc6 --- /dev/null +++ b/hub/apps/winui/winui3/release-notes/release-notes-08-preview.md @@ -0,0 +1,266 @@ +--- +title: WinUI 3 Project Reunion 0.8 Preview (April 2021) +description: Overview of WinUI 3 Project Reunion 0.8 Preview. +ms.date: 05/25/2021 +ms.topic: article +--- + +# Overview and release notes: Windows UI Library 3 - Project Reunion 0.8 Preview (May 2021) + +Windows UI Library (WinUI) 3 is a native user experience (UX) framework for building modern Windows apps. It ships independently from the Windows operating system as a part of [Project Reunion](../../../project-reunion/index.md). The Project Reunion 0.8 Preview release provides [Visual Studio project templates](../winui-project-templates-in-visual-studio.md) to help you start building apps with a WinUI 3-based user interface. + +**WinUI 3 - Project Reunion 0.8 Preview** is a pre-release version of WinUI 3 that includes bug fixes, general improvements, and experimental features - some of which will be stabilized for the Project Reunion 0.8 stable release in June 2021. + +> [!Important] +> This preview release is intended for early evaluation and to gather feedback from the developer community. It should **NOT** be used for production apps. +> +> If you're looking to ship a production app using Project Reunion and WinUI 3, see [Overview and release notes: WinUI 3 - Project Reunion 0.5](../index.md). +> +> Please use the [WinUI GitHub repo](https://github.com/microsoft/microsoft-ui-xaml) to provide feedback and log suggestions and issues. + +## Install WinUI 3 - Project Reunion 0.8 Preview + +This version of WinUI 3 is available as part of the Project Reunion 0.8 Preview. To install, see: + +**[Installation instructions for Project Reunion 0.8 Preview](../../../project-reunion/set-up-your-development-environment.md)** + +Since WinUI ships as a part of Project Reunion, you'll download the Project Reunion Visual Studio Extension (VSIX) to get started, which includes a set of developer tools and components. For more on the Project Reunion package, see [Deploy apps that use Project Reunion](../../../project-reunion/deploy-apps-that-use-project-reunion.md). The Project Reunion VSIX includes [WinUI Project Templates](../winui-project-templates-in-visual-studio.md) that you'll use to build your WinUI 3 app. + +> [!NOTE] +> To see WinUI 3 controls and features in action, you can clone and build the [WinUI 3 Controls Gallery](#winui-3-controls-gallery) from GitHub, or download it from the [Microsoft Store](https://www.microsoft.com/en-us/p/winui-3-controls-gallery/9p3jfpwwdzrc). + +Once you've set up your development environment, see [WinUI 3 project templates in Visual Studio](../winui-project-templates-in-visual-studio.md) to familiarize yourself with the available Visual Studio Project and Item templates. + +For more information about getting started with building a WinUI 3 app, see the following articles: + +- [Get started with WinUI 3 for desktop apps](../get-started-winui3-for-desktop.md) +- [Build a basic WinUI 3 app for desktop](../desktop-build-basic-winui3-app.md) +- [Build a basic WinUI 3 app for UWP](../get-started-winui3-for-uwp.md) + +Aside from the [limitations and known issues](#limitations-and-known-issues), building an app using the WinUI projects is similar to building a UWP app with XAML and WinUI 2.x. Therefore, most of the [guidance documentation](/windows/uwp/design/) for UWP apps and the **Windows.UI** WinRT namespaces in the Windows SDK is applicable. + +WinUI 3 API reference documentation is available here: [WinUI 3 API Reference](/windows/winui/api) + +### WebView2 + +To use WebView2 with this WinUI 3 release, please download the Evergreen Bootstrapper or Evergreen Standalone Installer found on [this page](https://developer.microsoft.com/microsoft-edge/webview2/) if you don't already have the WebView2 Runtime installed. + +### Windows Community Toolkit + +If you're using the Windows Community Toolkit, [download the latest version](https://aka.ms/wct-winui3). + +### Visual Studio Support + +In order to take advantage of the latest tooling features added into WinUI 3 like Hot Reload, Live Visual Tree, and Live Property Explorer, you must use a preview version of Visual Studio 2019 16.10. Please note that Visual Studio preview releases are pre-release products, so you may run into bugs and limitations when using preview versions of Visual Studio to build WinUI 3 apps. + +The table below shows the compatibility of Visual Studio 2019 versions with WinUI 3 - Project Reunion 0.5. + +| VS Version | WinUI 3 - Project Reunion 0.5 | +|---|---| +| 16.8 | No | +| 16.9 | Yes, but with no Hot Reload, Live Visual Tree, or Live Property Explorer | +| 16.10 Previews | Yes, with all WinUI 3 tooling (in preview) | + +## Updating your existing WinUI 3 app + +If you created an app with an earlier preview or stable version of WinUI 3, you can update the project to use WinUI 3 - Project Reunion 0.8 Preview. For instructions, see [Update existing projects to the latest release of Project Reunion](../../../project-reunion/update-existing-projects-to-the-latest-release.md). + + +## Major changes introduced in this release +- Pivot control is now available to use in this release. +- Most of the critical bug fixes from the Project Reunion v0.5.5, v0.5.6, and v0.5.7 servicing releases are included in this release as well. For servicing fixes that didn't make it into this preview, see [Known Issues](#known-issues). + + +## List of bugs fixed in WinUI 3 - Project Reunion 0.8 Preview + +- x:Bind does not work in a custom MenuFlyoutItem (more generally, x:Bind in ControlTemplate doesn't work if the parent namescope also uses x:Bind) + - Thanks to @lhak for filing this [issue on GitHub](https://github.com/microsoft/microsoft-ui-xaml/issues/4179)! + +- Hide windowed popups when the top-level window (or island) moves + +- StandardUICommand page in WinUI 3 Controls Gallery not showing everything + +- Mouse right-click in TextBox crashes the application + - Thanks to @Herdubreid for filing this [issue on GitHub](https://github.com/microsoft/microsoft-ui-xaml/issues/4804)! + +- Context menu displayed at the wrong location for EditableComboBox + +- Changing RichTextBlock Selection with touch makes selection indicator go away + +- Microsoft C++ exception: winrt::hresult_error at memory location 0x... when NavigationView is being used + - Thanks to @LeftTwixWand for filing [this issue on GitHub](https://github.com/microsoft/microsoft-ui-xaml/issues/4806)! + +- WinUI 3 error message needs rewording: "Cannot resolve 'Windows.metadata'. Please install the Windows Software Development Kit. The Windows SDK is installed with Visual Studio." + +- VSM Setter quirk for raising exception has backwards logic + - Thanks to @HppZ for filiing this [issue on GitHub](https://github.com/microsoft/microsoft-ui-xaml/issues/1048)! + +- Move focus off the WebView2 (if necessary) when browser process crashes + +- ProgressBar doesn't show difference between Paused and Error option + - Thansk to @j0shuams for filing this [issue on GitHub](https://github.com/microsoft/microsoft-ui-xaml/issues/3694)! + +- PointerReplay constantly running + +- NavigationView causes crash in UWP, Reunion 0.5 Preview + - Thanks to @kalin-todorov for filing this [issue on GitHub](https://github.com/microsoft/microsoft-ui-xaml/issues/4499)! + +- AutoSuggestBox, ComboBox, and CommandBarFlyout aren't setting ShouldConstrainToRootBounds="false" on their popup + +- WinUI 3 - Project Reunion 0.5 generating C++ exceptions for a C# managed app + - Thanks to @Noemata for filing [this issue on GitHub](https://github.com/microsoft/microsoft-ui-xaml/issues/4510)! + +- WebView2 initial tab focus lost + +- WebView2 crashes when DPI changes after Close() + +- Change in Appearance of AppBarButton with Flyout on CommandBar in WinUI3 + - Thanks to @eleanorleffler for filing [this issue on GitHub](https://github.com/microsoft/microsoft-ui-xaml/issues/4197)! + + + +## Features and capabilities introduced in past WinUI 3 Previews + +The following features and capabilities were introduced in past WinUI 3 preview releases and continue to be supported in WinUI 3 - Project Reunion 0.8 Preview. + +> [!NOTE] +> Some of the following features will continue to be a part of WinUI 3 previews, but may not be a part of the next supported release. These features are marked as experimental and will throw a warning when used in an app. APIs that are a part of the WinUI 2.6 pre-release are also marked as experimental in this release. + +- Ability to create desktop apps with WinUI, including [.NET 5](https://github.com/dotnet/core/tree/master/release-notes/5.0) for Win32 apps +- Preview-level support for building UWP apps +- [RadialGradientBrush](/windows/uwp/design/style/brushes#radial-gradient-brushes) +- [TabView updates](/windows/uwp/design/controls-and-patterns/tab-view) +- Dark theme updates +- Improvements and updates to [WebView2](/microsoft-edge/hosting/webview2) + - Support for High DPI + - Support for window resizing and moving + - Updated to target more recent version of Edge + - No longer necessary to reference a WebView2-specific Nuget package +- SwapChainPanel +- MRT Core Support + - This makes apps faster and lighter on startup and provides quicker resource lookup. +- ARM64 Support +- Drag and drop inside and outside of apps +- RenderTargetBitmap (currently only XAML content - no SwapChainPanel content) +- Custom cursor support +- Off-thread input +- Improvements to our tooling/developer experience: + - Live Visual Tree, Hot Reload, Live Property Explorer and similar tools + - Intellisense for WinUI 3 +- Improvements required for open source migration +- Custom titlebar capabilities: new [Window.ExtendsContentIntoTitleBar](/windows/winui/api/microsoft.ui.xaml.window.extendscontentintotitlebar) and [Window.SetTitleBar](/windows/winui/api/microsoft.ui.xaml.window.settitlebar) APIs that allow developers to create custom title bars in desktop apps. +- VirtualSurfaceImageSource support +- In-app acrylic +- Multi-window support in desktop apps +- Input validation + +For more information on both the benefits of WinUI 3 and the WinUI roadmap, see the [Windows UI Library Roadmap](https://github.com/microsoft/microsoft-ui-xaml/blob/master/docs/roadmap.md) on GitHub. + + +### Provide feedback and suggestions + +We welcome your feedback in the [WinUI GitHub repo](https://github.com/microsoft/microsoft-ui-xaml/issues/new/choose). + +### What's coming next? + +For more information on when specific features are planned, see the [feature roadmap](https://github.com/microsoft/microsoft-ui-xaml/blob/master/docs/roadmap.md#winui-30-feature-roadmap) on GitHub. + +## Limitations and known issues + +The WinUI 3 - Project Reunion 0.8 Preview is just that, a preview. Please expect bugs, limitations, and other issues. + +The following items are some of the known issues with WinUI 3 - Project Reunion 0.8. If you find an issue that isn't listed below, please let us know by contributing to an existing issue or filing a new issue through the [WinUI GitHub repo](https://github.com/microsoft/microsoft-ui-xaml/issues/new/choose). + +### Platform and OS support + +WinUI 3 - Project Reunion 0.8 Preview is compatible with PCs running the Windows 10 October 2018 Update (version 1809 - build 17763) and newer. + +### Developer tools + +- Only C# and C++/WinRT apps are supported +- Desktop apps support .NET 5 and C# 9, and must be packaged in an MSIX app +- No XAML Designer support +- New C++/CX apps are not supported, however, your existing apps will continue to function (please move to C++/WinRT as soon as possible) +- Unpackaged desktop deployment is not supported +- When running a desktop app using F5, make sure that you are running the packaging project. Hitting F5 on the app project will run an unpackaged app, which WinUI 3 does not yet support. + +### Missing Platform Features + +- Xbox support +- HoloLens support +- Windowed popups + - More specifically, the `ShouldConstrainToRootBounds` property always acts as if it's set to `true`, regardless of the property value. +- Inking support, including: + - [InkCanvas](/uwp/api/Windows.UI.Xaml.Controls.InkCanvas) + - [HandwritingView](/uwp/api/Windows.UI.Xaml.Controls.HandwritingView) + - [InkPresenter](/uwp/api/Windows.UI.Input.Inking.InkPresenter) +- Background acrylic +- MediaElement and MediaPlayerElement +- MapControl +- SwapChainPanel does not support transparency +- AcrylicBrush and other effects using a CompositionBackdropBrush can’t sample from a SwapChainPanel or WebView2. +- Global Reveal uses fallback behavior, a solid brush +- XAML Islands is not supported in this release +- Using WinUI 3 directly in an existing non-WinUI desktop app has the following limitation: The currently available path for migrating an existing app is to add a **new** WinUI 3 project to your solution, and adjust or refactor your logic as needed. + +- Application.Suspending is not called in desktop apps. See API reference documentation on the [Application.Suspending Event](/windows/winui/api/microsoft.ui.xaml.application.suspending) for more details. + +- The [UISettings.ColorValuesChanged Event](/uwp/api/windows.ui.viewmanagement.uisettings.colorvalueschanged) and [AccessibilitySettings.HighContrastChanged Event](/uwp/api/windows.ui.viewmanagement.accessibilitysettings.highcontrastchanged) are no longer supported in desktop apps. This may cause issues if you are using it to detect changes in Windows themes. + +- Previously, to get a CompositionCapabilities instance you would call [CompositionCapabilites.GetForCurrentView()](/uwp/api/windows.ui.composition.compositioncapabilities.getforcurrentview). However, the capabilities returned from this call were *not* dependent on the view. To address and reflect this, we've deleted the GetForCurrentView() static in this release, so now you can create a [CompositionCapabilties](/uwp/api/windows.ui.composition.compositioncapabilities) object directly. + +- CoreWindow, ApplicationView, CoreApplicationView, CoreDispatcher and their dependencies are not supported in desktop apps (see below) + +### CoreWindow, ApplicationView, CoreApplicationView, and CoreDispatcher in desktop apps + +New in WinUI 3 Preview 4 and standard going forward, [CoreWindow](/uwp/api/Windows.UI.Core.CoreWindow), [ApplicationView](/uwp/api/Windows.UI.ViewManagement.ApplicationView), [CoreApplicationView](/uwp/api/Windows.ApplicationModel.Core.CoreApplicationView) [CoreDispatcher](/uwp/api/Windows.UI.Core.CoreDispatcher), and their dependencies are not available in desktop apps. For example, the [Window.Dispatcher](/uwp/api/Windows.UI.Xaml.Window.Dispatcher) property is always **null**, but the **Window.DispatcherQueue** property can be used as an alternative. + +These APIs only work in UWP apps. In past previews they've partially worked in desktop apps as well, but since Preview 4 they've been fully disabled. These APIs are designed for the UWP case where there is only one window per thread, and one of the features of WinUI 3 is to enable multiple in the future. + +There are APIs that internally depend on existence of these APIs, which consequently aren't supported in a desktop app. These APIs generally have a static `GetForCurrentView` method. For example [UIViewSettings.GetForCurrentView](/uwp/api/Windows.UI.ViewManagement.UIViewSettings.GetForCurrentView). + +For more information on affected APIs as well as workarounds and replacements for these APIs, please see [Windows Runtime APIs not supported in desktop apps](../../../desktop/modernize/desktop-to-uwp-supported-api.md). + +### Known issues + +- You may recieve a build error due to mismatched versions of the .NET SDK and the winrt.runtime.dll. As a workaround, you can try the following: + + Explicitly set your .NET SDK to the correct version. To determine the correct version for your app, locate the `` tag in your project file. Using the Windows SDK build number that your app is targeting in the `` tag (such as 18362 or 19041), add the following item to your project file, then save your project: + + ```xml + + + + + ``` + + Note this workaround is required for .NET SDK 5.0.203 and earlier, but will not be required for .NET SDK 5.0.204 or 5.0.300. + + +- When using Visual Studio 2019 16.10 Preview 2, Live Visual Tree may cause a crash. To avoid this, update to the latest [Visual Studio 2019 16.10 Preview](https://visualstudio.microsoft.com/vs/preview/). + +- Window caption buttons may be misplaced when SetTitleBar is not set or null + +## WinUI 3 Controls Gallery + +Check out the WinUI 3 Controls Gallery (previously called _XAML Controls Gallery - WinUI 3 version_) for a sample app that includes all controls and features that are a part of WinUI 3 - Project Reunion 0.8 Preview. + +![WinUI 3 Controls Gallery app](../images/WinUI3XamlControlsGallery.png)
+*Example of the WinUI 3 Controls Gallery app* + +The WinUI 3 Controls Gallery app is available through the [Microsoft Store](https://www.microsoft.com/en-us/p/winui-3-controls-gallery/9p3jfpwwdzrc). + +You can also download the sample by cloning the GitHub repo. To do this, clone the **winui3** branch using the following command: + +> [!NOTE] +> There's also a **winui3preview** branch in this GitHub repo that provides a version of the WinUI 3 Controls Gallery that's using WinUI 3 - Project Reunion 0.8 Preview. + +``` +git clone --single-branch --branch winui3 https://github.com/microsoft/Xaml-Controls-Gallery.git +``` + +After cloning, ensure that you switch to the **winui3** branch in your local Git environment: + +``` +git checkout winui3 +``` diff --git a/hub/apps/winui/winui3/release-notes/winui3-project-reunion-0.5-preview.md b/hub/apps/winui/winui3/release-notes/winui3-project-reunion-0.5-preview.md index c7a1050875..30e8e59a8a 100644 --- a/hub/apps/winui/winui3/release-notes/winui3-project-reunion-0.5-preview.md +++ b/hub/apps/winui/winui3/release-notes/winui3-project-reunion-0.5-preview.md @@ -22,7 +22,7 @@ Windows UI Library (WinUI) 3 is a native user experience (UX) platform for build This version of WinUI 3 is available as part of the Project Reunion 0.5 Preview. -To install, follow the directions found in the [Set up your development environment](../../../project-reunion/get-started-with-project-reunion.md#set-up-your-development-environment) guide for Project Reunion. +To install, follow the directions found in the [Set up your development environment](../../../project-reunion/set-up-your-development-environment.md) guide for Project Reunion. In contrast to past preview versions of WinUI 3, you'll download a Project Reunion VSIX package instead of a WinUI VSIX package. The Project Reunion VSIX includes [WinUI Project Templates](../winui-project-templates-in-visual-studio.md) that you'll use to build your WinUI 3 app. Once you've completed your installation, the experience of developing a WinUI 3 app should not change. diff --git a/hub/apps/winui/winui3/winui-project-templates-in-visual-studio.md b/hub/apps/winui/winui3/winui-project-templates-in-visual-studio.md index 38a7f68c26..3651ba674c 100644 --- a/hub/apps/winui/winui3/winui-project-templates-in-visual-studio.md +++ b/hub/apps/winui/winui3/winui-project-templates-in-visual-studio.md @@ -7,14 +7,14 @@ ms.topic: article # WinUI 3 project templates in Visual Studio -After installing the Project Reunion 0.5 VSIX package, you're ready to create a WinUI 3 app using one of the WinUI project templates in Visual Studio. To access the WinUI project templates in the **Create a new project** dialog, filter the language to **C++** or **C#**, the platform to **Windows**, and the project type to **WinUI**. Alternatively, you can search for *WinUI* and select one of the available C# or C++ templates. +After installing the Project Reunion VSIX, you're ready to create a WinUI 3 app using one of the WinUI project templates in Visual Studio. To access the WinUI project templates in the **Create a new project** dialog, filter the language to **C++** or **C#**, the platform to **Windows**, and the project type to **WinUI**. Alternatively, you can search for *WinUI* and select one of the available C# or C++ templates. ![WinUI project templates](images/winui3-csharp-newproject.png) > [!NOTE] -> Please see our most recent [set of release notes](../index.md) for guidance on setting up your development environment, known issues, and more. +> Please see our most recent [set of release notes](../winui3/index.md) for guidance on setting up your development environment, known issues, and more. -There are two Visual Studio Extensions available as a part of the Project Reunion 0.5 release: the **Project Reunion VSIX**, and the **Project Reunion Preview VSIX**. The Project Reunion VSIX includes project templates that can be used for building MSIX-packaged desktop production apps. The Project Reunion Preview VSIX includes experimental project templates that can be used for building MSIX-packaged desktop or UWP apps. +There are two Project Reunion Visual Studio Extensions available: the **Project Reunion VSIX**, and the **Project Reunion Preview VSIX**. The Project Reunion VSIX includes project templates that can be used for building MSIX-packaged desktop production apps. The Project Reunion Preview VSIX includes experimental project templates that can be used for building MSIX-packaged desktop or UWP apps. ## Project templates for WinUI 3 @@ -23,16 +23,16 @@ You can use these WinUI project templates to create apps. | Template | Language | Description | |----------|----------|-------------| | Blank App, Packaged (WinUI 3 in Desktop) | C# and C++ | Creates a desktop .NET 5 (C#) or native Win32 (C++) app with a WinUI-based user interface. The generated project includes a basic window that derives from the **Microsoft.UI.Xaml.Window** class in the WinUI library that you can use to start building your UI. For more information about this project type, see [Get started with WinUI 3 for desktop apps](get-started-winui3-for-desktop.md).

The solution also includes a [Windows Application Packaging Project](/windows/msix/desktop/desktop-to-uwp-packaging-dot-net) that is configured to build the app into an [MSIX package](/windows/msix/overview). This provides a modern deployment experience, the ability to integrate with Windows 10 features via package extensions, and much more. | -| Blank App (WinUI 3 in UWP), Experimental | C# and C++ | Creates a UWP app that with a WinUI-based user interface. The generated project includes a basic page that derives from the **Microsoft.UI.Xaml.Controls.Page** class in the WinUI library that you can use to start building your UI. For more information about this project type, see [Get started with WinUI 3 for UWP apps](get-started-winui3-for-uwp.md). | +| [Experimental] Blank App (WinUI 3 in UWP) | C# and C++ | Creates a UWP app that with a WinUI-based user interface. The generated project includes a basic page that derives from the **Microsoft.UI.Xaml.Controls.Page** class in the WinUI library that you can use to start building your UI. For more information about this project type, see [Get started with WinUI 3 for UWP apps](get-started-winui3-for-uwp.md). | You can use these WinUI project templates to build components that can be loaded and used by a WinUI-based app. | Template | Language | Description | |----------|----------|-------------| | Class Library (WinUI 3 in Desktop) | C# only | Creates a .NET 5 managed class library (DLL) in C# that can be used by other .NET 5 desktop apps with a WinUI-based user interface. | -| Class Library (WinUI 3 in UWP), Experimental | C# only | Creates a managed class library (DLL) in C# that can be used by other UWP apps with a WinUI-based user interface. | +| [Experimental] Class Library (WinUI 3 in UWP) | C# only | Creates a managed class library (DLL) in C# that can be used by other UWP apps with a WinUI-based user interface. | | Windows Runtime Component (WinUI 3) | C++ | Creates a [Windows Runtime component](/windows/uwp/winrt-components/) written in C++/WinRT that can be consumed by any UWP or desktop app with a WinUI-based user interface, regardless of the programming language in which the app is written. | -| Windows Runtime Component (WinUI 3 in UWP), Experimental | C# | Creates a [Windows Runtime component](/windows/uwp/winrt-components/) written in C# that can be consumed by any UWP app with a WinUI-based user interface, regardless of the programming language in which the app is written. | +| [Experimental] Windows Runtime Component (WinUI 3 in UWP) | C# | Creates a [Windows Runtime component](/windows/uwp/winrt-components/) written in C# that can be consumed by any UWP app with a WinUI-based user interface, regardless of the programming language in which the app is written. | ## Item templates for WinUI 3 @@ -40,6 +40,9 @@ The following item templates are available for use in a WinUI project. To access ![WinUI item templates](images/winui3-addnewitem.png) +> [!NOTE] +> If you have the Project Reunion Preview VSIX installed, you may see a second set of Item Templates that have the [Experimental] prefix. We recommend that you use those [Experimental] item templates if you're building a non-production/preview app, and use the stable, non-marked item templates if you're building a production desktop app. + | Template | Language | Description | |----------|----------|-------------| | Blank Page (WinUI 3) | C# and C++ | Adds a XAML file and code file that defines a new page derived from the **Microsoft.UI.Xaml.Controls.Page** class in the WinUI library. | diff --git a/hub/dev-environment/index.md b/hub/dev-environment/index.md index 78d70ec1d5..d8f8a28a06 100644 --- a/hub/dev-environment/index.md +++ b/hub/dev-environment/index.md @@ -8,7 +8,7 @@ ms.topic: article ms.technology: windows-nodejs keywords: Set up windows, Dev Environment, Dev tools, development paths, Microsoft, Windows, Developer, Tips, Performance, WSL, terminal, nodejs, python ms.localizationpriority: medium -ms.date: 07/24/2020 +ms.date: 06/01/2021 --- # Set up your development environment on Windows 10 @@ -94,10 +94,10 @@ This guide will help you get started with installing and setting up the language [Install Windows Package Manager (public preview)](../package-manager/winget/index.md#install-winget) :::column-end::: :::column::: - [![PowerToys icon](../images/powertoys.png)](https://github.com/microsoft/PowerToys)
- **[Windows PowerToys](https://github.com/microsoft/PowerToys)**
+ [![PowerToys icon](../images/powertoys.png)](../powertoys/index.md)
+ **[Microsoft PowerToys](../powertoys/index.md)**
Tune and streamline your Windows experience for greater productivity with this set of power user utilities.
- [Install PowerToys (public preview)](https://github.com/microsoft/PowerToys#installing-and-running-microsoft-powertoys) + [Install PowerToys](../powertoys/install.md) :::column-end::: :::row-end::: :::row::: diff --git a/hub/dev-environment/javascript/nextjs-on-wsl.md b/hub/dev-environment/javascript/nextjs-on-wsl.md index 9e454f6a1b..a697ab40fe 100644 --- a/hub/dev-environment/javascript/nextjs-on-wsl.md +++ b/hub/dev-environment/javascript/nextjs-on-wsl.md @@ -39,7 +39,7 @@ To install Next.js, which includes installing next, react, and react-dom: 2. Create a new project folder: `mkdir NextProjects` and enter that directory: `cd NextProjects`. -3. Install Next.js and create a project (replacing 'my-next-app' with whatever you'd like to call your app): `npx create next-app my-next-app`. +3. Install Next.js and create a project (replacing 'my-next-app' with whatever you'd like to call your app): `npx create-next-app my-next-app`. 4. Once the package has been installed, change directories into your new app folder, `cd my-next-app`, then use `code .` to open your Next.js project in VS Code. This will allow you to look at the Next.js framework that has been created for your app. Notice that VS Code opened your app in a WSL-Remote environment (as indicated in the green tab on the bottom-left of your VS Code window). This means that while you are using VS Code for editing on the Windows OS, it is still running your app on the Linux OS. diff --git a/hub/dev-environment/rust/overview.md b/hub/dev-environment/rust/overview.md index 46539f514c..172f5a5c77 100644 --- a/hub/dev-environment/rust/overview.md +++ b/hub/dev-environment/rust/overview.md @@ -31,7 +31,7 @@ Furthermore, Microsoft is a founding member of the [Rust Foundation](https://fou We'll introduce some Rust tools and terms in this section. You can refer back here to refresh yourself on any of the descriptions. -* A *crate* is a Rust unit of compilation and linking. A crate can exist in source code form, and from there it can be processed into a crate in the form of either a binary excutable (*binary* for short), or a binary library (*library* for short). +* A *crate* is a Rust unit of compilation and linking. A crate can exist in source code form, and from there it can be processed into a crate in the form of either a binary executable (*binary* for short), or a binary library (*library* for short). * A Rust project is known as a *package*. A package contains one or more crates, together with a `Cargo.toml` file that describes how to build those crates. * `rustup` is the installer and updater for the Rust toolchain. * *Cargo* is the name of Rust's package management tool. diff --git a/hub/dev-environment/toc.yml b/hub/dev-environment/toc.yml index c988e76b35..83382940ba 100644 --- a/hub/dev-environment/toc.yml +++ b/hub/dev-environment/toc.yml @@ -127,18 +127,32 @@ items: - name: Overview href: ../package-manager/winget/index.md + - name: export command + href: ../package-manager/winget/export.md + - name: features command + href: ../package-manager/winget/features.md - name: hash command href: ../package-manager/winget/hash.md - name: help command href: ../package-manager/winget/help.md + - name: import command + href: ../package-manager/winget/import.md - name: install command href: ../package-manager/winget/install.md + - name: list command + href: ../package-manager/winget/list.md - name: search command href: ../package-manager/winget/search.md + - name: settings command + href: ../package-manager/winget/settings.md - name: show command href: ../package-manager/winget/show.md - name: source command href: ../package-manager/winget/source.md + - name: uninstall command + href: ../package-manager/winget/uninstall.md + - name: upgrade command + href: ../package-manager/winget/upgrade.md - name: validate command href: ../package-manager/winget/validate.md - name: Submit packages @@ -149,6 +163,16 @@ href: ../package-manager/package/manifest.md - name: Submit your manifest to the repository href: ../package-manager/package/repository.md + - name: Validation process + href: ../package-manager/package/winget-validation.md + - name: Troubleshooting submissions + href: ../package-manager/package/winget-validation-troubleshooter.md + - name: Binary validation errors + href: ../package-manager/package/binary-validation-errors.md + - name: Repository policies + href: ../package-manager/package/windows-package-manager-policies.md + - name: Repository policies change history + href: ../package-manager/package/windows-package-manager-policies-change-history.md - name: PowerToys items: - name: Overview diff --git a/hub/docfx.json b/hub/docfx.json index c55480011d..72a27c0580 100644 --- a/hub/docfx.json +++ b/hub/docfx.json @@ -52,7 +52,7 @@ "ms.technology": { "apps/**.md": "apps", - "apps/project-reunion/*.md": "", + "apps/project-reunion/**.md": "", "apps/project-reunion/mrtcore/*.md": "mrt-core", "apps/project-reunion/dwritecore.md": "dwrite-core", "apps/winui/**.md": "winui-conceptual", @@ -61,8 +61,8 @@ "android/**.md": "windows-android", "powertoys/**.md": "powertoys", "package-manager/**.md": "package-manager", - "javascript/**.md": "windows-javascript", - "rust/**.md": "windows-rust" + "dev-environment/javascript/**.md": "windows-javascript", + "dev-environment/rust/**.md": "windows-rust" }, "feedback_product_url": { @@ -110,10 +110,11 @@ "apps/speech.md": "kbridge", "dev-environment/*.md": "mattwoj", "android/*.md": "mattwoj", - "nodejs/*.md": "mattwoj", + "javascript/**/*.md": "mattwoj", "python/*.md": "mattwoj", "powertoys/*.md": "mattwoj", - "package-manager/**.md": "kevinla" + "package-manager/**.md": "kevinla", + "rust/*.md": "stwhi" }, "titleSuffix": { diff --git a/hub/includes/package-manager-preview.md b/hub/includes/package-manager-preview.md deleted file mode 100644 index a02407da55..0000000000 --- a/hub/includes/package-manager-preview.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -ms.topic: include -author: mcleanbyron -ms.author: mcleans -ms.date: 04/30/2020 ---- - -> [!IMPORTANT] -> Windows Package Manager and the **winget** tool are in public preview and may be substantially modified before they are generally available. Microsoft makes no warranties, express or implied, with respect to the information provided here. diff --git a/hub/package-manager/index.md b/hub/package-manager/index.md index ba539c596c..3476b5fbb3 100644 --- a/hub/package-manager/index.md +++ b/hub/package-manager/index.md @@ -6,9 +6,7 @@ ms.topic: overview ms.localizationpriority: medium --- -# Windows Package Manager (preview) - -[!INCLUDE [preview-note](../includes/package-manager-preview.md)] +# Windows Package Manager Windows Package Manager is a comprehensive [package manager solution](#understanding-package-managers) that consists of a command line tool and set of services for installing applications on Windows 10. diff --git a/hub/package-manager/package/binary-validation-errors.md b/hub/package-manager/package/binary-validation-errors.md new file mode 100644 index 0000000000..40b82912c8 --- /dev/null +++ b/hub/package-manager/package/binary-validation-errors.md @@ -0,0 +1,31 @@ +--- +title: Binary validation errors +description: Provides additional information about binary validation errors reported by the Windows Package Manager service. +ms.date: 05/25/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# Binary validation errors + +If your [pull request fails](winget-validation.md) to pass the **Installers Scan** test and is given the **Binary-Validation-Error** label, this indicates that your application failed to install on all environments. This article provides more background and guidance about this error. + +## Understanding the Installers Scan test + +Windows Package Manager goes to great lengths to create an excellent user experience when installing applications. In order to do this, we must ensure that all applications install on PCs without errors regardless of environment. + +To that end, a key test we use for the Windows Package Manager is to ensure that all installers will install without warnings on a variety of popular antivirus configurations. While Windows provides Microsoft Defender as a built-in antivirus program, many enterprise customers and users employ a wide range of antivirus software. + +Therefore, each submission to the Windows Package Manager will be run through several antivirus programs. These programs all have different virus detection algorithms for identifying [Potentially unwanted application (PUA)](/windows/security/threat-protection/intelligence/criteria) and malware. + +If an application fails validation, Microsoft will first attempt to verify that the flagged software is not a false positive with the antivirus vendors. In many cases, after notification and validation, the antivirus vendor will update their algorithm and the application will pass. + +## What to do if you see the Binary-Validation-Error label + +In some cases, the code anomaly detected is not able to be determined to be a false positive by the antivirus vendors. In this case the application cannot be added to the Windows Package Manager repository, and the pull request will be rejected with a **Binary-Validation-Error** label. + +If the **Binary-Validation-Error** label is applied to your pull request, update your software to remove the code detected as PUA. + +## What if I cannot remove that code? + +Occasionally, genuine tools used for debugging and low-level activities will appear as PUA to the antivirus vendors. This is because the code necessary to do the debugging will have a similar signature to unwanted software. Even though this is a legitimate use of that coding practice, unfortunately we are unable to allow those applications into the Windows Package Manager repository. diff --git a/hub/package-manager/package/images/details.png b/hub/package-manager/package/images/details.png new file mode 100644 index 0000000000..64808bd19d Binary files /dev/null and b/hub/package-manager/package/images/details.png differ diff --git a/hub/package-manager/package/images/installation-validation.PNG b/hub/package-manager/package/images/installation-validation.PNG new file mode 100644 index 0000000000..264837f1f3 Binary files /dev/null and b/hub/package-manager/package/images/installation-validation.PNG differ diff --git a/hub/package-manager/package/images/manifest-content-validation.PNG b/hub/package-manager/package/images/manifest-content-validation.PNG new file mode 100644 index 0000000000..2234fde2aa Binary files /dev/null and b/hub/package-manager/package/images/manifest-content-validation.PNG differ diff --git a/hub/package-manager/package/images/some-checks-were-not-successful.png b/hub/package-manager/package/images/some-checks-were-not-successful.png new file mode 100644 index 0000000000..5c20debc3c Binary files /dev/null and b/hub/package-manager/package/images/some-checks-were-not-successful.png differ diff --git a/hub/package-manager/package/index.md b/hub/package-manager/package/index.md index 3a4665bf4a..07aedbe1f5 100644 --- a/hub/package-manager/package/index.md +++ b/hub/package-manager/package/index.md @@ -8,15 +8,23 @@ ms.localizationpriority: medium # Submit packages to Windows Package Manager -[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] +This section provides guidance about submitting packages to Windows Package Manager. -If you're an Independent Software Vendor (ISV), you can use Windows Package Manager as a distribution channel for software packages containing your applications. Windows Package Manager currently supports installers in the following formats: MSIX, MSI, and EXE. +## Independent Software Vendor (ISV) or Publisher + +If you are an ISV or Publisher, you can use Windows Package Manager as a distribution channel for software packages containing your applications. Windows Package Manager currently supports installers in the following formats: MSIX, MSI, and EXE. To submit software packages to Windows Package Manager, follow these steps: 1. [Create a package manifest that provides information about your application](manifest.md). Manifests are YAML files that follow the Windows Package Manager schema. 2. [Submit your manifest to the Windows Package Manager repository](repository.md). This is an open source repository on GitHub that contains a collection of manifests that the **winget** tool can access. +## Community member + +If you are a GitHub community member, you may also submit packages to Windows Package Manager following the steps above. + +Optionally, you may also request help to have a package added to the [community repository](https://github.com/microsoft/winget-pkgs). To do so, create a new [Package Request/Submission](https://github.com/microsoft/winget-pkgs/issues/new/choose) issue. + ## Related topics * [Use the winget tool](../winget/index.md) diff --git a/hub/package-manager/package/manifest.md b/hub/package-manager/package/manifest.md index 52d715c354..e65984d93c 100644 --- a/hub/package-manager/package/manifest.md +++ b/hub/package-manager/package/manifest.md @@ -8,8 +8,6 @@ ms.localizationpriority: medium # Create your package manifest -[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] - If you want to submit a software package to the [Windows Package Manager repository](repository.md), start by creating a package manifest. The manifest is a YAML file that describes the application to be installed. This article describes the contents of a package manifest for Windows Package Manager. @@ -36,128 +34,164 @@ A package manifest must include a set of required items, and can also include fu Each field in the manifest file must be Pascal-cased and cannot be duplicated. -For a complete list and descriptions of items in a manifest, see the [manifest specification](https://github.com/microsoft/winget-cli/blob/master/doc/ManifestSpecv0.1.md) in the [https://github.com/microsoft/winget-cli](https://github.com/microsoft/winget-cli) repository. +For a complete list and descriptions of items in a manifest, see the [manifest specification](https://github.com/microsoft/winget-cli/blob/master/doc/ManifestSpecv1.0.md) in the [https://github.com/microsoft/winget-cli](https://github.com/microsoft/winget-cli) repository. ### Minimal required schema +As specified in the [singleton JSON schema](https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.0.0/manifest.singleton.1.0.0.json), +only certain fields are required. The minimal supported YAML file would look like the example below. The singleton format is only valid for packages containing a single installer and a single locale. If more than one installer or locale is provided, the multiple YAML file format and schema must be used. + +The partitioning scheme was added to help with GitHub's UX. Folders with thousands of children do not render well in the browser. + #### [Minimal required schema](#tab/minschema/) ```yaml -Id: string # Publisher.package format. -Publisher: string # The name of the publisher. -Name: string # The name of the application. -Version: string # Version numbering format. -License: string # The open source license or copyright. -InstallerType: string # Enumeration of supported installer types (exe, msi, msix, inno, wix, nullsoft, appx). -Installers: - - Arch: string # Enumeration of supported architectures. - Url: string # Path to download installation file. - Sha256: string # SHA256 calculated from installer. -ManifestVersion: 0.1.0 +PackageIdentifier: # Publisher.package format. +PackageVersion: # Version numbering format. +PackageLocale: # BCP 47 format (e.g. en-US) +Publisher: # The name of the publisher. +PackageName: # The name of the application. +License: # The license of the application. +ShortDescription: # The description of the application. +Installers: + - Architecture: # Enumeration of supported architectures. + InstallerType: # Enumeration of supported installer types (exe, msi, msix, inno, wix, nullsoft, appx). + InstallerUrl: # Path to download installation file. + InstallerSha256: # SHA256 calculated from installer. +ManifestType: # The manifest file type +ManifestVersion: 1.0.0 ``` #### [Example](#tab/minexample/) -```yaml -Id: microsoft.teams -Publisher: Microsoft Corporation -Name: Microsoft Teams -Version: 1.3.0.4461 -License: Copyright (c) Microsoft Corporation. All rights reserved. -InstallerType: exe -Installers: - - Arch: x64 - Url: https://statics.teams.cdn.office.net/production-windows-x64/1.3.00.4461/Teams_windows_x64.exe - Sha256: 712f139d71e56bfb306e4a7b739b0e1109abb662dfa164192a5cfd6adb24a4e1 -ManifestVersion: 0.1.0 +Path: manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0 / WindowsTerminal.yaml + +```YAML +PackageIdentifier: Microsoft.WindowsTerminal +PackageVersion: 1.6.10571.0 +PackageLocale: en-US +Publisher: Microsoft +PackageName: Windows Terminal +License: MIT +ShortDescription: The new Windows Terminal, a tabbed command line experience for Windows. +Installers: + - Architecture: x64 + InstallerType: msix + InstallerUrl: https://github.com/microsoft/terminal/releases/download/v1.6.10571.0/Microsoft.WindowsTerminal_1.6.10571.0_8wekyb3d8bbwe.msixbundle + InstallerSha256: 092aa89b1881e058d31b1a8d88f31bb298b5810afbba25c5cb341cfa4904d843 + SignatureSha256: e53f48473621390c8243ada6345826af7c713cf1f4bbbf0d030599d1e4c175ee +ManifestType: singleton +ManifestVersion: 1.0.0 ``` * * * -### Complete schema +### Multiple manifest files -#### [Complete schema](#tab/compschema/) +To provide the best user experience, manifests should contain as much meta-data as possible. In order to separate concerns for validating installers +and providing localized metadata, manifests should be split into multiple files. The minimum number of YAML files for this kind of manifest is three. Additional locales should also be provided. -```yaml -Id: string # Publisher.package format. -Publisher: string # The name of the publisher. -Name: string # The name of the application. -AppMoniker: string # The common name someone may use to search for the package. -Version: string # Version numbering format for package version. -Channel: string # A string representing the flight ring. -License: string # The open source license or copyright. -LicenseUrl: string # Valid secure URL to license. -MinOSVersion: string # Version numbering format for minimum version of Windows supported. -Description: string # Description of the package. -Homepage: string # Valid secure URL for the package. -Tags: list # Additional strings a user would use to search for the package. -FileExtensions: list # List of file extensions the package could support. -Protocols: list # List of protocols the package provides a handler for. -Commands: list # List of commands or aliases the user would use to run the package. -InstallerType: string # Enumeration of supported installer types (exe, msi, msix, inno, wix, nullsoft, appx). -Switches: # These can be used to change the install behavior if supported by the InstallerType. - Custom: string # Custom switches passed to the installer. - Silent: string # Switches passed to the installer for silent installation. - SilentWithProgress: string # Switches passed to the installer for non-interactive install. - Interactive: string # Experimental. - Language: string # Experimental. - Log: string # Specifies log redirection switches and path. - InstallLocation: string # Specifies alternate location to install package. -Installers: # Nested map of keys for specific installer. - - Arch: string # Enumeration of supported architectures. - Url: string # Path to download installation file. - Sha256: string # SHA256 calculated from installer. - SignatureSha256: string # SHA256 calculated from signature file's hash of MSIX file. - Switches: # Collection of entries to override root keys. The primary supported values are: Custom, Silent, SilentWithProgress, Interactive. For a complete list see the specification at https://github.com/microsoft/winget-cli/blob/master/doc/ManifestSpecv0.1.md. - Scope: string # Experimental. - SystemAppId: string # Experimental. -Localization: # Nested map of keys for localization. - - Language: string # Locale for display fields and localized URLs. -ManifestVersion: string # Version number format for manifest version. -``` +* A [version](https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.0.0/manifest.version.1.0.0.json) file. +* The [default locale](https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.0.0/manifest.defaultLocale.1.0.0.json) file. +* An [installer](https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.0.0/manifest.installer.1.0.0.json) file. +* Additional [locale](https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.0.0/manifest.locale.1.0.0.json) files. -#### [Good example](#tab/good/) +The example below shows many optional metadata fields and multiple locales. Note the default locale has more requirements than additional locales. In the [show command](../winget/show.md), any required fields that aren't provided for additional locales will display fields from the default locale. -```yaml -Id: microsoft.teams -Publisher: Microsoft Corporation -Name: Microsoft Teams -Version: 1.3.0.4461 -License: Copyright (c) Microsoft Corporation. All rights reserved. -LicenseUrl: https://docs.microsoft.com/en-us/MicrosoftTeams/assign-teams-licenses -InstallerType: exe -Installers: - - Arch: x64 - Url: https://statics.teams.cdn.office.net/production-windows-x64/1.3.00.4461/Teams_windows_x64.exe - Sha256: 712f139d71e56bfb306e4a7b739b0e1109abb662dfa164192a5cfd6adb24a4e1 -ManifestVersion: 0.1.0 +#### [Version file example](#tab/version-example/) + +Path: manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0 / Microsoft.WindowsTerminal.yaml + +```YAML +PackageIdentifier: "Microsoft.WindowsTerminal" +PackageVersion: "1.6.10571.0" +DefaultLocale: "en-US" +ManifestType: "version" +ManifestVersion: "1.0.0" +``` + +#### [Default locale file example](#tab/default-locale-example/) + +Path: manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0 / Microsoft.WindowsTerminal.locale.en-US.yaml + +```YAML +PackageIdentifier: "Microsoft.WindowsTerminal" +PackageVersion: "1.6.10571.0" +PackageLocale: "en-US" +Publisher: "Microsoft" +PublisherURL: "https://www.microsoft.com/" +PrivacyURL: "https://privacy.microsoft.com/" +PackageName: "Windows Terminal" +PackageURL: "https://docs.microsoft.com/windows/terminal/" +License: "MIT" +LicenseURL: "https://github.com/microsoft/terminal/blob/master/LICENSE" +ShortDescription: "The new Windows Terminal, a tabbed command line experience for Windows." +Tags: +- "Console" +- "Command-Line" +- "Shell" +- "Command-Prompt" +- "PowerShell" +- "WSL" +- "Developer-Tools" +- "Utilities" +- "cli" +- "cmd" +- "ps" +- "terminal" +ManifestType: "defaultLocale" +ManifestVersion: "1.0.0" ``` -#### [Better example](#tab/better/) +#### [Additional locale file example](#tab/additional-locale-example/) -```yaml -Id: microsoft.teams -Publisher: Microsoft Corporation -Name: Microsoft Teams -Version: 1.3.0.4461 -AppMoniker: teams -MinOSVersion: 10.0.0.0 -Description: The hub for teamwork in Microsoft 365 -Homepage: https://www.microsoft.com/microsoft/teams -License: Copyright (c) Microsoft Corporation. All rights reserved. -LicenseUrl: https://docs.microsoft.com/en-us/MicrosoftTeams/assign-teams-licenses -InstallerType: exe -Installers: - - Arch: x64 - Url: https://statics.teams.cdn.office.net/production-windows-x64/1.3.00.4461/Teams_windows_x64.exe - Sha256: 712f139d71e56bfb306e4a7b739b0e1109abb662dfa164192a5cfd6adb24a4e1 -ManifestVersion: 0.1.0 +Path: manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0 / Microsoft.WindowsTerminal.locale.fr-FR.yaml + +```YAML +PackageIdentifier: "Microsoft.WindowsTerminal" +PackageVersion: "1.6.10571.0" +PackageLocale: "fr-FR" +Publisher: "Microsoft" +ShortDescription: "Le nouveau terminal Windows, une expérience de ligne de commande à onglets pour Windows." +ManifestType: "locale" +ManifestVersion: "1.0.0" +``` + +#### [Installer file example](#tab/installer-example/) + +Path: manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0 / Microsoft.WindowsTerminal.installer.yaml + +```YAML +PackageIdentifier: "Microsoft.WindowsTerminal" +PackageVersion: "1.6.10571.0" +Platform: + - "Windows.Desktop" +MinimumOSVersion: "10.0.18362.0" +InstallerType: "msix" +InstallModes: + - "silent" +PackageFamilyName: "Microsoft.WindowsTerminal_8wekyb3d8bbwe" +Installers: + - Architecture: "x64" + InstallerUrl: "https://github.com/microsoft/terminal/releases/download/v1.6.10571.0/Microsoft.WindowsTerminal_1.6.10571.0_8wekyb3d8bbwe.msixbundle" + InstallerSha256: 092aa89b1881e058d31b1a8d88f31bb298b5810afbba25c5cb341cfa4904d843 + SignatureSha256: e53f48473621390c8243ada6345826af7c713cf1f4bbbf0d030599d1e4c175ee + - Architecture: "arm64" + InstallerUrl: "https://github.com/microsoft/terminal/releases/download/v1.6.10571.0/Microsoft.WindowsTerminal_1.6.10571.0_8wekyb3d8bbwe.msixbundle" + InstallerSha256: 092aa89b1881e058d31b1a8d88f31bb298b5810afbba25c5cb341cfa4904d843 + SignatureSha256: e53f48473621390c8243ada6345826af7c713cf1f4bbbf0d030599d1e4c175ee + - Architecture: "x86" + InstallerUrl: "https://github.com/microsoft/terminal/releases/download/v1.6.10571.0/Microsoft.WindowsTerminal_1.6.10571.0_8wekyb3d8bbwe.msixbundle" + InstallerSha256: 092aa89b1881e058d31b1a8d88f31bb298b5810afbba25c5cb341cfa4904d843 + SignatureSha256: e53f48473621390c8243ada6345826af7c713cf1f4bbbf0d030599d1e4c175ee +ManifestType: "installer" +ManifestVersion: "1.0.0" ``` * * * > [!NOTE] -> if your installer is an .exe and it was built using Nullsoft or Inno, you may specify those values instead. When Nullsoft or Inno are specified, the client will automatically set the silent and silent with progress install behaviors for the installer. +> If your installer is an .exe and it was built using Nullsoft or Inno, you may specify those values instead. When Nullsoft or Inno are specified, the client will automatically set the silent and silent with progress install behaviors for the installer. ## Installer switches @@ -172,9 +206,13 @@ You can often figure out what silent `Switches` are available for an installer b ## Tips and best practices -* For the best customer experience when finding and installing your software, we recommend that you include as many optional items beyond the required schema as possible. For example, the `AppMoniker` field is optional. However, if you include this field, customers will see results associated with the `AppMoniker` value when performing the [search](../winget/search.md) command (for example, **vscode** for **Visual Studio Code**). If there is only one app with the specified `AppMoniker` value, customers can install your application by specifying the moniker rather than the fully qualified ID. -* The `Id` must be unique. You cannot have multiple submissions with the same package identifier. Avoid spaces, because this will require users to put quotation marks around the `Id` when using the [winget](../index.md) client. -* Avoid creating multiple publisher folders. For example, do not create "Contoso Ltd" if there is already a "Contoso" folder. Also avoid spaces when creating folders. -* All packages should be submitted with a silent install if possible. If you have an executable that does not support a silent install, the user experience will be diminished. +* The package identifier must be unique. You cannot have multiple submissions with the same package identifier. Only one pull request per package version is allowed. +* Avoid creating multiple publisher folders. For example, do not create "Contoso Ltd." if there is already a "Contoso" folder. +* All tools must support a silent install. If you have an executable that does not support a silent install, then we cannot provide that tool at this time. +* Provide as many fields as possible. The more meta-data you provide the better the user experience will be. In some cases, the fields may not yet be supported by the Windows Package Manager client (winget.exe). For example, the `AppMoniker` field is optional. However, if you include this field, customers will see results associated with the `AppMoniker` value when performing the [search](../winget/search.md) command (for example, **vscode** for **Visual Studio Code**). If there is only one app with the specified `AppMoniker` value, customers can install your application by specifying the moniker rather than the fully qualified package identifier. +* The length of strings in this specification should be limited to 100 characters before a line break. +* The `PackageName` should match the entry made in **Add / Remove Programs** to help the correlation with manifests to support **export**, and **upgrade**. +* The `Publisher` should match the entry made in **Add / Remove Programs** to help the correlation with manifests to support **export**, and **upgrade**. +* Package installers in MSI format use [product codes](/windows/win32/msi/product-codes) to uniquely identify applications. The product code for a given version of a package should be included in the manifest to help ensure the best **upgrade** experience. * Limit the length of strings in your manifest to 100 characters before a line break. * When more than one installer type exists for the specified version of the package, an instance of `InstallerType` can be placed under each of the `Installers`. diff --git a/hub/package-manager/package/repository.md b/hub/package-manager/package/repository.md index 5b66a2489a..8071d84f59 100644 --- a/hub/package-manager/package/repository.md +++ b/hub/package-manager/package/repository.md @@ -8,11 +8,9 @@ ms.localizationpriority: medium # Submit your manifest to the repository -[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] - After you create a [package manifest](manifest.md) that describes your application, you're ready to submit your manifest to the Windows Package Manager repository. This a public-facing repository that contains a collection of manifests that the **winget** tool can access. To submit your manifest, you'll upload it to the open source [https://github.com/microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs) repository on GitHub. -After you submit a pull request to add a new manifest to the GitHub repository, an automated process will validate your manifest file and check to make sure the package is not known to be malicious. If this validation is successful, your package will be added to the public-facing Windows Package Manager repository so it can be discovered by the **winget** client tool. Note the distinction between the manifests in the open source GitHub repository and the public-facing Windows Package Manager repository. +After you submit a pull request to add a new manifest to the GitHub repository, an automated process will validate your manifest file and check to make sure the package complies with the [Windows Package Manager polices](windows-package-manager-policies.md) and is not known to be malicious. If this validation is successful, your package will be added to the public-facing Windows Package Manager repository so it can be discovered by the **winget** client tool. Note the distinction between the manifests in the open source GitHub repository and the public-facing Windows Package Manager repository. > [!IMPORTANT] > Microsoft reserves the right to refuse a submission for any reason. @@ -25,6 +23,8 @@ There are currently no known third party repositories. Microsoft is working with When you submit a manifest to the [https://github.com/microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs) repository on GitHub, your manifest will be automatically validated and evaluated for the safety of the Windows ecosystem. Manifests may also be reviewed manually. +For more information about the validation process, see [Windows Package Manager validation process](winget-validation.md). + ## How to submit your manifest To submit a manifest to the repository, follow these steps. @@ -60,15 +60,16 @@ Next, create a fork of the repository and clone it. You must add your manifest file to the repository in the following folder structure: -**manifests** / **publisher** / **application** / **version.yaml** +**manifests** / **letter** / **publisher** / **application** / **version** / **Yaml file** * The **manifests** folder is the root folder for all manifests in the repository. +* The **letter** folder is the first letter of the publisher name. * The **publisher** folder is the name of the company that publishes the software. For example, **Microsoft**. * The **application** folder is the name of the application or tool. For example, **VSCode**. -* **version.yaml** is the file name of the manifest. The file name must be set to the current version of the application. For example, **1.0.0.yaml**. +* The **version** folder is the version of the application or tool. For example, **1.0.0**. +* **Yaml File** is the file name of the manifest. The file name must be set to the name and publisher of the application. For example, **Contoso.ContosoApp.yaml**. ->[!IMPORTANT] -> The `Id` value in the manifest must match the publisher and application names in the manifest folder path, and the `version` value in the manifest must match the version in the file name. For more information, see [Create your package manifest](manifest.md#tips-and-best-practices). +The `PackageIdentifier` value in the manifest must match the publisher and application names in the manifest folder path, and the `PackageVersion` value in the manifest must match the version in the file name. For more information, see [Create your package manifest](manifest.md#tips-and-best-practices). ### Step 4: Submit your manifest to the remote repository @@ -76,12 +77,12 @@ You're now ready to push your new manifest to the remote repository. 1. Use the `add` command to prepare for submission. ```CMD - git add manifests\Contoso\ContosoApp\1.0.0.yaml + git add manifests\C\Contoso\ContosoApp\1.0.0\Contoso.ContosoApp.yaml ``` 2. Use the `commit` command to commit the change and provide information on the submission. ```CMD - git commit -m "Submitting ContosoApp version 1.0.0.yaml" + git commit -m "Submitting ContosoApp version 1.0.0.yaml" ``` 3. Use the `push` command to push the changes to the remote repository. @@ -95,34 +96,12 @@ After you push your changes, return to [https://github.com/microsoft/winget-pkgs ![picture of pull request tab](images\pull-request.png) -## Validation process - -When you create a pull request, this will start an automation process that validates the manifest and processes your pull request. We add labels to your pull request so you can track progress. - -### Submission expectations - -All application submissions to the Windows Package Manager repository should be well-behaved. Here are some expectations for submissions: +## Submission process -* The manifest complies with the [schema requirements](manifest.md#manifest-contents). -* All URLs in the manifest lead to safe websites. -* The installer and application are virus free. The package may be identified as malware by mistake. If you believe it's a false positive you can submit the installer to the defender team for analysis from [here](https://www.microsoft.com/wdsi/filesubmission). -* The application installs and uninstalls correctly for both administrators and non-administrators. -* The installer supports non-interactive modes. -* All manifest entries are accurate and not misleading. -* The installer comes directly from the publisher's website. +When you create a pull request, this will start an automated process that validates the manifests and verifies your pull request. During this process we will run tests against the installer and installed binaries to validate the submission. -### Pull request labels +We add labels to your pull request so you can track its progress. For more information, see [Validation process](winget-validation.md). -During validation, we apply a series of labels to our pull request to communicate progress. +Once complete, the submission will be automatically merged and the application will get added to the Windows Package Manager catalog. -* **Needs: author feedback**: There is a failure with the submission. We will reassign pull request back to you. If you do not address the issue within 10 days, we will close the pull request. -* **Manifest-Validation-Error**: The submitted manifest contains a syntax error. -* **URL-Validation-Error**: One or more URLs in the submission failed [SmartScreen](/windows/security/threat-protection/microsoft-defender-smartscreen/microsoft-defender-smartscreen-overview) validation. -* **Binary-Validation-Error**: The submitted application installer failed virus scan testing or there is a hash mismatch. -* **Pull-Request-Error**: There is a problem with the pull request. For example, the folder structure does not have the [required format](#step-3-add-your-manifest-to-the-local-repository). -* **Validation-Error**: The submitted application failed a general validation test. -* **Validation-Installation-Error**: The submitted application failed install testing. -* **Validation-Uninstall-Error**: The submitted application failed uninstall testing. -* **Validation-Virus-Scan-Error**: The submitted application failed virus scan testing. -* **Azure-Pipeline-Passed**: The manifest has completed the first portion of validation. After this step, your pull request is assigned to our test team for final validation. -* **Validation-Completed**: The validation is complete and your pull request will be merged. \ No newline at end of file +If there is an error during the process, you will be notified and our labels and bot will assist you in fixing your submission. For the list of common errors, see [Validation process](winget-validation.md). diff --git a/hub/package-manager/package/windows-package-manager-policies-change-history.md b/hub/package-manager/package/windows-package-manager-policies-change-history.md new file mode 100644 index 0000000000..1f58292882 --- /dev/null +++ b/hub/package-manager/package/windows-package-manager-policies-change-history.md @@ -0,0 +1,13 @@ +--- +title: Change history for Windows Package Manager policies +description: Provides history of changes made to the policy doc. +ms.date: 05/25/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# Change history for Windows Package Manager policies + +| Date | Document Version | Change Description | +|------|------------------|--------------------| +| 5/25/2021 | 1.0 | Initial publishing of Windows Package Manager policies. | diff --git a/hub/package-manager/package/windows-package-manager-policies.md b/hub/package-manager/package/windows-package-manager-policies.md new file mode 100644 index 0000000000..1c8bc72f69 --- /dev/null +++ b/hub/package-manager/package/windows-package-manager-policies.md @@ -0,0 +1,289 @@ +--- +title: Windows Package Manager repository policies +description: Provides the Windows Package Manager repository policies. +ms.date: 05/25/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# Windows Package Manager repository policies + +**Document version: 1.0** + +**Document date: May 22, 2021** + +**Effective date: May 22, 2021** + +Thank you for your interest in providing a Product to the Windows Package Manager repository. + +- **Product** refers to content in whatever form including, but not limited to, apps, games, titles, and any additional content sold or offered from within a **Product**. +- **Submission** refers to a [pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) of manifest files and includes but is not limited to the Product and metadata about the Product. + +A few principles to get you started: + +- Offer unique and distinct value within your Submission. Provide a compelling reason to download the Product from the [Windows Package Manager repository](https://www.github.com/microsoft/winget-pkgs). +- Don’t mislead our customers about what your Submission can do, who is offering it, etc. +- Don’t attempt to cheat customers, the system or the ecosystem. There is no place in the repository for any kind of fraud, be it ratings and review manipulation, credit card fraud or other fraudulent activity. + +Adhering to these policies should help you make choices that enhance your Submission's appeal and audience. + +Your Submissions are crucial to the experience of hundreds of millions of customers. We can't wait to see what you create and want to help deliver your Submissions to the world. + +If you have feedback on the policies or Windows Package Manager, let us know by commenting in our [GitHub issues forum](https://www.github.com/microsoft/winget-cli/issues) + +## Table of Contents + +**Product Policies:** + +- [1.1 Distinct Function & Value; Accurate Representation](#11-distinct-function--value-accurate-representation) +- [1.2 Security](#12-security) +- [1.3 Product is Testable](#13-product-is-testable) +- [1.4 Usability](#14-usability) +- [1.5 Personal Information](#15-personal-information) +- [1.6 Capabilities](#16-capabilities) +- [1.7 Localization](#17-localization) +- [1.8 Financial Transactions](#18-financial-transactions) +- [1.9 Notifications](#19-notifications) +- [1.10 Advertising Conduct and Content](#110-advertising-conduct-and-content) + +**Content Policies:** + +- [2.1 General Content Requirements](#21-general-content-requirements) +- [2.2 Content Including Names, Logos, Original and Third Party](#22-content-including-names-logos-original-and-third-party) +- [2.3 Risk of Harm](#23-risk-of-harm) +- [2.4 Defamatory, Libelous, Slanderous and Threatening](#24-defamatory-libelous-slanderous-and-threatening) +- [2.5 Offensive Content](#25-offensive-content) +- [2.6 Alcohol, Tobacco, Weapons and Drugs](#26-alcohol-tobacco-weapons-and-drugs) +- [2.7 Adult Content](#27-adult-content) +- [2.8 Illegal Activity](#28-illegal-activity) +- [2.9 Excessive Profanity and Inappropriate Content](#29-excessive-profanity-and-inappropriate-content) +- [2.10 Country/Region Specific Requirements](#210-countryregion-specific-requirements) +- [2.11 Age Ratings](#211-age-ratings) +- [2.12 User Generated Content](#212-user-generated-content) + +## Product Policies + +### 1.1 Distinct Function & Value; Accurate Representation + +The Product and its associated metadata, including but not limited to the app title, description, screenshots, trailers, content rating and Product category, must accurately and clearly reflect the source, functionality, and features of the Product. + +### 1.1.1 + +All aspects of the Product should accurately describe the functions, features and any important limitations of the Product. + +### 1.1.2 + +[Tags](https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.0.0/manifest.defaultLocale.1.0.0.json) may not exceed 16 unique tags and should be relevant to the Product. + +### 1.1.3 + +The Product must have distinct and informative metadata and must provide a valuable and quality user experience. + +### 1.1.4 + +The [InstallerUrl](https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.0.0/manifest.defaultLocale.1.0.0.json) must be the ISV's release location for the Product. Products from download websites will not be allowed. + +### 1.2 Security + +The Product must not jeopardize or compromise user security, or the security or functionality of the device, system or related systems. + +### 1.2.1 + +The Product must not attempt to change or extend its described functionality through any form of dynamic inclusion of code that is in violation of Windows Package Manager Policies. The Product should not, for example, download a remote script and subsequently execute that script in a manner that is not consistent with the described functionality. + +### 1.2.2 + +The Product must not contain or enable malware as defined by the Microsoft criteria for [Unwanted and Malicious Software](/windows/security/threat-protection/intelligence/criteria). + +### 1.2.3 + +The Product may contain fully integrated middleware (such as third-party cross-platform engines and third-party analytics services). + +The Product may depend on non-integrated software (such as another Product, module, or service) to deliver its primary functionality, subject to the following requirements: + +### 1.3 Product is Testable + +The Product must be testable. If it is not possible to test your submitted Product for any reason your Product may fail this requirement. + +### 1.4 Usability + +The Product should meet usability standards, including, but not limited to, those listed in the subsections below. + +### 1.4.1 + +The Product should support the devices and platforms on which they are downloaded, including compatibility with the software, hardware and screen resolution requirements specified by the Product. If the Product is downloaded on a device with which it is not compatible, it should detect that at launch and display a message to the customer detailing the requirements. + +### 1.4.2 + +The Product should continue to run and remain responsive to user input. Products should shut down gracefully and not close unexpectedly. The Product should handle exceptions raised by any of the managed or native system APIs and remain responsive to user input after the exception is handled. + +### 1.4.3 + +The Product should start up promptly and must stay responsive to user input. + +### 1.5 Personal Information + +The following requirements apply to Products that access Personal Information. Personal Information includes all information or data that identifies or could be used to identify a person, or that is associated with such information or data. + +### 1.5.1 + +If the Product accesses, collects or transmits Personal Information, or if otherwise required by law, it should maintain a privacy policy. The submission, should include the [PrivacyUrl](https://github.com/microsoft/winget-cli/blob/master/schemas/JSON/manifests/v1.0.0/manifest.defaultLocale.1.0.0.json) which links to the privacy policy of the Product. + +### 1.5.2 + +If the Product publishes the Personal Information of customers of the Product to an outside service or third party, the Product should only do so after obtaining opt-in consent from those customers. Opt-in consent means the customer gives their express permission in the Product user interface for the requested activity, after the Product has: + +- Described to the customer how the information will be accessed, used or shared, indicating the types of parties to whom it is disclosed, and +- Provided the customer a mechanism in the Product user interface through which they can later rescind this permission and opt-out. + +### 1.5.3 + +If the Product publishes a person’s Personal Information to an outside service or third party through the Product or its metadata, but the person whose information is being shared is not a customer of the Product, the Product must obtain express written consent to publish that Personal Information, and must permit the person whose information is shared to withdraw that consent at any time. If the Product provides a customer with access to another person’s Personal Information, this requirement would also apply. + +### 1.5.4 + +If the Product collects, stores or transmits Personal Information, it must do so securely, by using modern cryptography methods. + +### 1.5.5 + +The Product must not collect, store or transmit highly sensitive personal information, such as health or financial data, unless the information is related to the Product’s functionality. The Product must also obtain express user consent before collecting, storing or transmitting such information. The Product’s privacy policy must clearly tell the user when and why it is collecting Personal Information and how it will be used. + +### 1.5.6 + +If the Product supports Microsoft identity authentication it must do so only by using Microsoft-approved methods. + +### 1.5.7 + +Products that receive device location must provide settings that allow the user to enable and disable the Product's access to and use of location from the Location Service API. + +### 1.6 Capabilities + +If the Product declares the use of capabilities, then the capabilities the Product declares must legitimately relate to the functions of the Product. The Product must not circumvent operating system checks for capability usage. + +### 1.7 Localization + +If the Product you should provide localized all languages that it supports. The experience provided by a product must be reasonably similar in all languages that it supports. + +### 1.8 Financial Transactions + +If your product includes in-product purchase, subscriptions, virtual currency, billing functionality or captures financial information, the following requirements apply: + +### 1.8.1 + +In-product offerings sold in your product cannot be converted to any legally valid currency (for example, USD, Euro, etc.) or any physical goods or services. + +### 1.8.2 + +The Product must use a secure purchase API for purchases of physical goods or services, and a secure purchase API for payments made in connection with real world gambling or charitable contributions. If the Product is used to facilitate or collect charitable contributions or to conduct a promotional sweepstakes or contest, it must do so in compliance with applicable law. The Product must also state clearly that Microsoft is not the fundraiser or sponsor of the promotion. + +The Product must use a secure purchase API to receive voluntary donations from users. + +The following requirements apply to your use of a secure purchase API: + +- At the time of the transaction or when the Product collects any payment or financial information from the customer, the Product must identify the commerce transaction provider, authenticate the user, and obtain user confirmation for the transaction. +- The product can offer the user the ability to save this authentication, but the user must have the ability to either require an authentication on every transaction or to turn off in-product transactions. +- If the product collects credit card information or uses a third-party payment processor that collects credit card information, the payment processing must meet the current PCI Data Security Standard (PCI DSS). + +### 1.8.3 + +The product and its associated metadata must provide information about the types of in-product purchases offered and the range of prices. The Product not mislead customers and must be clear about the nature of the in-product promotions and offerings including the scope and terms of any trial experiences. If the Product restricts access to user-created content during or after a trial, it must notify users in advance. In addition, the Product must make it clear to users that they are initiating a purchase option in the Product. + +If your game offers “loot boxes” or other mechanisms that provide randomized virtual items, then you must disclose the odds of receiving each item to customers prior to purchase. These disclosures may appear: in-product, such as in an in-app store, on the Microsoft Store Product Description Page (PDP), and/or on a developer or publisher website, with a link from the Store Product Description Page (PDP) and/or in-app. + +### 10.8.4 + +All pricing, including sales or discounting, for your digital products or services shall comply with all applicable laws, regulations and regulatory guidelines, including without limitation, the Federal Trade Commission [Guides Against Deceptive Pricing](https://www.ecfr.gov/cgi-bin/text-idx?SID=676bd39fe43a808fcb417973b3d0247e&mc=true&tpl=/ecfrbrowse/Title16/16cfr233_main_02.tpl). + +### 1.9 Notifications + +If the Product supports notifications, then the Product must respect system settings for notifications and remain functional when they are disabled. This includes the presentation of ads and notifications to the customer, which must also be consistent with the customer’s preferences, whether the notifications are provided by the Microsoft Push Notification Service (MPNS), Windows Push Notification Service (WNS) or any other service. If the customer disables notifications, either on an Product-specific or system-wide basis, the Product must remain functional. + +### 1.10 Advertising Conduct and Content + +For all advertising related activities, the following requirements apply: + +### 1.10.1 + +- The primary purpose of the Product should not be to get users to click ads. +- The Product may not do anything that interferes with or diminishes the visibility, value, or quality of any ads it displays. +- The Product must respect advertising ID settings that the user has selected. +- All advertising must be truthful, non-misleading and comply with all applicable laws, regulations, and regulatory guidelines. + +## Content Policies + +The following policies apply to content and metadata (including publisher name, Product name, Product icon, Product description, Product screenshots, Product trailers and trailer thumbnails, and any other Product metadata) offered for distribution in the Windows Package Manager repository. Content means the Product name, publisher name, Product icon, Product description, the images, sounds, videos and text contained in the Product, the tiles, notifications, error messages or ads exposed through the Product, and anything that’s delivered from a server or that the Product connects to. Because Product and the Windows Package Manager repository are used around the world, these requirements will be interpreted and applied in the context of regional and cultural norms. + +### 2.1 General Content Requirements + +Metadata and other content you submit to accompany your submission may contain only content that would merit a rating of PEGI 12, ESRB EVERYONE 10+, or lower. + +### 2.2 Content Including Names, Logos, Original and Third Party + +All content in the Product and associated metadata must be either originally created by the application provider, appropriately licensed from the third-party rights holder, used as permitted by the rights holder, or used as otherwise permitted by law. + +### 2.3 Risk of Harm + +### 2.3.1 + +The Product must not contain any content that facilitates or glamorizes the following real world activities: (a) extreme or gratuitous violence; (b) human rights violations; (c) the creation of illegal weapons; or (d) the use of weapons against a person, animal, or real or personal property. + +### 2.3.2 + +The Product must not: (a) pose a safety risk to, nor result in discomfort, injury or any other harm to end users or to any other person or animal; or (b) pose a risk of or result in damage to real or personal property. You are solely responsible for all Product safety testing, certificate acquisition, and implementation of any appropriate feature safeguards. You will not disable any platform safety or comfort features, and you must include all legally required and industry-standard warnings, notices, and disclaimers in the Product. + +### 2.4 Defamatory, Libelous, Slanderous and Threatening + +The Product must not contain any content that is defamatory, libelous, slanderous, or threatening. + +### 2.5 Offensive Content + +The Product and associated metadata must not contain potentially sensitive or offensive content. Content may be considered sensitive or offensive in certain countries/regions because of local laws or cultural norms. In addition, the Product and associated metadata must not contain content that advocates discrimination, hatred, or violence based on considerations of race, ethnicity, national origin, language, gender, age, disability, religion, sexual orientation, status as a veteran, or membership in any other social group. + +### 2.6 Alcohol, Tobacco, Weapons and Drugs + +The Product must not contain any content that facilitates or glamorizes excessive or irresponsible use of alcohol or tobacco Products, drugs, or weapons. + +### 2.7 Adult Content + +The Product must not contain or display content that a reasonable person would consider pornographic or sexually explicit. + +### 2.8 Illegal Activity + +The Product must not contain content or functionality that encourages, facilitates or glamorizes illegal activity in the real world. + +### 2.9 Excessive Profanity and Inappropriate Content + +- The Product must not contain excessive or gratuitous profanity. +- The Product must not contain or display content that a reasonable person would consider to be obscene. + +### 2.10 Country/Region Specific Requirements + +Content that is offensive in any country/region to which the Product is targeted is not allowed. Content may be considered offensive in certain countries/regions because of local laws or cultural norms. Examples of potentially offensive content in certain countries/regions include the following: + +China + +- Prohibited sexual content +- Disputed territory or region references +- Providing or enabling access to content or services that are illegal under applicable local law + +### 2.11 Age Ratings + +The Product should have a age rating that would merit a rating of PEGI 12, ESRB EVERYONE 10+, or lower. + +### 2.11.1 + +If the Product provides content (such as user-generated, retail or other web-based content) that might be appropriate for a higher age rating than its assigned rating, you must enable users to opt in to receiving such content by using a content filter or by signing in with a pre-existing account. + +### 2.12 User Generated Content + +User Generated Content (UGC) is content that users contribute to an app or Product and which can be viewed or accessed by other users in an online state. If the Product contains UGC, the Product should: + +- Publish and make available to users a Product terms of service and/or content guidelines for User Generated Content either in Product or on the Product website. +- Provide a means for users to report inappropriate content within the Product to the developer for review and removal/disablement if in violation of content guidelines and/or implement a method for proactive detection of inappropriate or harmful UGC. +- Remove or disable UGC when requested by Microsoft. + +### See also + +- [Change history for Windows Package Manager policies](windows-package-manager-policies-change-history.md) +- [Windows Package Manager Code of Conduct](https://github.com/microsoft/winget-pkgs/blob/master/CODE_OF_CONDUCT.md) +- [Windows Package Manager Contributing requirements](https://github.com/microsoft/winget-pkgs/blob/master/README.md) diff --git a/hub/package-manager/package/winget-validation-troubleshooter.md b/hub/package-manager/package/winget-validation-troubleshooter.md new file mode 100644 index 0000000000..83e086eb05 --- /dev/null +++ b/hub/package-manager/package/winget-validation-troubleshooter.md @@ -0,0 +1,27 @@ +--- +title: Troubleshooting submissions to Windows Package Manager +description: Provides additional help for how to troubleshooting submission errors for Windows Package Manager. +ms.date: 05/25/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# Troubleshooting submissions to Windows Package Manager + +When Windows Package Manager is processing the manifest files in the pipeline, it [displays labels](winget-validation.md). If your pull request fails then then you may need to investigate to understand the failure better. + +This article walks you through how you can get more information on your pull request failure. + +## Walkthrough of investigating a failure + +1. When a pull request fails, it indicates the failure at the bottom of the web page. It will indicate a failure with the string **Some checks were not successful**. Click the **Details** link. + ![Screenshot of a pull request failure](.\images\some-checks-were-not-successful.png). + +2. After you click **Details**, you will go to an Azure Pipelines page. Click the link with the string **0 errors / 0 warnings**. + ![Screenshot of the Azure Pipelines page](.\images\details.png). + +3. The next page lists the job that failed. In the following screenshot, the failed job is **Manifest Content Validation**. Click the failed job. + ![Screenshot of the error details](.\images\manifest-content-validation.PNG). + +4. The next page displays the output for the failed job. You can use this information to debug the issue. In the following example, the failure was during **Installation Validation** task. The output should help you identify the change that needs to be made to fix the manifest. + ![Screenshot of the failed job output](.\images\installation-validation.png). diff --git a/hub/package-manager/package/winget-validation.md b/hub/package-manager/package/winget-validation.md new file mode 100644 index 0000000000..806ac72876 --- /dev/null +++ b/hub/package-manager/package/winget-validation.md @@ -0,0 +1,113 @@ +--- +title: Windows Package Manager validation process +description: Provides details on the labels specified during submission process. +ms.date: 05/5/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# Windows Package Manager validation process + +When you create a [pull request](repository.md) to submit your manifest to the Windows Package Manager repository, this will start an automation process that validates the manifest and processes your pull request. GitHub labels are used to share progress and allow you to communicate with us. + +## Submission expectations + +All application submissions to the Windows Package Manager repository should be well-behaved and adhere to the [Windows Package Manager repository policies](windows-package-manager-policies.md). +Here are some expectations for submissions: + +- The manifest complies with the [schema requirements](manifest.md?tabs=minschema#manifest-contents). +- All URLs in the manifest lead to safe websites. + +- The installer and application are virus free. The package may be identified as malware by mistake. If you believe it is a false positive you can [submit the installer to the Microsoft Defender team for analysis](https://www.microsoft.com/wdsi/filesubmission). + +- The application installs and uninstalls correctly for both administrators and non-administrators. + +- The installer supports non-interactive modes. + +- All manifest entries are accurate and not misleading. + +- The installer comes directly from the publisher's website. + +For a complete list of the policies, see [Windows Package Manager policies](.\windows-package-manager-policies.md). + +## Pull request labels + +During validation, we apply a series of labels to pull requests to communicate progress. Some labels will direct you to take action, while others will be directed to the Windows Package Manager engineering team. + +### Status labels + +The following table describes the **status labels** you might encounter. + +| **Label** | **Details** | +|--------------|-------------| +| **Azure-Pipeline-Passed** | The manifest has completed the test pass. It is waiting for approval. If no issues are encountered during the test pass it will automatically be approved. If a test fails, it may be flagged for manual review. | +| **Blocking-Issue** | This label indicates that the pull request cannot be approved because there is a blocking issue. You can often tell what the blocking issue is by the included error label. | +| **Needs: Attention** | This label indicates that the pull request needs to be investigated by the Windows Package Manager development team. This is either due to a test failure that needs manual review, or a comment added to the pull request by the community. | +| **Needs: author feedback** | Indicates there is a failure with the submission. We will reassign the pull request back to you. If you do not address the issue within 10 days, the bot will close the pull request. **Needs: author feedback** labels are typically added when there was a failure with the pull request that should be updated, or if the person reviewing the pull request has a question. | +| **Validation-Completed** | Indicates that the test pass has been completed successfully and your pull request will be merged.| + +### Error labels + +The following table describes the **error labels** you might encounter. Not all of the error cases will be assigned to you immediately. Some may trigger manual validation. + +| **Label** | **Details** | +|--------------|-------------| +| **Binary-Validation-Error** | The application included in this pull request failed to pass the **Installers Scan** test. This test is designed to ensure that the application installs on all environments without warnings. For more details on this error, see [Binary validation errors](binary-validation-errors.md). | +| **Error-Analysis-Timeout** | The **Binary-Validation-Test** test timed out. The pull request will get assigned to a Windows Package Manager engineer to investigate. | +| **Error-Hash-Mismatch** | The submitted manifest could not be processed because the **InstallerSha256** hash provided for the **InstallerURL** did not match. Update the **InstallerSha256** in the pull request and try again. | +| **Error-Installer-Availability** | The validation service was unable to download the installer. This may be related to Azure IP ranges being blocked, or the installer URL may be incorrect. Check that the **InstallerURL** is correct and try again. If you feel this has failed in error, add a comment and the pull request will get assigned to a Windows Package Manager engineer to investigate. | +| **Manifest-Path-Error** | The manifest files must be put into a specific folder structure. This label indicates a problem with the path of your submission. For example, the folder structure does not have the [required format](manifest.md?tabs=minschema%2Ccompschema). Update your manifest and path resubmit your pull request. | +| **Manifest-Validation-Error** | The submitted manifest contains a syntax error. Address the syntax issue with the manifest and re-submit. For details on the manifest format and schema, see [required format](manifest.md?tabs=minschema%2Ccompschema). | +| **PullRequest-Error** | The pull request is invalid because not all files submitted are under manifest folder or there is more than one package or version in the pull request. Update your pull request to address the issue and try again. | +| **URL-Validation-Error** | The **URLs Validation Test** could not locate the URL and responded with a [HTTP error status code](/troubleshoot/iis/http-status-code) (403 or 404), or the URL reputation test failed. You can identify which URL is in question by looking at the [pull request check details](winget-validation-troubleshooter.md). To address this issue, update the URLs in question to resolve the HTTP error status code. If the issue is not due to an HTTP error status code, you can [submit the URL for review](https://www.microsoft.com/wdsi/filesubmission/) to avoid the reputation failure. | +| **Validation-Defender-Error** | During dynamic testing, Microsoft Defender reported a problem. To reproduce this problem, install your application, then run a Microsoft Defender full scan. If you can reproduce the problem, fix the binary or [submit it for analysis](/microsoft-365/security/defender-endpoint/defender-endpoint-false-positives-negatives?#part-4-submit-a-file-for-analysis) for false positive assistance. If you are unable to reproduce the problem, add a comment to get the Windows Package Manager engineers to investigate. | +| **Validation-Domain** | The test has determined the domain if the **InstallerURL** does not match the domain expected. The Windows Package Manager policies requires that the [InstallerUrl](manifest.md?tabs=minschema%2Ccompschema) comes directly from the ISV's release location. If you believe this is a false detection, add a comment to the pull request to get the Windows Package Manager engineers to investigate. | +| **Validation-Error** | Validation of the Windows Package Manager failed during manual approval. Look at the accompanying comment for next steps. | +| **Validation-Executable-Error** | During installation testing, the test was unable to locate the primary application. Make sure the application installs correctly on all platforms. If your application does not install an application, but should still be included in the repository, add a comment to the pull request to get the Windows Package Manager engineers to investigate. | +| **Validation-Hash-Verification-Failed** | During installation testing, the application fails to install because the **InstallerSha256** no longer matches the **InstallerURL** hash. This can occur if the application is behind a vanity URL and the installer was updated without updating the **InstallerSha256**. To address this issue, update the **InstallerSha256** associated with the **InstallerURL** and submit again. | +| **Validation-HTTP-Error** | The URL used for the installer does not use the HTTPS protocol. Update the **InstallerURL** to use HTTPS and resubmit the **Pull Request.** | +| **Validation-Indirect-URL** | The URL is not coming directly from the ISVs server. Testing has determined a redirector has been used. This is not allowed because the Windows Package Manager policies require that the [InstallerUrl](manifest.md?tabs=minschema%2Ccompschema) comes directly from the ISV's release location. Remove the redirection and resubmit. +| **Validation-Installation-Error** | During manual validation of this package, there was a general error. Look at the accompanying comment for next steps. | +| **Validation-Merge-Conflict** | This package could not be validated due to a merge conflict. Please address the merge conflict and resubmit your pull request. | +| **Validation-MSIX-Dependency** | The MSIX package has a dependency on package that could not be resolved. Update the package to include the missing components or add the dependency to the manifest file and resubmit the pull request. | +| **Validation-Unapproved-URL** | The test has determined the domain if the **InstallerURL** does not match the domain expected. The Windows Package Manager policies requires that the [InstallerUrl](manifest.md?tabs=minschema%2Ccompschema) comes directly from the ISV's release location. | +| **Validation-Unattended-Failed** | During installation, the test timed out. This most likely is due to the application not installing silently. It could also be due to some other error being encountered and stopping the test. Verify that you can install your manifest without user input. If you need assistance, add a comment to the pull request and the Windows Package Manager engineers will investigate. | +| **Validation-Uninstall-Error** | During uninstall testing, the application did not clean up completely following uninstall. Look at the accompanying comment for more details. | +| **Validation-VCRuntime-Dependency** | The package has a dependency on the C++ runtime that could not be resolved. Update the package to include the missing components or add the dependency to the manifest file and resubmit the pull request. | + +### Content policy labels + +The following table lists **content policy labels**. If one of these labels is added, something in the manifest metadata triggered additional manual content review to ensure that the metadata is following the [Windows Package Manager policies](windows-package-manager-policies.md). + +| **Label** | **Details** | +|--------------|-------------| +| **Policy-Test-2.1** | See [General Content Requirements](windows-package-manager-policies.md#21-general-content-requirements). | +| **Policy-Test-2.2** | See [Content Including Names, Logos, Original and Third Party](windows-package-manager-policies.md#22-content-including-names-logos-original-and-third-party) | +| **Policy-Test-2.3** | See [Risk of Harm](windows-package-manager-policies.md#23-risk-of-harm). | +| **Policy-Test-2.4** | See [Defamatory, Libelous, Slanderous and Threatening](windows-package-manager-policies.md#24-defamatory-libelous-slanderous-and-threatening). | +| **Policy-Test-2.5** | See [Offensive Content](windows-package-manager-policies.md#25-offensive-content). | +| **Policy-Test-2.6** | See [Alcohol, Tobacco, Weapons and Drugs](windows-package-manager-policies.md#26-alcohol-tobacco-weapons-and-drugs). | +| **Policy-Test-2.7** | See [Adult Content](windows-package-manager-policies.md#27-adult-content). | +| **Policy-Test-2.8** | See [Illegal Activity](windows-package-manager-policies.md#28-illegal-activity). | +| **Policy-Test-2.9** | See [Excessive Profanity and Inappropriate Content](windows-package-manager-policies.md#29-excessive-profanity-and-inappropriate-content). | +| **Policy-Test-2.10** | See [Country/Region Specific Requirements](windows-package-manager-policies.md#210-countryregion-specific-requirements). | +| **Policy-Test-2.11** | See [Age Ratings](windows-package-manager-policies.md#211-age-ratings). | +| **Policy-Test-2.12** | See [User Generated Content](windows-package-manager-policies.md#212-user-generated-content). | + +### Internal labels + +The following table lists internal error labels. When internal errors are encountered, your pull request will be assigned to the Windows Package +Manager engineers to investigate. + +| **Label** | **Details** | +|--------------|-------------| +|**Internal-Error-Domain**| An error occurred during the domain validation of the URL. | +|**Internal-Error-Dynamic-Scan**| An error occurred during the validation of the installed binaries. | +|**Internal-Error-Keyword-Policy**| An error occurred during the validation of the manifest. | +|**Internal-Error-Manifest**| An error occurred during the validation of the manifest. | +|**Internal-Error-NoArchitectures**| An error occurred because the test could not determine the architecture if the application.| +|**Internal-Error-NoSupportedArchitectures**| An error occurred because the current architecture is not supported. | +|**Internal-Error-PR**| An error occurred during the processing of the pull request. | +|**Internal-Error-Static-Scan**| An error occurred during static analysis of the installers. | +|**Internal-Error-URL**| An error occurred during reputation validation of the installers. | +|**Internal-Error**| A generic failure or unknown error was encountered during the test pass. | diff --git a/hub/package-manager/winget/export.md b/hub/package-manager/winget/export.md new file mode 100644 index 0000000000..b2485686a1 --- /dev/null +++ b/hub/package-manager/winget/export.md @@ -0,0 +1,62 @@ +--- +title: export Command +description: exports the list of installed applications. +ms.date: 05/02/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# export command (winget) + +The **export** command of the [winget](index.md) tool exports a JSON file of apps to a specified file. The **export** command uses JSON as the format. The JSON schema used by **winget** can be found [here](https://aka.ms/winget-packages.schema.1.0.json). + +The **export** combined with the [**import**](.\import.md) command allows you to batch install applications on your PC. + +The **export** command is often used to create a file that you can share with other developers, or for use when restoring your build environment. + +## Usage + +`winget export [-o] []` + +![Image of the export command usage](images\export.png) + +## Arguments + +The following arguments are available. + +| Argument | Description | +|-------------|-------------| +| **-o,--output** | Path to the JSON file to be created | + +## Options + +The options allow you to customize the export experience to meet your needs. + +| Option | Description | +|----------------|-------------| +| **-s, --source** | [optional] Specifies a source to export files from. Use this option when you only want files from a specific source. | +| **--include-versions** | [optional] Includes the version of the app currently installed. Use this option if you want a specific version. By default, unless specified, [**import**](.\import.md) will use latest. | + +## JSON schema + +The driving force behind the **export** command is the JSON file. You can find the schema for the JSON file [here](https://aka.ms/winget-packages.schema.1.0.json). + +The JSON file includes the following hierarchy. + +| Entry | Description | +|-------------|-------------| +| **Sources** | The sources application manifests come from. | +| **Packages** | The collection of packages to install. | +| **Id** | The Windows Package Manager package identifier used to specify the package. | +| **Version** | [optional] The specific version of the package to install. | + +## Exporting files + +When the Windows Package Manager exports the JSON file, it attempts to export all the applications installed on the PC. If the **winget export** command is not able to match an application to an application from an available **source**, the export command will show a warning. + +> [!NOTE] +> Matching an application depends on metadata in the manifest from a configured source, and metadata in **Add / Remove Programs** in Windows based on the package installer. + +![Image of export command warnings](images\export-command.png) + +After the export is complete, you can edit the resulting JSON file in your favorite editor. You can remove apps you do not wish to import in the future. diff --git a/hub/package-manager/winget/features.md b/hub/package-manager/winget/features.md new file mode 100644 index 0000000000..f7da34b2c9 --- /dev/null +++ b/hub/package-manager/winget/features.md @@ -0,0 +1,28 @@ +--- +title: features Command +description: Displays the list of experimental features available and the state. +ms.date: 05/5/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# features command (winget) + +The **features** command of the [winget](index.md) tool displays a list of the experimental features available with your version of the Windows Package Manager. + +Each feature can be turned on individually by enabling the features through [**settings**](.\settings.md). + +You can find the latest up to date information features on the [experimental features](https://aka.ms/winget-experimentalfeatures) web page. + +## Usage + +`winget features` + +![features command](images\features.png) + +Notice above that the status of each feature is listed. If the feature is **disabled** you will not be able to use it. If the feature is **enabled** you will notice that the command will be available to you through **winget**. + +To enabled any disabled features, go to **settings** and enable the feature. + +> [!NOTE] +> Features may be managed by group policy. You can use the **winget --info** command to view any policies in effect on your system. diff --git a/hub/package-manager/winget/hash.md b/hub/package-manager/winget/hash.md index 00a56fb18d..f7a73ddbe8 100644 --- a/hub/package-manager/winget/hash.md +++ b/hub/package-manager/winget/hash.md @@ -8,8 +8,6 @@ ms.localizationpriority: medium # hash command (winget) -[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] - The **hash** command of the [winget](index.md) tool generates the SHA256 hash for an installer. This command is used if you need to create a [manifest file](../package/manifest.md) for submitting software to the **Microsoft Community Package Manifest Repository** on GitHub. In addition, the **hash** command also supports generating a SHA256 certificate hash for MSIX files. ## Usage diff --git a/hub/package-manager/winget/help.md b/hub/package-manager/winget/help.md index 9653289043..98bc13aa7f 100644 --- a/hub/package-manager/winget/help.md +++ b/hub/package-manager/winget/help.md @@ -8,8 +8,6 @@ ms.localizationpriority: medium # help command (winget) -[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] - The **help** command of the [winget](index.md) tool displays help for all the supported commands and sub commands. In addition, you can pass the **--help** argument to any other command to get details about all additional command options. ## Usage diff --git a/hub/package-manager/winget/images/export-command.png b/hub/package-manager/winget/images/export-command.png new file mode 100644 index 0000000000..1feeaba245 Binary files /dev/null and b/hub/package-manager/winget/images/export-command.png differ diff --git a/hub/package-manager/winget/images/export.png b/hub/package-manager/winget/images/export.png new file mode 100644 index 0000000000..43d97d8aa6 Binary files /dev/null and b/hub/package-manager/winget/images/export.png differ diff --git a/hub/package-manager/winget/images/features.png b/hub/package-manager/winget/images/features.png new file mode 100644 index 0000000000..592684afc8 Binary files /dev/null and b/hub/package-manager/winget/images/features.png differ diff --git a/hub/package-manager/winget/images/import-command.png b/hub/package-manager/winget/images/import-command.png new file mode 100644 index 0000000000..d29d5444a3 Binary files /dev/null and b/hub/package-manager/winget/images/import-command.png differ diff --git a/hub/package-manager/winget/images/import.png b/hub/package-manager/winget/images/import.png new file mode 100644 index 0000000000..b3ec063833 Binary files /dev/null and b/hub/package-manager/winget/images/import.png differ diff --git a/hub/package-manager/winget/images/list-count.png b/hub/package-manager/winget/images/list-count.png new file mode 100644 index 0000000000..84e7af989d Binary files /dev/null and b/hub/package-manager/winget/images/list-count.png differ diff --git a/hub/package-manager/winget/images/list-update.png b/hub/package-manager/winget/images/list-update.png new file mode 100644 index 0000000000..4b43acda32 Binary files /dev/null and b/hub/package-manager/winget/images/list-update.png differ diff --git a/hub/package-manager/winget/images/list.png b/hub/package-manager/winget/images/list.png new file mode 100644 index 0000000000..671442d451 Binary files /dev/null and b/hub/package-manager/winget/images/list.png differ diff --git a/hub/package-manager/winget/images/settings.png b/hub/package-manager/winget/images/settings.png new file mode 100644 index 0000000000..9426ed64e3 Binary files /dev/null and b/hub/package-manager/winget/images/settings.png differ diff --git a/hub/package-manager/winget/images/uninstall-execute.png b/hub/package-manager/winget/images/uninstall-execute.png new file mode 100644 index 0000000000..16ac04e334 Binary files /dev/null and b/hub/package-manager/winget/images/uninstall-execute.png differ diff --git a/hub/package-manager/winget/images/uninstall-multiple.png b/hub/package-manager/winget/images/uninstall-multiple.png new file mode 100644 index 0000000000..acaa48a354 Binary files /dev/null and b/hub/package-manager/winget/images/uninstall-multiple.png differ diff --git a/hub/package-manager/winget/images/uninstall-with-list.png b/hub/package-manager/winget/images/uninstall-with-list.png new file mode 100644 index 0000000000..9baed75c94 Binary files /dev/null and b/hub/package-manager/winget/images/uninstall-with-list.png differ diff --git a/hub/package-manager/winget/images/uninstall.png b/hub/package-manager/winget/images/uninstall.png new file mode 100644 index 0000000000..10d097a892 Binary files /dev/null and b/hub/package-manager/winget/images/uninstall.png differ diff --git a/hub/package-manager/winget/images/upgrade.gif b/hub/package-manager/winget/images/upgrade.gif new file mode 100644 index 0000000000..ab86c0c5a4 Binary files /dev/null and b/hub/package-manager/winget/images/upgrade.gif differ diff --git a/hub/package-manager/winget/images/upgrade.png b/hub/package-manager/winget/images/upgrade.png new file mode 100644 index 0000000000..2c740561dc Binary files /dev/null and b/hub/package-manager/winget/images/upgrade.png differ diff --git a/hub/package-manager/winget/import.md b/hub/package-manager/winget/import.md new file mode 100644 index 0000000000..183577fe57 --- /dev/null +++ b/hub/package-manager/winget/import.md @@ -0,0 +1,57 @@ +--- +title: import Command +description: imports the list of installed applications. +ms.date: 05/02/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# import command (winget) + +The **import** command of the [winget](index.md) tool imports a JSON file of apps to install. The **import** command combined with the [**export**](.\export.md) command allows you to batch install applications on your PC. + +The **import** command is often used to share your developer environment or build up your PC image with your favorite apps. + +## Usage + +`winget import [-i] []` + +![Image of import command options](images\import.png) + +## Arguments + +The following arguments are available. + +| Argument | Description | +|-------------|-------------| +| **-i,--import-file** | JSON file describing the packages to install. | + +## Options + +The options allow you to customize the import experience to meet your needs. + +| Option | Description | +|-------------|-------------| +| **--ignore-unavailable** | Suppresses errors if the app requested is unavailable. | +| **--ignore-versions** | Ignores versions specified in the JSON file and installs the latest available version. | + +## JSON Schema + +The driving force behind the **import** command is the JSON file. You can find the schema for the JSON file [here](https://aka.ms/winget-packages.schema.1.0.json). + +The JSON file includes the following hierarchy. + +| Entry | Description | +|-------------|-------------| +| **Sources** | The sources application manifests come from. | +| **Packages** | The collection of packages to install. | +| **Id** | The Windows Package Manager package identifier used to specify the package. | +| **Version** | [optional] The specific version of the package to install. | + +## Importing files + +When the Windows Package Manager imports the JSON file, it attempts to install the specified applications in a serial fashion. If the application is not available or the application is already installed, it will notify the user of that case. + +![Image of importing files command](images\import-command.png) + +In the previous example, the Microsoft.WindowsTerminal was already installed. Therefore the import command skipped passed the installation. diff --git a/hub/package-manager/winget/index.md b/hub/package-manager/winget/index.md index 3316e3175a..23138561c1 100644 --- a/hub/package-manager/winget/index.md +++ b/hub/package-manager/winget/index.md @@ -8,8 +8,6 @@ ms.localizationpriority: medium # Use the winget tool to install and manage applications -[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] - The **winget** command line tool enables developers to discover, install, upgrade, remove and configure applications on Windows 10 computers. This tool is the client interface to the Windows Package Manager service. The **winget** tool is currently a preview, so not all planned functionality is available at this time. @@ -25,13 +23,13 @@ There are several ways to install the **winget** tool: * Install the Windows Desktop App Installer package located on the [Releases page for the winget repository](https://github.com/microsoft/winget-cli/releases). > [!NOTE] -> The **winget** tool requires Windows 10, version 1709 (10.0.16299), or a later version of Windows 10. +> The **winget** tool requires Windows 10, version 1809 (10.0.17763), or a later version of Windows 10. ## Administrator considerations Installer behavior can be different depending on whether you are running **winget** with administrator privileges. -* When running **winget** without administrator privileges, some applications may [require elevation](https://docs.microsoft.com/windows/security/identity-protection/user-account-control/) to install. When the installer runs, Windows will prompt you to [elevate](https://docs.microsoft.com/windows/security/identity-protection/user-account-control). If you choose not to elevate, the application will fail to install. +* When running **winget** without administrator privileges, some applications may [require elevation](/windows/security/identity-protection/user-account-control/) to install. When the installer runs, Windows will prompt you to [elevate](/windows/security/identity-protection/user-account-control). If you choose not to elevate, the application will fail to install. * When running **winget** in an Administrator Command Prompt, you will not see [elevation prompts](/windows/security/identity-protection/user-account-control/how-user-account-control-works) if the application requires it. Always use caution when running your command prompt as an administrator, and only install applications you trust. @@ -54,13 +52,19 @@ The current preview of the **winget** tool supports the following commands. | Command | Description | |---------|-------------| +| [export](export.md) | Exports a list of the installed packages. | +| [features](features.md) | Shows the status of experimental features. | | [hash](hash.md) | Generates the SHA256 hash for the installer. | -| [help](help.md) | Displays help for the **winget** tool commands. | +| [import](import.md) | Installs all the packages in a file. | | [install](install.md) | Installs the specified application. | +| [list](list.md) | Display installed packages. | | [search](search.md) | Searches for an application. | +| [settings](settings.md) | Open settings. | | [show](show.md) | Displays details for the specified application. | | [source](source.md) | Adds, removes, and updates the Windows Package Manager repositories accessed by the **winget** tool. | | [validate](validate.md) | Validates a manifest file for submission to the Windows Package Manager repository. | +| [uninstall](uninstall.md) | Uninstalls the given package. | +| [upgrade](upgrade.md) | Upgrades the given package. | ### Options @@ -68,8 +72,8 @@ The current preview of the **winget** tool supports the following options. | Option | Description | |--------------|-------------| -| **-v,--version** | Returns the current version of winget. | -| **--info** | Provides you with all detailed information on winget, including the links to the license and privacy statement. | +| **-v, --version** | Returns the current version of winget. | +| **--info** | Provides you with all detailed information on winget, including the links to the license, privacy statement, and configured group policies. | | **-?, --help** | Shows additional help for winget. | ## Supported installer formats diff --git a/hub/package-manager/winget/install.md b/hub/package-manager/winget/install.md index 5549ed0fb0..54c515c32e 100644 --- a/hub/package-manager/winget/install.md +++ b/hub/package-manager/winget/install.md @@ -8,8 +8,6 @@ ms.localizationpriority: medium # install command (winget) -[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] - The **install** command of the [winget](index.md) tool installs the specified application. Use the [**search**](search.md) command to identify the application you want to install. The **install** command requires that you specify the exact string to install. If there is any ambiguity, you will be prompted to further filter the **install** command to an exact application. @@ -78,11 +76,17 @@ The best way to limit the selection to one file is to use the **id** of the appl winget install --id Git.Git -e ``` +If multiple sources are configured, it is possible to have duplicate entries. Specifying a source is required to further disambiguate. + +```CMD +winget install --id Git.Git -e -source winget +``` + ## Local install -The **manifest** option enables you to install an application by passing in a YAML file directly to the client. The **manifest** option has the following usage. +The **manifest** option enables you to install an application by passing in a YAML file directly to the client. If the manifest is a multi-file manifest, the directory containing the files must be used. The **manifest** option has the following usage. -Usage: `winget install --manifest \` +Usage: `winget install --manifest \` | Option | Description | |-------------|-------------| diff --git a/hub/package-manager/winget/list.md b/hub/package-manager/winget/list.md new file mode 100644 index 0000000000..c73492e9f9 --- /dev/null +++ b/hub/package-manager/winget/list.md @@ -0,0 +1,81 @@ +--- +title: list Command +description: Displays the list of listed apps and if an update is available. +ms.date: 05/5/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# list command (winget) + +The **list** command of the [winget](index.md) tool displays a list of the applications currently installed on your computer. The list command will show apps that were installed through the Windows Package Manager as well as apps that were installed by other means. + +The **list** command will also display if an update is available for an app, and you can use the [**upgrade**](.\upgrade.md) command to update the app. + +The **list** command also supports filters which can be used to limit your list query. + +## Usage + +`winget list [[-q] \] [\]` + +![Image of list command usage](images\list.png) + +## Arguments + +The following arguments are available. + +| Argument | Description | +|-------------|-------------| +| **-q,--query** | The query used to search for an app. | +| **-?, --help** | Get additional help on this command. | + +## Options + +The options allow you to customize the list experience to meet your needs. + +| Option | Description | +|-------------|-------------| +| **--id** | Limits the list to the ID of the application. | +| **--name** | Limits the list to the name of the application. | +| **--moniker** | Limits the list to the moniker listed for the application. | +| **-s, --source** | Restricts the list to the source name provided. Must be followed by the source name. | +| **--tag** | Filters results by tags. | +| **--command** | Filters results by command specified by the application. | +| **-n, --count** | Limits the number of apps displayed in one query. | +| **-l, --location** | Location to list to (if supported). | +| **-e, --exact** | Uses the exact string in the list query, including checking for case-sensitivity. It will not use the default behavior of a substring. | + +### Example queries + +The following example lists a specific version of an application. + +```CMD +winget list --name powertoys + +``` + +The following example lists all application by ID from a specific source. + +```CMD +winget list --id Microsoft.PowerToys --source winget +``` + +The following example limits the output of list to twelve apps. + +```CMD +winget list -n 12 +``` + +![Image of list output command limited to twelve apps](images\list-count.png) + +## List with update + +As stated above, the **list** command allows you to see what apps you have installed that have updates available. + +In the image below, you will notice the preview version of Terminal has an update available. + +![Image of list with update command](images\list-update.png) + +The **list** command will show not only the update version available, but the source that the update is available from. + +* [Use the winget tool to list and manage applications](index.md) diff --git a/hub/package-manager/winget/search.md b/hub/package-manager/winget/search.md index e322a915cf..eaf3ca9cb0 100644 --- a/hub/package-manager/winget/search.md +++ b/hub/package-manager/winget/search.md @@ -8,7 +8,6 @@ ms.localizationpriority: medium # search command (winget) -[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] The **search** command of the [winget](index.md) tool queries the sources for available applications that can be installed. diff --git a/hub/package-manager/winget/settings.md b/hub/package-manager/winget/settings.md new file mode 100644 index 0000000000..b3836b4c87 --- /dev/null +++ b/hub/package-manager/winget/settings.md @@ -0,0 +1,140 @@ +--- +title: settings command +description: Provides customizations for the Windows Package Manager. +ms.date: 05/05/2021 +ms.topic: article +ms.localizationpriority: medium +--- + +# settings command (winget) + +The **settings** command of the [winget](index.md) tool allows you to customize your Windows Package Manager client experience. You can change defaults and try out experimental features that are enabled in your client. + +The **settings** command will launch your default text editor. Windows by default will launch Notepad as an option. We recommend using a tool like [Visual Studio code](https://code.visualstudio.com/). + +>[!NOTE] +>You can easily install Visual Studio Code by typing `winget install Microsoft.VisualStudioCode` + +## Usage + +Launch your default JSON editing tool: `winget settings` + +![Screenshot of the Windows Package Manager Settings.](images\settings.png) + +When you launch the settings for the first time, there will be no settings specified. At the top of the JSON file we provide a [link](https://aka.ms/winget-settings) where you can discover the latest experimental features and settings. + +We have also defined a schema for the settings file. This allows you to use TAB to discover settings and syntax if your JSON editor supports JSON schemas. + +## Updating settings + +The following settings are available for the 1.0 release of the Windows Package Manager. + +### source + +The `source` settings involve configuration to the WinGet source. + +```json +"source": { + "autoUpdateIntervalInMinutes": 3 +}, +``` + +#### autoUpdateIntervalInMinutes + +A positive integer represents the update interval in minutes. The check for updates only happens when a source is used. A zero will disable the check for updates to a source. Any other values are invalid. + +- Disable: 0 +- Default: 5 + +To manually update the source use `winget source update`. + +### visual + +The `visual` settings involve visual elements that are displayed by WinGet + +```json +"visual": { + "progressBar": "accent" +}, +``` + +#### progressBar + +Color of the progress bar that WinGet displays when not specified by arguments. + +- accent (default) +- retro +- rainbow + +### installBehavior + +The `installBehavior` settings affect the default behavior of installing and upgrading (where applicable) packages. + +#### preferences and requirements + +Some of the settings are duplicated under `preferences` and `requirements`. + +- The `preferences` setting affects how the various available options are sorted when choosing the one to act on. For example, the default scope of package installs is for the current user, but if that is not an option then a machine level installer will be chosen. +- The `requirements` setting filters the options, potentially resulting in an empty list and a failure to install. In the previous example, a user scope requirement would result in no applicable installers and an error. + +Any arguments passed on the command line will effectively override the matching `requirement` setting for the duration of that command. + +#### scope + +The `scope` behavior affects the choice between installing a package for the current user or for the entire machine. The matching parameter is `--scope`, and uses the same values (`user` or `machine`). + +```json +"installBehavior": { + "preferences": { + "scope": "user" + } +}, +``` + +#### locale + +The `locale` behavior affects the choice of installer based on installer locale. The matching parameter is `--locale`, and uses bcp47 language tag. + +```json +"installBehavior": { + "preferences": { + "locale": [ "en-US", "fr-FR" ] + } +}, +``` + +### telemetry + +The `telemetry` settings control whether winget writes ETW events that may be sent to Microsoft on a default installation of Windows. + +See [details on telemetry](https://github.com/microsoft/winget-cli/blob/master/README.md#datatelemetry), and our [primary privacy statement](https://github.com/microsoft/winget-cli/blob/master/privacy.md). + +#### disable + +```json +"telemetry": { + "disable": true +}, +``` + +If set to true, the `telemetry.disable` setting will prevent any event from being written by the program. + +### network + +The `network` settings influence how winget uses the network to retrieve packages and metadata. + +#### downloader + +The `downloader` setting controls which code is used when downloading packages. The default is `default`, which may be any of the options based on our determination. + +`wininet` uses the [WinINet](/windows/win32/wininet/about-wininet) APIs, while `do` uses the [Delivery Optimization](https://support.microsoft.com/windows/delivery-optimization-in-windows-10-0656e53c-15f2-90de-a87a-a2172c94cf6d) service. + +```json +"network": { + "downloader": "do" +} +``` + +## Enabling experimental features + +To discover which experimental features are available, go to [https://aka.ms/winget-settings](https://aka.ms/winget-settings) where you can see the experimental features available to you. diff --git a/hub/package-manager/winget/show.md b/hub/package-manager/winget/show.md index bb8454ef6c..f8813ba739 100644 --- a/hub/package-manager/winget/show.md +++ b/hub/package-manager/winget/show.md @@ -8,8 +8,6 @@ ms.localizationpriority: medium # show command (winget) -[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] - The **show** command of the [winget](index.md) tool displays details for the specified application, including details on the source of the application as well as the metadata associated with the application. The **show** command only shows metadata that was submitted with the application. If the submitted application excludes some metadata, then the data will not be displayed. @@ -64,7 +62,7 @@ If a single application is detected, the following data will be displayed. | **AppMoniker** | AppMoniker of the application. | | **Description** | Description of the application. | | **License** | License of the application. | -| **LicenseUrl** | The URL to the license file of the applicatio. | +| **LicenseUrl** | The URL to the license file of the application. | | **Homepage** | Homepage of the application. | | **Tags** | The tags provided to assist in searching. | | **Command** | The commands supported by the application. | diff --git a/hub/package-manager/winget/source.md b/hub/package-manager/winget/source.md index c75ca8f4cb..050b3a2dcc 100644 --- a/hub/package-manager/winget/source.md +++ b/hub/package-manager/winget/source.md @@ -8,8 +8,6 @@ ms.localizationpriority: medium # source command (winget) -[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] - > [!NOTE] > The **source** command is currently for internal use only. Additional sources are not supported at this time. @@ -52,7 +50,7 @@ The **source** command supports the following options. | **-n,--name** | The name to identify the source by. | | **-a,--arg** | The URL or UNC of the source. | | **-t,--type** | The type of source. | -| **-?, --help** | Gets additional help on this command. | +| **-?, --help** | Gets additional help on this command. | ## add diff --git a/hub/package-manager/winget/uninstall.md b/hub/package-manager/winget/uninstall.md new file mode 100644 index 0000000000..efa1650687 --- /dev/null +++ b/hub/package-manager/winget/uninstall.md @@ -0,0 +1,77 @@ +--- +title: uninstall Command +description: uninstalls the specified application. +ms.date: 05/05/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# uninstall command (winget) + +The **uninstall** command of the [winget](index.md) tool uninstalls the specified application. + +The **uninstall** command requires that you specify the exact string to uninstall. If there is any ambiguity, you will be prompted to further filter the **uninstall** command to an exact application. + +## Usage + +`winget uninstall [[-q] \] [\]` + +![Image of uninstall command usage](images\uninstall.png) + +## Arguments + +The following arguments are available. + +| Argument | Description | +|-------------|-------------| +| **-q,--query** | The query used to search for an app. | +| **-?, --help** | Get additional help on this command. | + +## Options + +The options allow you to customize the uninstall experience to meet your needs. + +| Option | Description | +|-------------|-------------| +| **-m, --manifest** | Must be followed by the path to the manifest (YAML) file. You can use the manifest to run the uninstall experience from a [local YAML file](install.md#local-install). | +| **--id** | Limits the uninstall to the ID of the application. | +| **--name** | Limits the search to the name of the application. | +| **--moniker** | Limits the search to the moniker listed for the application. | +| **-v, --version** | Enables you to specify an exact version to uninstall. If not specified, latest will uninstall the highest versioned application. | +| **-s, --source** | Restricts the search to the source name provided. Must be followed by the source name. | +| **-e, --exact** | Uses the exact string in the query, including checking for case-sensitivity. It will not use the default behavior of a substring. | +| **-i, --interactive** | Runs the uninstaller in interactive mode. The default experience shows uninstaller progress. | +| **-h, --silent** | Runs the uninstaller in silent mode. This suppresses all UI. The default experience shows uninstaller progress. | +| **-o, --log** | Directs the logging to a log file. You must provide a path to a file that you have the write rights to. | + +After you have successfully identified the application intended to uninstall, winget will execute the uninstall command. In the example below, the **name** 'orca' and the **id** was passed in. + +![Image of uninstall command example](images\uninstall-execute.png) + +### Example queries + +The following example uninstalls a specific version of an application. + +```CMD +winget uninstall --name powertoys --version 0.15.2 +``` + +The following example uninstalls an application using its ID. + +```CMD +winget uninstall --id "{24559D0F-481C-F3BE-8DD0-D908923A38F8}" +``` + +## Multiple selections + +If the query provided to **winget** does not result in a single application to uninstall, then **winget** will display multiple results. You can then use additional filters to refine the search for a correct application. + +![Image of uninstall command multiple selections](images\uninstall-multiple.png) + +## Uninstalling apps not installed with Windows Package Manager + +As mentioned in [**list**](.\list.md), the **winget list** command will display more than just apps installed with the **winget**. Therefore you can use these commands to quickly and easily remove apps from your PC. + +In this example, **list** was used to find the application, and then the **id** was passed in as part of uninstall. + +![Image of uninstall command for apps not installed with Package Manager](images\uninstall-with-list.png) diff --git a/hub/package-manager/winget/upgrade.md b/hub/package-manager/winget/upgrade.md new file mode 100644 index 0000000000..13804ae112 --- /dev/null +++ b/hub/package-manager/winget/upgrade.md @@ -0,0 +1,83 @@ +--- +title: upgrade Command +description: upgrades the specified application. +ms.date: 05/05/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# upgrade command (winget) + +The **upgrade** command of the [winget](index.md) tool upgrades the specified application. Optionally, you may use the [**list**](.\list.md) command to identify the application you want to upgrade. + +The **upgrade** command requires that you specify the exact string to upgrade. If there is any ambiguity, you will be prompted to further filter the **upgrade** command to an exact application. + +## Usage + +`winget upgrade [[-q] \] [\]` + +![Image of upgrade command arguments](images\upgrade.png) + +## Arguments + +The following arguments are available. + +| Argument | Description | +|-------------|-------------| +| **-q,--query** | The query used to search for an app. | +| **-?, --help** | Get additional help on this command. | + +## Options + +The options allow you to customize the upgrade experience to meet your needs. + +| Option | Description | +|-------------|-------------| +| **-m, --manifest** | Must be followed by the path to the manifest (YAML) file. You can use the manifest to run the upgrade experience from a [local YAML file](install.md#local-install). | +| **--id** | Limits the upgrade to the ID of the application. | +| **--name** | Limits the search to the name of the application. | +| **--moniker** | Limits the search to the moniker listed for the application. | +| **-v, --version** | Enables you to specify an exact version to upgrade. If not specified, latest will upgrade the highest versioned application. | +| **-s, --source** | Restricts the search to the source name provided. Must be followed by the source name. | +| **-e, --exact** | Uses the exact string in the query, including checking for case-sensitivity. It will not use the default behavior of a substring. | +| **-i, --interactive** | Runs the installer in interactive mode. The default experience shows installer progress. | +| **-h, --silent** | Runs the installer in silent mode. This suppresses all UI. The default experience shows installer progress. | +| **-o, --log** | Directs the logging to a log file. You must provide a path to a file that you have the write rights to. | +| **--override** | A string that will be passed directly to the installer. | +| **-l, --location** | Location to upgrade to (if supported). | +| **--force** | When a hash mismatch is discovered will ignore the error and attempt to install the package. | +| **--all** | Updates all available packages to the latest application. | +### Example queries + +The following example upgrades a specific version of an application. + +```CMD +winget upgrade powertoys --version 0.15.2 +``` + +The following example upgrades an application from its ID. + +```CMD +winget upgrade --id Microsoft.PowerToys +``` + +The following example shows upgrading all apps + +```CMD +winget upgrade --all +``` + +## Using list and upgrade + +It is common to use the [**list**](.\list.md) command to identify apps in need of an update, and then to use **upgrade** to install the latest. + +In the example below you will see [**list**](.\list.md) identifies that an update is available for Microsoft.WindowsTerminalPreview, and then the user uses **upgrade** to update the application. + +![Animation demonstrating list and upgrade commands](images\upgrade.gif) + +## **upgrade** --all + +**upgrade --all** will identify all the applications with upgrades available. When you run **winget upgrade --all** the Windows Package Manager will look for all applications that have updates available and attempt to install the. + +> [!NOTE] +> Some applications do not provide a version. They are always latest. Because the Windows Package Manager cannot identify if there is a newer version of the app, an upgrade will not be possible. diff --git a/hub/package-manager/winget/validate.md b/hub/package-manager/winget/validate.md index bd28d5407c..cfdfa8631c 100644 --- a/hub/package-manager/winget/validate.md +++ b/hub/package-manager/winget/validate.md @@ -8,13 +8,11 @@ ms.localizationpriority: medium # validate command (winget) -[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] - -The **validate** command of the [winget](index.md) tool validates a [manifest file](../package/manifest.md) for submitting software to the **Microsoft Community Package Manifest Repository** on GitHub. The manifest must be a YAML file that follows the [specification](https://github.com/microsoft/winget-pkgs/YamlSpec.md). +The **validate** command of the [winget](index.md) tool validates a [manifest](../package/manifest.md) for submitting software to the **Microsoft Community Package Manifest Repository** on GitHub. The manifest must be a YAML file that follows the [specification](https://github.com/microsoft/winget-pkgs/YamlSpec.md). ## Usage -`winget validate [--manifest] \` +`winget validate [--manifest] \` ## Arguments diff --git a/hub/powertoys/administrator.md b/hub/powertoys/administrator.md index 5ed320b1cb..62227ce485 100644 --- a/hub/powertoys/administrator.md +++ b/hub/powertoys/administrator.md @@ -1,9 +1,10 @@ --- title: PowerToys administrator mode for Windows 10 description: For PowerToys to work with an app running in elevated admin mode, PowerToys must be run in administrator mode as well. -ms.date: 12/02/2020 +ms.date: 05/28/2021 ms.topic: article ms.localizationpriority: medium +no-loc: [PowerToys, Windows, FancyZones, Fancy, Zone, Zones] --- # PowerToys running with administrator elevated permissions diff --git a/hub/powertoys/color-picker.md b/hub/powertoys/color-picker.md index 9dc53788c9..9102acd22a 100644 --- a/hub/powertoys/color-picker.md +++ b/hub/powertoys/color-picker.md @@ -1,9 +1,10 @@ --- title: PowerToys Color Picker utility for Windows 10 description: A system-wide color picking utility for Windows 10 that enables you to pick colors from any currently running application and automatically copies the HEX or RGB values to your clipboard. -ms.date: 12/02/2020 +ms.date: 05/28/2021 ms.topic: article ms.localizationpriority: medium +no-loc: [PowerToys, Windows, FancyZones, Fancy, Zone, Zones] --- # Color Picker utility diff --git a/hub/powertoys/fancyzones.md b/hub/powertoys/fancyzones.md index 76925ccae9..24ffe157e5 100644 --- a/hub/powertoys/fancyzones.md +++ b/hub/powertoys/fancyzones.md @@ -1,9 +1,10 @@ --- title: PowerToys FancyZones utility for Windows 10 description: A window manager utility for arranging and snapping windows into efficient layouts -ms.date: 12/02/2020 +ms.date: 05/28/2021 ms.topic: article ms.localizationpriority: medium +no-loc: [PowerToys, Windows, FancyZones, Fancy, Zone, Zones] --- # FancyZones utility @@ -40,7 +41,7 @@ If multiple displays are in use, the editor will detect the available monitors a ### Space around zones -The **Show space around zones** toggle enables you to determine sort of border or margin will surround each FancyZone window. The **Space around zones** field enables you to set a custom value for how wide the border will be. +The **Show space around zones** toggle enables you to determine what sort of border or margin will surround each FancyZone window. The **Space around zones** field enables you to set a custom value for how wide the border will be. The **Distance to highlight adjacent zones** enables you to set a custom value for the amount of space between FancyZone windows until they snap together, or before both are highlighted enabling them to merge together. diff --git a/hub/powertoys/file-explorer.md b/hub/powertoys/file-explorer.md index d4b6a2282d..3273936938 100644 --- a/hub/powertoys/file-explorer.md +++ b/hub/powertoys/file-explorer.md @@ -1,9 +1,10 @@ --- title: PowerToys File Explorer utility for Windows 10 description: A File Explorer add on that enables Markdown and SVG previews -ms.date: 12/02/2020 +ms.date: 05/28/2021 ms.topic: article ms.localizationpriority: medium +no-loc: [PowerToys, Windows, File Explorer] --- # File Explorer add-ons utility diff --git a/hub/powertoys/image-resizer.md b/hub/powertoys/image-resizer.md index 9782f59bd9..be3b5316fa 100644 --- a/hub/powertoys/image-resizer.md +++ b/hub/powertoys/image-resizer.md @@ -1,9 +1,10 @@ --- title: PowerToys Image Resizer utility for Windows 10 description: A Windows shell extension for bulk image-resizing -ms.date: 12/02/2020 +ms.date: 05/28/2021 ms.topic: article ms.localizationpriority: medium +no-loc: [PowerToys, Windows, File Explorer, Image Resizer] --- # Image Resizer utility @@ -36,7 +37,6 @@ Add new preset sizes. Each size can be configured as Fill, Fit or Stretch. The d The width and height of the specified size may be swapped to match the orientation (portrait/landscape) of the current image. To always use the width and height as specified, un-check: **Ignore the orientation of pictures**. - ### Fallback encoding The fallback encoder is used when the file cannot be saved in it's original format. For example, the Windows Metafile (.wmf) image format has a decoder to read the image, but no encoder to write a new image. In this case, the image cannot be saved in it's original format. Image Resizer enables you to specify what format the fallback encoder will use: PNG, JPEG, TIFF, BMP, GIF, or WMPhoto settings. *This is not a file type conversion tool, but only works as a fallback for unsupported file formats.* diff --git a/hub/powertoys/index.md b/hub/powertoys/index.md index c6bcb8efce..8d4887bffd 100644 --- a/hub/powertoys/index.md +++ b/hub/powertoys/index.md @@ -4,6 +4,7 @@ description: Microsoft PowerToys is a set of utilities for customizing Windows 1 ms.date: 12/02/2020 ms.topic: overview ms.localizationpriority: medium +no-loc: [PowerRename, Windows, File Explorer, PowerToys, Run] --- # Microsoft PowerToys: Utilities to customize Windows 10 diff --git a/hub/powertoys/install.md b/hub/powertoys/install.md index 524394c119..a93d9cd2e3 100644 --- a/hub/powertoys/install.md +++ b/hub/powertoys/install.md @@ -1,9 +1,10 @@ --- title: Install PowerToys description: Install PowerToys, a set of utilities for customizing Windows 10, using an executable file or package manager (WinGet, Chocolatey, Scoop). -ms.date: 12/02/2020 +ms.date: 05/28/2021 ms.topic: quickstart ms.localizationpriority: medium +no-loc: [PowerToys, Windows, Chocolatey, Scoop] --- # Install PowerToys diff --git a/hub/powertoys/keyboard-manager.md b/hub/powertoys/keyboard-manager.md index 42d3c67c29..75d8febef6 100644 --- a/hub/powertoys/keyboard-manager.md +++ b/hub/powertoys/keyboard-manager.md @@ -1,9 +1,10 @@ --- title: PowerToys Keyboard Manager utility for Windows 10 description: A utility that enables users to redefine keys on the keyboard -ms.date: 05/02/2021 +ms.date: 05/28/2021 ms.topic: article ms.localizationpriority: medium +no-loc: [PowerToys, Windows, File Explorer, Keyboard Manager, Spotify] --- # Keyboard Manager utility diff --git a/hub/powertoys/powerrename.md b/hub/powertoys/powerrename.md index f19236013d..bc183227c6 100644 --- a/hub/powertoys/powerrename.md +++ b/hub/powertoys/powerrename.md @@ -4,6 +4,7 @@ description: A windows shell extension for bulk renaming of files ms.date: 12/02/2020 ms.topic: article ms.localizationpriority: medium +no-loc: [PowerRename, Pampalona, Windows, File Explorer, regex] --- # PowerRename utility diff --git a/hub/powertoys/run.md b/hub/powertoys/run.md index e8c65aac56..c053595a52 100644 --- a/hub/powertoys/run.md +++ b/hub/powertoys/run.md @@ -1,9 +1,10 @@ --- title: PowerToys Run utility for Windows 10 description: A quick launcher for power users that contains some additional features without sacrificing performance. -ms.date: 12/02/2020 +ms.date: 05/28/2021 ms.topic: article ms.localizationpriority: medium +no-loc: [PowerToys, Windows, File Explorer, PowerToys Run, WindowWalker] --- # PowerToys Run utility diff --git a/hub/powertoys/shortcut-guide.md b/hub/powertoys/shortcut-guide.md index 74b7d7eade..93cd5a9e17 100644 --- a/hub/powertoys/shortcut-guide.md +++ b/hub/powertoys/shortcut-guide.md @@ -1,9 +1,10 @@ --- title: PowerToys Shortcut Guide utility for Windows 10 description: A utility to display common keyboard shortcuts that use the Windows ⊞ key -ms.date: 12/02/2020 +ms.date: 05/28/2021 ms.topic: article ms.localizationpriority: medium +no-loc: [PowerToys, Windows, File Explorer] --- # Windows key shortcut guide diff --git a/hub/powertoys/video-conference-mute.md b/hub/powertoys/video-conference-mute.md index 700f831082..05a9e60661 100644 --- a/hub/powertoys/video-conference-mute.md +++ b/hub/powertoys/video-conference-mute.md @@ -1,9 +1,10 @@ --- title: PowerToys Video Conference Mute utility for Windows 10 description: A utility that allows users to quickly mute the microphone (audio) and turn off the camera (video) while on a conference call with a single keystroke, regardless of what application has focus on the computer. -ms.date: 12/07/2020 +ms.date: 05/28/2021 ms.topic: article ms.localizationpriority: medium +no-loc: [PowerToys, Windows, File Explorer, Video Conference Mute] --- # Video Conference Mute (Preview) @@ -66,5 +67,3 @@ You could also create an empty `PowerToysVideoConferenceVerbose.flag` in the sam ## Known issues To view all of the known issues currently open on the Video Conference Mute utility, see [PowerToys tracking issue #6246 on GitHub](https://github.com/microsoft/PowerToys/issues/6246). The PowerToys development team and contributor community is actively working toward resolving these issues and plans to keep the utility in pre-release until essential issues are resolved. - -![Screenshot of PowerToys video conference with 5 participants and device settings displayed](../images/pt-video-conference.png) diff --git a/hub/python/scripting.md b/hub/python/scripting.md index 3dca6c75d6..866c332d69 100644 --- a/hub/python/scripting.md +++ b/hub/python/scripting.md @@ -7,7 +7,7 @@ manager: jken ms.topic: article keywords: python, windows 10, microsoft, python system administration, python file automation, python scripts on windows, set up python on windows, python developer environment on windows, python dev environment on windows, python with powershell, python scripts for file system tasks ms.localizationpriority: medium -ms.date: 07/19/2019 +ms.date: 05/07/2021 --- # Get started using Python on Windows for scripting and automation @@ -29,7 +29,7 @@ To install Python using the Microsoft Store: 1. Go to your **Start** menu (lower left Windows icon), type "Microsoft Store", select the link to open the store. -2. Once the store is open, select **Search** from the upper-right menu and enter "Python". Open "Python 3.7" from the results under Apps. Select **Get**. +2. Once the store is open, select **Search** from the upper-right menu and enter "Python". Select which version of Python you would like to use from the results under Apps. We recommend using the most recent unless you have a reason not to (such as aligning with the version used on a pre-existing project that you plan to work on). Once you've determined which version you would like to install, select **Get**. 3. Once Python has completed the downloading and installation process, open Windows PowerShell using the **Start** menu (lower left Windows icon). Once PowerShell is open, enter `Python --version` to confirm that Python3 has been installed on your machine. diff --git a/landing/arm-docs/index.yml b/landing/arm-docs/index.yml index f194da5221..28a989defe 100644 --- a/landing/arm-docs/index.yml +++ b/landing/arm-docs/index.yml @@ -35,8 +35,6 @@ landingContent: url: https://youtu.be/OZtVBDeVqCE - text: Build 2018 Windows 10 on ARM for developers url: https://channel9.msdn.com/Events/Build/2018/BRK2438 - - text: Windows Community Standup with Kevin Gallo - url: https://channel9.msdn.com/Events/Ch9Live/Windows-Community-Standup/Kevin-Gallo-January-2018 # Card - title: Develop for Windows 10 on ARM @@ -45,14 +43,22 @@ landingContent: links: - text: Build ARM64 apps with the SDK url: https://blogs.windows.com/windowsdeveloper/2018/11/15/official-support-for-windows-10-on-arm-development/ - - text: UWP apps on ARM + - text: Build ARM64 Drivers with the WDK + url: /windows-hardware/drivers/develop/building-arm64-drivers + - text: Troubleshoot UWP apps on ARM url: /windows/uwp/porting/apps-on-arm-troubleshooting-arm32 - text: Debug on ARM url: /windows-hardware/drivers/debugger/debugging-arm64 - - text: Build ARM64 Drivers with the WDK - url: /windows-hardware/drivers/develop/building-arm64-drivers - - text: Develop x86 apps on ARM - url: /windows/uwp/porting/apps-on-arm-troubleshooting-x86 + - linkListType: reference + links: + - text: Developer resources at Qualcomm Developer Network + url: https://developer.qualcomm.com/hardware/windows-on-snapdragon/developer-resources + - text: Windows on ARM documentation at developer.arm.com + url: https://developer.arm.com/solutions/os/windows-on-arm + - linkListType: whats-new + links: + - text: Develop apps for ARM with Snapdragon Developer Kit + url: https://developer.qualcomm.com/hardware/windows-on-snapdragon/snapdragon-developer-kit # Card - title: Any feedback? diff --git a/windows-apps-src/audio-video-camera/code/MediaPlayer_RS1/cs/MainPage.xaml.cs b/windows-apps-src/audio-video-camera/code/MediaPlayer_RS1/cs/MainPage.xaml.cs index 9e121e2d4b..e3816b9f32 100644 --- a/windows-apps-src/audio-video-camera/code/MediaPlayer_RS1/cs/MainPage.xaml.cs +++ b/windows-apps-src/audio-video-camera/code/MediaPlayer_RS1/cs/MainPage.xaml.cs @@ -634,20 +634,9 @@ await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () => { mediaPlayer.CopyFrameToVideoSurface(inputBitmap); - - //Rect subtitleTargetRect = new Rect(0, 0, inputBitmap.Bounds.Width, inputBitmap.Bounds.Bottom * .1); Rect subtitleTargetRect = new Rect(0, 0, 100, 100); - mediaPlayer.RenderSubtitlesToSurface(inputBitmap);//, subtitleTargetRect); - - //var gaussianBlurEffect = new GaussianBlurEffect - //{ - // Source = inputBitmap, - // BlurAmount = 5f, - // Optimization = EffectOptimization.Speed - //}; - - //ds.DrawImage(gaussianBlurEffect); + mediaPlayer.RenderSubtitlesToSurface(inputBitmap); ds.DrawImage(inputBitmap); } diff --git a/windows-apps-src/audio-video-camera/code/MediaPlayer_RS1/cs/MediaPlayer_Win10.csproj b/windows-apps-src/audio-video-camera/code/MediaPlayer_RS1/cs/MediaPlayer_Win10.csproj index 89450e6ae6..23a41335ac 100644 --- a/windows-apps-src/audio-video-camera/code/MediaPlayer_RS1/cs/MediaPlayer_Win10.csproj +++ b/windows-apps-src/audio-video-camera/code/MediaPlayer_RS1/cs/MediaPlayer_Win10.csproj @@ -11,8 +11,8 @@ MediaPlayer_Win10 en-US UAP - 10.0.17133.0 - 10.0.17133.0 + 10.0.18362.0 + 10.0.18362.0 14 512 {A5A43C5B-DE2A-4C0C-9213-0A381AF9435A};{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC} diff --git a/windows-apps-src/cpp-and-winrt-apis/author-events.md b/windows-apps-src/cpp-and-winrt-apis/author-events.md index 5142549336..4df29ef705 100644 --- a/windows-apps-src/cpp-and-winrt-apis/author-events.md +++ b/windows-apps-src/cpp-and-winrt-apis/author-events.md @@ -374,6 +374,102 @@ logCallback(L"Hello, World!"); If you're porting from a C++/CX codebase where events and delegates are used internally within a project, then **winrt::delegate** will help you to replicate that pattern in C++/WinRT. +## Deferrable events + +A common pattern in the Windows Runtime is the deferrable event. An event handler *takes a deferral* by calling the event argument's **GetDeferral** method. Doing so indicates to the event source that post-event activities should be postponed until the deferral is completed. This allows an event handler to perform asynchronous actions in response to an event. + +The [**winrt::deferrable_event_args**](/uwp/cpp-ref-for-winrt/deferrable-event-args) struct template is a helper class for implementing (producing) the Windows Runtime deferral pattern. Here's an example. + +```cppwinrt +// Widget.idl +namespace Sample +{ + runtimeclass WidgetStartingEventArgs + { + Windows.Foundation.Deferral GetDeferral(); + Boolean Cancel; + }; + + runtimeclass Widget + { + event Windows.Foundation.TypedEventHandler< + Widget, WidgetStartingEventArgs> Starting; + }; +} + +// Widget.h +namespace winrt::Sample::implementation +{ + struct Widget : WidgetT + { + Widget() = default; + + event_token Starting(Windows::Foundation::TypedEventHandler< + Sample::Widget, Sample::WidgetStartingEventArgs> const& handler) + { + return m_starting.add(handler); + } + void Starting(event_token const& token) noexcept + { + m_starting.remove(token); + } + + private: + event> m_starting; + }; + + struct WidgetStartingEventArgs : WidgetStartingEventArgsT, + deferrable_event_args + // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + { + bool Cancel() const noexcept { return m_cancel; } + void Cancel(bool value) noexcept { m_cancel = value; } + bool m_cancel = false; + }; +} +``` + +Here's how the event recipient consumes the deferrable event pattern. + +```cppwinrt +// EventRecipient.h +widget.Starting([](auto sender, auto args) -> fire_and_forget +{ + auto deferral = args.GetDeferral(); + if (!co_await CanWidgetStartAsync(sender)) + { + // Do not allow the widget to start. + args.Cancel(true); + } + deferral.Complete(); +}); +``` + +As the implementor (producer) of the event source, you derive your event args class from [**winrt::deferrable_event_args**](/uwp/cpp-ref-for-winrt/deferrable-event-args). **deferrable_event_args\** implements **T::GetDeferral** for you. It also exposes a new helper method [**deferrable_event_args::wait_for_deferrals**](/uwp/cpp-ref-for-winrt/deferrable-event-args#deferrable_event_argswait_for_deferrals-function), which completes when all outstanding deferrals have completed (if no deferrals were taken, then it completes immediately). + +```cppwinrt +// Widget.h +IAsyncOperation TryStartWidget(Widget const& widget) +{ + auto args = make_self(); + // Raise the event to let people know that the widget is starting + // and give them a chance to prevent it. + m_starting(widget, *args); + // Wait for deferrals to complete. + co_await args->wait_for_deferrals(); + // Use the results. + bool started = false; + if (!args->Cancel()) + { + widget.InsertBattery(); + widget.FlipPowerSwitch(); + started = true; + } + co_return started; +} +``` + ## Design guidelines We recommend that you pass events, and not delegates, as function parameters. The **add** function of [**winrt::event**](/uwp/cpp-ref-for-winrt/event) is the one exception, because you must pass a delegate in that case. The reason for this guideline is because delegates can take different forms across different Windows Runtime languages (in terms of whether they support one client registration, or multiple). Events, with their multiple subscriber model, constitute a much more predictable and consistent option. diff --git a/windows-apps-src/cpp-and-winrt-apis/concurrency-2.md b/windows-apps-src/cpp-and-winrt-apis/concurrency-2.md index d81f72ab7d..a8953a5a3b 100644 --- a/windows-apps-src/cpp-and-winrt-apis/concurrency-2.md +++ b/windows-apps-src/cpp-and-winrt-apis/concurrency-2.md @@ -744,7 +744,7 @@ else ## Asynchronous timeouts made easy -C++/WinRT is invested heavily in C++ coroutines. Their effect on writing concurrency code is transformational. This section discusses cases where details of asynchrony are not important, and all you want is the result there and then. For that reason, C++/WinRT's implementation of the [**IAsyncAction**](/uwp/api/windows.foundation.iasyncaction) Windows Runtime asynchronous operation interface has a **get** function, similar to that provided by **std::future**. +C++/WinRT is invested heavily in C++ coroutines. Their effect on writing concurrency code is transformational. This section discusses cases where details of asynchrony are not important, and all you want is the result there and then. For that reason, C++/WinRT's implementation of the [**IAsyncAction**](/uwp/api/windows.foundation.iasyncaction) Windows Runtime asynchronous operation interface has a [**get**](/uwp/api/windows.foundation.iasyncaction#cwinrt-extension-functions) function, similar to that provided by **std::future**. ```cppwinrt using namespace winrt::Windows::Foundation; @@ -758,7 +758,7 @@ int main() The **get** function blocks indefinitely, while the async object completes. Async objects tend to be very short-lived, so this is often all you need. -But there are cases where that's not sufficient, and you need to abandon the wait after some time has elapsed. Writing that code has always been possible, thanks to the building blocks provided by the Windows Runtime. But now C++/WinRT makes it a lot easier by providing the **wait_for** function. It's also implementated on **IAsyncAction**, and again it's similar to that provided by **std::future**. +But there are cases where that's not sufficient, and you need to abandon the wait after some time has elapsed. Writing that code has always been possible, thanks to the building blocks provided by the Windows Runtime. But now C++/WinRT makes it a lot easier by providing the [**wait_for**](/uwp/api/windows.foundation.iasyncaction#cwinrt-extension-functions) function. It's also implementated on **IAsyncAction**, and again it's similar to that provided by **std::future**. ```cppwinrt using namespace std::chrono_literals; @@ -776,7 +776,10 @@ int main() > [!NOTE] > **wait_for** uses **std::chrono::duration** at the interface, but it is limited to some range smaller than what **std::chrono::duration** provides (roughly 49.7 days). -The **wait_for** in this next example waits for around five seconds and then it checks completion. If the comparison is favorable, then you know that the async object completed successfully, and you're done. If you're waiting for some result, then you can simply follow that with a call to the **get** function to retrieve the result. +The **wait_for** in this next example waits for around five seconds and then it checks completion. If the comparison is favorable, then you know that the async object completed successfully, and you're done. If you're waiting for some result, then you can simply follow that with a call to the [**GetResults**](/uwp/api/windows.foundation.iasyncoperation-1.getresults) method to retrieve the result. + +> [!NOTE] +> **wait_for** and **get** are mutually exclusive (you can't call both of them). They each count as a *waiter*, and Windows Runtime asynchronous actions/operations support only a single waiter. ```cppwinrt int main() @@ -785,18 +788,18 @@ int main() if (async.wait_for(5s) == AsyncStatus::Completed) { - printf("result %d\n", async.get()); + printf("result %d\n", async.GetResults()); } } ``` -Because the async object has completed by then, **get** returns the result immediately, without any further wait. As you can see, **wait_for** returns the state of the async object. So, you can use it for more fine-grained control, like this. +Because the async object has completed by then, the **GetResults** method returns the result immediately, without any further wait. As you can see, **wait_for** returns the state of the async object. So, you can use it for more fine-grained control, like this. ```cppwinrt switch (async.wait_for(5s)) { case AsyncStatus::Completed: - printf("result %d\n", async.get()); + printf("result %d\n", async.GetResults()); break; case AsyncStatus::Canceled: puts("canceled"); @@ -810,10 +813,24 @@ case AsyncStatus::Started: } ``` -- Remember that **AsyncStatus::Completed** means that the async object completed successfully, and you may call the **get** function to retrieve any result. -- **AsyncStatus::Canceled** means that the async object was canceled. A cancellation is typically requested by the caller, so it would be rare to handle this state. Typically, a cancelled async object is simply discarded. -- **AsyncStatus::Error** means that the async object has failed in some way. You can **get** to rethrow the exception if you wish. -- **AsyncStatus::Started** means that the async object is still running. The Windows Runtime async pattern doesn't allow multiple waits, nor waiters. That means that you can't call **wait_for** in a loop. If the wait has effectively timed-out, then you're left with a few choices. You can abandon the object, or you can poll its status before calling **get** to retrieve any result. But it's best just to discard the object at this point. +- Remember that **AsyncStatus::Completed** means that the async object completed successfully, and you may call the **GetResults** method to retrieve any result. +- **AsyncStatus::Canceled** means that the async object was canceled. A cancellation is typically requested by the caller, so it would be rare to handle this state. Typically, a cancelled async object is simply discarded. You can call the **GetResults** method to rethrow the cancellation exception if you wish. +- **AsyncStatus::Error** means that the async object has failed in some way. You can call the **GetResults** method to rethrow the exception if you wish. +- **AsyncStatus::Started** means that the async object is still running. The Windows Runtime async pattern doesn't allow multiple waits, nor waiters. That means that you can't call **wait_for** in a loop. If the wait has effectively timed-out, then you're left with a few choices. You can abandon the object, or you can poll its status before calling the **GetResults** method to retrieve any result. But it's best just to discard the object at this point. + +An alternative pattern is to check only for [**Started**](/uwp/api/windows.foundation.asyncstatus), and let GetResults deal with the other cases. + +```cppwinrt +if (async.wait_for(5s) == AsyncStatus::Started) +{ + puts("timed out"); +} +else +{ + // will throw appropriate exception if in cancelled or error state + auto results = async.GetResults(); +} +``` ## Returning an array asynchronously diff --git a/windows-apps-src/cpp-and-winrt-apis/get-started.md b/windows-apps-src/cpp-and-winrt-apis/get-started.md index cb8a95ff24..a073763a16 100644 --- a/windows-apps-src/cpp-and-winrt-apis/get-started.md +++ b/windows-apps-src/cpp-and-winrt-apis/get-started.md @@ -9,6 +9,9 @@ ms.localizationpriority: medium # Get started with C++/WinRT +> [!IMPORTANT] +> For info about setting up Visual Studio for C++/WinRT development—including installing and using the C++/WinRT Visual Studio Extension (VSIX) and the NuGet package (which together provide project template and build support)—see [Visual Studio support for C++/WinRT](./intro-to-using-cpp-with-winrt.md#visual-studio-support-for-cwinrt-xaml-the-vsix-extension-and-the-nuget-package). + To get you up to speed with using [C++/WinRT](./intro-to-using-cpp-with-winrt.md), this topic walks through a simple code example based on a new **Windows Console Application (C++/WinRT)** project. This topic also shows how to [add C++/WinRT support to a Windows Desktop application project](#modify-a-windows-desktop-application-project-to-add-cwinrt-support). > [!NOTE] @@ -16,9 +19,6 @@ To get you up to speed with using [C++/WinRT](./intro-to-using-cpp-with-winrt.md ## A C++/WinRT quick-start -> [!NOTE] -> For info about setting up Visual Studio for C++/WinRT development—including installing and using the C++/WinRT Visual Studio Extension (VSIX) and the NuGet package (which together provide project template and build support)—see [Visual Studio support for C++/WinRT](./intro-to-using-cpp-with-winrt.md#visual-studio-support-for-cwinrt-xaml-the-vsix-extension-and-the-nuget-package). - Create a new **Windows Console Application (C++/WinRT)** project. Edit `pch.h` and `main.cpp` to look like this. diff --git a/windows-apps-src/cpp-and-winrt-apis/use-csharp-component-from-cpp-winrt.md b/windows-apps-src/cpp-and-winrt-apis/use-csharp-component-from-cpp-winrt.md index 916267b42f..5226eb700b 100644 --- a/windows-apps-src/cpp-and-winrt-apis/use-csharp-component-from-cpp-winrt.md +++ b/windows-apps-src/cpp-and-winrt-apis/use-csharp-component-from-cpp-winrt.md @@ -207,11 +207,11 @@ In the Visual Studio Solution Explorer, open the shortcut menu for the the *CppT ... true - + true ``` ## Related topics * [Windows Runtime components with C# and Visual Basic](../winrt-components/creating-windows-runtime-components-in-csharp-and-visual-basic.md) -* [Windows Runtime components with C++/WinRT](../winrt-components/create-a-windows-runtime-component-in-cppwinrt.md) \ No newline at end of file +* [Windows Runtime components with C++/WinRT](../winrt-components/create-a-windows-runtime-component-in-cppwinrt.md) diff --git a/windows-apps-src/debug-test-perf/conditional-xaml.md b/windows-apps-src/debug-test-perf/conditional-xaml.md index 18a7d6dcbe..1014b1b546 100644 --- a/windows-apps-src/debug-test-perf/conditional-xaml.md +++ b/windows-apps-src/debug-test-perf/conditional-xaml.md @@ -54,7 +54,7 @@ We discuss these methods further in later sections of this article. In this example, you display, "Hello, Conditional XAML", as the content of a text block if the app runs on the Fall Creators Update or later, and default to no content if it's on a previous version. -First, define a custom namespace with the prefix 'contract5Present' and use the default XAML namespace (https://schemas.microsoft.com/winfx/2006/xaml/presentation) as the schema containing the [TextBlock.Text](/uwp/api/windows.ui.xaml.controls.textblock.Text) property. To make this a conditional namespace, add the ‘?’ delimiter after the schema. +First, define a custom namespace with the prefix 'contract5Present' and use the default XAML namespace (`https://schemas.microsoft.com/winfx/2006/xaml/presentation`) as the schema containing the [TextBlock.Text](/uwp/api/windows.ui.xaml.controls.textblock.Text) property. To make this a conditional namespace, add the ‘?’ delimiter after the schema. You then define a conditional that returns **true** on devices that are running the Fall Creators Update or later. You use the ApiInformation method **IsApiContractPresent** to check for the 5th version of the UniversalApiContract. Version 5 of the UniversalApiContract was released with the Fall Creators Update (SDK 16299). diff --git a/windows-apps-src/debug-test-perf/device-portal-api-core.md b/windows-apps-src/debug-test-perf/device-portal-api-core.md index 8d89d1d28b..767e2f0b50 100644 --- a/windows-apps-src/debug-test-perf/device-portal-api-core.md +++ b/windows-apps-src/debug-test-perf/device-portal-api-core.md @@ -62,7 +62,8 @@ This API has the following expected status codes. * HoloLens * IoT -
+> [!NOTE] +> Windows Mixed Reality runs on regular desktop, so it’s the same portal as Desktop. ### Install a related set @@ -494,6 +495,7 @@ This API has the following expected status codes. * IoT --- + ### Get a list of paired Bluetooth devices **Request** @@ -4457,4 +4459,4 @@ This API has the following expected status codes. * Windows Desktop * HoloLens * Xbox -* IoT \ No newline at end of file +* IoT diff --git a/windows-apps-src/debug-test-perf/device-portal.md b/windows-apps-src/debug-test-perf/device-portal.md index 98bb957de2..dce9e6e224 100644 --- a/windows-apps-src/debug-test-perf/device-portal.md +++ b/windows-apps-src/debug-test-perf/device-portal.md @@ -45,6 +45,9 @@ Phone | Enable inside Dev Mode | 80| 443 | http://127.0.0.1:10080 | [Device Port \* This is not always the case, as Device Portal on desktop claims ports in the ephemeral range (>50,000) to prevent collisions with existing port claims on the device. To learn more, see the [Registry-based configuration](device-portal-desktop.md#registry-based-configuration) section in [Windows Device Portal for Desktop](device-portal-desktop.md). +> [!NOTE] +> Windows Mixed Reality runs on regular desktop, so it’s the same portal as Desktop. + ## Features ### Toolbar and navigation diff --git a/windows-apps-src/design/input/keyboard-events.md b/windows-apps-src/design/input/keyboard-events.md index 0c0e142f58..b545eda058 100644 --- a/windows-apps-src/design/input/keyboard-events.md +++ b/windows-apps-src/design/input/keyboard-events.md @@ -27,7 +27,7 @@ The following keyboard events can occur for both hardware and touch keyboards. | [**KeyUp**](/uwp/api/windows.ui.xaml.uielement.keyup) | Occurs when a key is released. | > [!IMPORTANT] -> Some Windows Runtime controls handle input events internally. In these cases, it might appear that an input event doesn't occur because your event listener doesn't invoke the associated handler. Typically, this subset of keys is processed by the class handler to provide built in support of basic keyboard accessibility. For example, the [**Button**](/uwp/api/Windows.UI.Xaml.Controls.Button) class overrides the [**OnKeyDown**](/uwp/api/windows.ui.xaml.controls.control.onkeydown) events for both the Space key and the Enter key (as well as [**OnPointerPressed**](/uwp/api/windows.ui.xaml.controls.control.onpointerpressed)) and routes them to the [**Click**](/uwp/api/windows.ui.xaml.controls.primitives.buttonbase.click) event of the control. When a key press is handled by the control class, the [**KeyDown**](/uwp/api/windows.ui.xaml.uielement.keydown) and [**KeyUp**](/uwp/api/windows.ui.xaml.uielement.keyup) events are not raised. +> Some XAML controls handle input events internally. In these cases, it might appear that an input event doesn't occur because your event listener doesn't invoke the associated handler. Typically, this subset of keys is processed by the class handler to provide built in support of basic keyboard accessibility. For example, the [**Button**](/uwp/api/Windows.UI.Xaml.Controls.Button) class overrides the [**OnKeyDown**](/uwp/api/windows.ui.xaml.controls.control.onkeydown) events for both the Space key and the Enter key (as well as [**OnPointerPressed**](/uwp/api/windows.ui.xaml.controls.control.onpointerpressed)) and routes them to the [**Click**](/uwp/api/windows.ui.xaml.controls.primitives.buttonbase.click) event of the control. When a key press is handled by the control class, the [**KeyDown**](/uwp/api/windows.ui.xaml.uielement.keydown) and [**KeyUp**](/uwp/api/windows.ui.xaml.uielement.keyup) events are not raised. > This provides a built-in keyboard equivalent for invoking the button, similar to tapping it with a finger or clicking it with a mouse. Keys other than Space or Enter still fire [**KeyDown**](/uwp/api/windows.ui.xaml.uielement.keydown) and [**KeyUp**](/uwp/api/windows.ui.xaml.uielement.keyup) events. For more info about how class-based handling of events works (specifically, the "Input event handlers in controls" section), see [Events and routed events overview](../../xaml-platform/events-and-routed-events-overview.md). diff --git a/windows-apps-src/design/input/keyboard-interactions.md b/windows-apps-src/design/input/keyboard-interactions.md index a0f280fee6..d9ecc2bab1 100644 --- a/windows-apps-src/design/input/keyboard-interactions.md +++ b/windows-apps-src/design/input/keyboard-interactions.md @@ -201,6 +201,8 @@ The **Enter** key can perform a variety of common user interactions, depending o ![enter key](images/keyboard/enter-key.png) +#### Esc key + The Esc key lets a user cancel transient UI (along with any ongoing actions in that UI). Examples of this experience include: diff --git a/windows-apps-src/devices-sensors/aep-service-class-ids.md b/windows-apps-src/devices-sensors/aep-service-class-ids.md index f4a7685047..54b2c342b2 100644 --- a/windows-apps-src/devices-sensors/aep-service-class-ids.md +++ b/windows-apps-src/devices-sensors/aep-service-class-ids.md @@ -25,43 +25,43 @@ Bluetooth services fall under one of two protocols, either the Bluetooth protoco - Bluetooth protocol ID: {e0cbf06c-cd8b-4647-bb8a-263b43f0f974} - Bluetooth LE protocol ID: {bb7bb05e-5972-42b5-94fc-76eaa7084d49} -The Bluetooth protocol supports several services, all following the same basic format. The first four digits of the GUID vary based upon the service, but all Bluetooth GUIDs end with **0000-0000-1000-8000-00805F9B34FB**. For example, the RFCOMM service has the precursor of 0x0003, so the full ID would be **00030000-0000-1000-8000-00805F9B34FB**. The following table lists some common Bluetooth services. +The Bluetooth protocol supports several services, all following the same basic format. The first group of digits in the GUID vary based upon the service, but all Bluetooth GUIDs end with **-0000-1000-8000-00805F9B34FB**. For example, the RFCOMM service has the precursor of 0x0003, so the full ID would be **00000003-0000-1000-8000-00805F9B34FB**. The following table lists some common Bluetooth services. | Service name | GUID | |--------------------------------------|------------------------------------------| -| RFCOMM | **00030000-0000-1000-8000-00805F9B34FB** | -| GATT - Alert notification service | **18110000-0000-1000-8000-00805F9B34FB** | -| GATT - Automation IO | **18150000-0000-1000-8000-00805F9B34FB** | -| GATT - Battery service | **180F0000-0000-1000-8000-00805F9B34FB** | -| GATT - Blood pressure | **18100000-0000-1000-8000-00805F9B34FB** | +| RFCOMM | **00000003-0000-1000-8000-00805F9B34FB** | +| GATT - Alert notification service | **00001811-0000-1000-8000-00805F9B34FB** | +| GATT - Automation IO | **00001815-0000-1000-8000-00805F9B34FB** | +| GATT - Battery service | **0000180F-0000-1000-8000-00805F9B34FB** | +| GATT - Blood pressure | **00001810-0000-1000-8000-00805F9B34FB** | | GATT - Body composition | **181B0000-0000-1000-8000-00805F9B34FB** | -| GATT - Bond management | **181E0000-0000-1000-8000-00805F9B34FB** | -| GATT - Continuous glucose monitoring | **181F0000-0000-1000-8000-00805F9B34FB** | -| GATT - Current time service | **18050000-0000-1000-8000-00805F9B34FB** | -| GATT - Cycling power | **18180000-0000-1000-8000-00805F9B34FB** | -| GATT - Cycling speed and cadence | **18160000-0000-1000-8000-00805F9B34FB** | -| GATT - Device information | **180A0000-0000-1000-8000-00805F9B34FB** | -| GATT - Environmental sensing | **181A0000-0000-1000-8000-00805F9B34FB** | -| GATT - Generic access | **18000000-0000-1000-8000-00805F9B34FB** | -| GATT - Generic attribute | **18010000-0000-1000-8000-00805F9B34FB** | -| GATT - Glucose | **18080000-0000-1000-8000-00805F9B34FB** | -| GATT - Health thermometer | **18090000-0000-1000-8000-00805F9B34FB** | -| GATT - Heart rate | **180D0000-0000-1000-8000-00805F9B34FB** | -| GATT - Human interface device | **18120000-0000-1000-8000-00805F9B34FB** | -| GATT - Immediate alert | **18020000-0000-1000-8000-00805F9B34FB** | -| GATT - Indoor positioning | **18210000-0000-1000-8000-00805F9B34FB** | -| GATT - Internet protocol support | **18200000-0000-1000-8000-00805F9B34FB** | -| GATT - Link loss | **18030000-0000-1000-8000-00805F9B34FB** | -| GATT - Location and navigation | **18190000-0000-1000-8000-00805F9B34FB** | -| GATT - Next DST change service | **18070000-0000-1000-8000-00805F9B34FB** | -| GATT - Phone alert status service | **180E0000-0000-1000-8000-00805F9B34FB** | -| GATT - Pulse oximeter | **18220000-0000-1000-8000-00805F9B34FB** | -| GATT - Reference time update service | **18060000-0000-1000-8000-00805F9B34FB** | -| GATT - Running speed and cadence | **18140000-0000-1000-8000-00805F9B34FB** | -| GATT - Scan parameters | **18130000-0000-1000-8000-00805F9B34FB** | -| GATT - Tx power | **18040000-0000-1000-8000-00805F9B34FB** | -| GATT - User data | **181C0000-0000-1000-8000-00805F9B34FB** | -| GATT - Weight scale | **181D0000-0000-1000-8000-00805F9B34FB** | +| GATT - Bond management | **0000181E-0000-1000-8000-00805F9B34FB** | +| GATT - Continuous glucose monitoring | **0000181F-0000-1000-8000-00805F9B34FB** | +| GATT - Current time service | **00001805-0000-1000-8000-00805F9B34FB** | +| GATT - Cycling power | **00001818-0000-1000-8000-00805F9B34FB** | +| GATT - Cycling speed and cadence | **00001816-0000-1000-8000-00805F9B34FB** | +| GATT - Device information | **0000180A-0000-1000-8000-00805F9B34FB** | +| GATT - Environmental sensing | **0000181A-0000-1000-8000-00805F9B34FB** | +| GATT - Generic access | **00001800-0000-1000-8000-00805F9B34FB** | +| GATT - Generic attribute | **00001801-0000-1000-8000-00805F9B34FB** | +| GATT - Glucose | **00001808-0000-1000-8000-00805F9B34FB** | +| GATT - Health thermometer | **00001809-0000-1000-8000-00805F9B34FB** | +| GATT - Heart rate | **0000180D-0000-1000-8000-00805F9B34FB** | +| GATT - Human interface device | **00001812-0000-1000-8000-00805F9B34FB** | +| GATT - Immediate alert | **00001802-0000-1000-8000-00805F9B34FB** | +| GATT - Indoor positioning | **00001821-0000-1000-8000-00805F9B34FB** | +| GATT - Internet protocol support | **00001820-0000-1000-8000-00805F9B34FB** | +| GATT - Link loss | **00001803-0000-1000-8000-00805F9B34FB** | +| GATT - Location and navigation | **00001819-0000-1000-8000-00805F9B34FB** | +| GATT - Next DST change service | **00001807-0000-1000-8000-00805F9B34FB** | +| GATT - Phone alert status service | **0000180E-0000-1000-8000-00805F9B34FB** | +| GATT - Pulse oximeter | **00001822-0000-1000-8000-00805F9B34FB** | +| GATT - Reference time update service | **00001806-0000-1000-8000-00805F9B34FB** | +| GATT - Running speed and cadence | **00001814-0000-1000-8000-00805F9B34FB** | +| GATT - Scan parameters | **00001813-0000-1000-8000-00805F9B34FB** | +| GATT - Tx power | **00001804-0000-1000-8000-00805F9B34FB** | +| GATT - User data | **0000181C-0000-1000-8000-00805F9B34FB** | +| GATT - Weight scale | **0000181D-0000-1000-8000-00805F9B34FB** | For a more complete listing of available Bluetooth services, see the [GATT Services specification](https://www.bluetooth.com/specifications/gatt/services/). You can also use the [**GattServiceUuids**](/uwp/api/Windows.Devices.Bluetooth.GenericAttributeProfile.GattServiceUuids) API to get some common GATT services. diff --git a/windows-apps-src/gaming/e2e.md b/windows-apps-src/gaming/e2e.md index 9e8966749b..c70f6956c1 100644 --- a/windows-apps-src/gaming/e2e.md +++ b/windows-apps-src/gaming/e2e.md @@ -153,7 +153,7 @@ The Xbox Tools and Middleware Program licenses Xbox development kits to professi Contact the tools and middleware program - + xboxtlsm@microsoft.com diff --git a/windows-apps-src/porting/apps-on-arm-troubleshooting-x86.md b/windows-apps-src/porting/apps-on-arm-troubleshooting-x86.md index ee9edb6cae..66978d875a 100644 --- a/windows-apps-src/porting/apps-on-arm-troubleshooting-x86.md +++ b/windows-apps-src/porting/apps-on-arm-troubleshooting-x86.md @@ -8,7 +8,7 @@ ms.localizationpriority: medium --- # Troubleshooting x86 desktop apps >[!IMPORTANT] -> The ARM64 SDK is now available as part of Visual Studio 15.8 Preview 1. We recommend that you recompile your app to ARM64 so that your app runs at full native speed. For more info, see the [Early preview of Visual Studio support for Windows 10 on ARM development](https://blogs.windows.com/buildingapps/2018/05/08/visual-studio-support-for-windows-10-on-arm-development/) blog post. +> The ARM64 SDK is now available as part of Visual Studio 2017 15.9 or Visual Studio 2019. We recommend that you recompile your app to ARM64 so that your app runs at full native speed. For more info, see the [Visual Studio support for Windows 10 on ARM development](https://blogs.windows.com/windowsdeveloper/2018/11/15/official-support-for-windows-10-on-arm-development/) blog post. If an x86 desktop app doesn't work the way it does on an x86 machine, here's some guidance to help you troubleshoot. @@ -45,4 +45,4 @@ The Windows Hypervisor platform is not supported on the Qualcomm Snapdragon 835 ## Dynamic Code Generation X86 desktop apps are emulated on ARM64 by the system generating ARM64 instructions at runtime. This means if an x86 desktop app prevents dynamic code generation or modification in its process, that app cannot be supported to run as x86 on ARM64. -This is a security mitigation some apps enable on their process using [SetProcessMitigationPolicy](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-setprocessmitigationpolicy) API with the `ProcessDynamicCodePolicy` flag. To run successfully on ARM64 as an x86 process, this mitigation policy will have to be disabled. \ No newline at end of file +This is a security mitigation some apps enable on their process using [SetProcessMitigationPolicy](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-setprocessmitigationpolicy) API with the `ProcessDynamicCodePolicy` flag. To run successfully on ARM64 as an x86 process, this mitigation policy will have to be disabled. diff --git a/windows-apps-src/porting/apps-on-arm.md b/windows-apps-src/porting/apps-on-arm.md index 09c053990f..843593cd9d 100644 --- a/windows-apps-src/porting/apps-on-arm.md +++ b/windows-apps-src/porting/apps-on-arm.md @@ -8,7 +8,7 @@ ms.localizationpriority: medium --- # Windows 10 on ARM -Originally Windows 10 (as distinguished from Windows 10 Mobile) could run only on PCs that were powered by x86 and x64 processors. Now, Windows 10 desktop can run on machines that are powered by ARM64 processors with the Fall Creators Update or newer. The power-saving nature of the ARM CPU architecture allows these PCs to have all-day battery life and support for mobile data networks. These PCs will provide great application compatibility and allow you to run your existing x86 win32 applications unmodified. For more information or a demo, look at the [Channel 9 video for the Always Connected PC](https://channel9.msdn.com/Events/Build/2017/P4171). +Windows 10 desktop can run on machines that are powered by ARM64 processors. The power-saving nature of the ARM CPU architecture allows these PCs to have all-day battery life and integrated support for mobile data networks. These PCs also provide great application compatibility and allow you to run your existing x86 win32 applications unmodified. For more information or a demo, look at the [Build video for Windows 10 on ARM](https://channel9.msdn.com/Events/Build/2018/BRK2438). We use the term *ARM* here as a shorthand for PCs that run the desktop version of Windows 10 on ARM64 (also commonly called *AArch64*) processors. We use the term *ARM32* here as a shorthand for the 32-bit ARM architecture (commonly called *ARM* in other documentation). @@ -28,7 +28,7 @@ Windows 10 on ARM runs all x86, ARM32, and ARM64 [UWP apps](../get-started/unive > Windows 10 on ARM supports x86, ARM32, and ARM64 UWP apps from Store on ARM64 devices. When a user downloads your UWP app on an ARM64 device, the OS will automatically install the optimal version of your app that is available. If you submit x86, ARM32, and ARM64 versions of your app to the Store, the OS will automatically install the ARM64 version of your app. If you only submit x86 and ARM32 versions of your app, the OS will install the ARM32 version. If you only submit the x86 version of your app, the OS will install that version and run it under emulation. For more information about architectures, see [App package architectures](/windows/msix/package/device-architecture). ### Win32 apps -In addition to UWP apps, Windows 10 on ARM can also run your x86 Win32 apps unmodified, with good performance and a seamless user experience, just like any PC. These x86 Win32 apps don’t have to recompiled for ARM and don’t even realize they are running on an ARM processor. +In addition to UWP apps, Windows 10 on ARM can also run your x86 Win32 apps unmodified, with good performance and a seamless user experience, just like any PC. These x86 Win32 apps don’t have to be recompiled for ARM and don’t even realize they are running on an ARM processor. ### x86-64 apps Initial support for x86-64 applications was added in build 21277, and is currently being developed further. If an app's x64 Win32 version doesn't work, the vast majority of apps do also have x86 versions available. When given the choice of app architecture, just choose the 32-bit x86 version to run the app's 32-bit version on a Windows 10 on ARM PC.