Merge pull request #4139 from MicrosoftDocs/alvinashcraft/main-power-mgmt-add-csharp-code

Add c# examples to Power Mgmt topic in AppLifecycle docs

Author: alvinashcraft

hub/apps/windows-app-sdk/applifecycle/applifecycle-instancing.md

@@ -2,7 +2,7 @@
 description: Describes how to use app instancing features with the app lifecycle API (Windows App SDK).
 title: App instancing with the app lifecycle API (Windows App SDK)
 ms.topic: article
-ms.date: 11/16/2021
+ms.date: 03/07/2024
 keywords: AppLifecycle, Windows, ApplicationModel, instancing, single instance, multi instance
 ms.localizationpriority: medium
 ---
@@ -13,15 +13,16 @@ An app's instancing model determines whether multiple instances of your app's pr
 
 ## Prerequisites
 
-
-
 To use the app lifecycle API in the Windows App SDK:
 
 1. Download and install the latest release of the Windows App SDK. For more information, see [Install tools for the Windows App SDK](../set-up-your-development-environment.md).
 2. Follow the instructions to [Create your first WinUI 3 project](../../winui/winui3/create-your-first-winui3-app.md) or to [use the Windows App SDK in an existing project](../use-windows-app-sdk-in-existing-project.md).
 
 ## Single-instance apps
 
+> [!NOTE]
+> For an example of how to implement single instancing in a WinUI 3 app with C#, see [Making the app single-instanced](https://blogs.windows.com/windowsdeveloper/2022/01/28/making-the-app-single-instanced-part-3/) on the Windows developer blog.
+
 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.
@@ -407,7 +408,7 @@ void CALLBACK OnFileClosed(HWND hDlg, UINT message, WPARAM wParam, LPARAM lParam
 }
 ```
 
-> [!Warning]
+> [!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](/windows/windows-app-sdk/api/winrt/microsoft.windows.applifecycle.appinstance.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

hub/apps/windows-app-sdk/applifecycle/applifecycle-power.md

@@ -2,7 +2,7 @@
 description: Describes how to use power management and notification features with the app lifecycle API (Windows App SDK).
 title: Power management with the app lifecycle API (Windows App SDK)
 ms.topic: article
-ms.date: 11/16/2021
+ms.date: 03/07/2024
 keywords: AppLifecycle, Windows, ApplicationModel, power, battery,
 ms.localizationpriority: medium
 ---
@@ -15,8 +15,6 @@ The power management APIs use a callback-based model similar to the existing [Po
 
 ## Prerequisites
 
-
-
 To use the app lifecycle API in the Windows App SDK:
 
 1. Download and install the latest release of the Windows App SDK. For more information, see [Install tools for the Windows App SDK](../set-up-your-development-environment.md).
@@ -26,6 +24,8 @@ To use the app lifecycle API in the Windows App SDK:
 
 The following example demonstrates how to subscribe and respond to [PowerManager](/windows/windows-app-sdk/api/winrt/microsoft.windows.system.power.powermanager) events. This code subscribes to the [BatteryStatusChanged](/windows/windows-app-sdk/api/winrt/microsoft.windows.system.power.powermanager.batterystatuschanged) event during startup. The app then responds to changes by checking the current power level and adjusting its resource usage appropriately. For example, if the battery discharges at a low power state, the app might defer any non-critical background work.
 
+#### [C++/WinRT](#tab/cpp)
+
 > [!NOTE]
 > Apps can register and unregister for these events at any time, but most apps will want to set callbacks in `WinMain` that persist as long as the app continues to run.
 
@@ -96,10 +96,68 @@ void OnPowerSupplyStatusChanged()
 }
 ```
 
+#### [C#](#tab/csharp)
+
+> [!NOTE]
+> Apps can register and unregister for these events at any time, but most apps will want to set callbacks that persist as long as the app continues to run.
+
+```csharp
+private bool bWorkInProgress;
+private EventRegistrationToken batteryToken;
+private EventRegistrationToken powerToken;
+private EventRegistrationToken powerSourceToken;
+private EventRegistrationToken chargeToken;
+private EventRegistrationToken dischargeToken;
+
+private void RegisterPowerManagerCallbacks()
+{
+    batteryToken = PowerManager.BatteryStatusChanged += (s, e) => OnBatteryStatusChanged();
+    powerToken = PowerManager.PowerSupplyStatusChanged += (s, e) => OnPowerSupplyStatusChanged();
+    powerSourceToken = PowerManager.PowerSourceKindChanged += (s, e) => OnPowerSourceKindChanged();
+    chargeToken = PowerManager.RemainingChargePercentChanged += (s, e) => OnRemainingChargePercentChanged();
+    dischargeToken = PowerManager.RemainingDischargeTimeChanged += (s, e) => OnRemainingDischargeTimeChanged();
+
+    if (batteryToken != null && powerToken != null && powerSourceToken != null && chargeToken != null && dischargeToken != null)
+    {
+        OutputMessage("Successfully registered for state notifications");
+    }
+    else
+    {
+        OutputMessage("Failed to register for state notifications");
+    }
+}
+
+private void OnBatteryStatusChanged()
+{
+    BatteryStatus batteryStatus = PowerManager.BatteryStatus;
+    int remainingCharge = PowerManager.RemainingChargePercent;
+    string status = batteryStatus switch
+    {
+        BatteryStatus.Charging => "Charging",
+        BatteryStatus.Discharging => "Discharging",
+        BatteryStatus.Idle => "Idle",
+        BatteryStatus.NotPresent => "NotPresent",
+        _ => "Unknown"
+    };
+
+    OutputFormattedMessage($"Battery status changed: {status}, {remainingCharge}% remaining");
+    DetermineWorkloads();
+}
+
+private void OnPowerSupplyStatusChanged()
+{
+    //...etc
+}
+```
+
+---
+
 ## Configure app logic based on multiple status values
 
 [PowerManager](/windows/windows-app-sdk/api/winrt/microsoft.windows.system.power.powermanager) events are relatively low-level, and in some scenarios, a single event handler being called might not provide enough information for the app to decide how to behave. In this example, the [PowerSupplyStatusChanged](/windows/windows-app-sdk/api/winrt/microsoft.windows.system.power.powermanager.powersupplystatuschanged) event could be called when the device is disconnected from power. In that case, the app must check the current battery status before deciding how to proceed.
 
+#### [C++/WinRT](#tab/cpp)
+
 ```cpp
 void DetermineWorkloads()
 {
@@ -128,10 +186,44 @@ void DetermineWorkloads()
 }
 ```
 
+#### [C#](#tab/csharp)
+
+```csharp
+private void DetermineWorkloads()
+{
+    BatteryStatus batteryStatus = PowerManager.BatteryStatus();
+    int remainingCharge = PowerManager.RemainingChargePercent();
+    PowerSupplyStatus powerStatus = PowerManager.PowerSupplyStatus();
+    PowerSourceKind powerSource = PowerManager.PowerSourceKind();
+
+    if ((powerSource == PowerSourceKind.DC 
+        && batteryStatus == BatteryStatus.Discharging 
+        && remainingCharge < 25)
+        || (powerSource == PowerSourceKind.AC
+        && powerStatus == PowerSupplyStatus.Inadequate))
+    {
+        // The device is not in a good battery/power state, 
+        // so we should pause any non-critical work.
+        PauseNonCriticalWork();
+    }
+    else if ((batteryStatus != BatteryStatus.Discharging && remainingCharge > 75)
+        && powerStatus != PowerSupplyStatus.Inadequate)
+    {
+        // The device is in good battery/power state,
+        // so let's kick of some high-power work.
+        StartPowerIntensiveWork();
+    }
+}
+```
+
+---
+
 ## Check screen status
 
 The [PowerManager](/windows/windows-app-sdk/api/winrt/microsoft.windows.system.power.powermanager) class offers information about other device states relevant to an app's power usage. For example, apps can disable graphics processing when the device's display is turned off.
 
+#### [C++/WinRT](#tab/cpp)
+
 ```cpp
 void OnDisplayStatusChanged()
 {
@@ -165,10 +257,39 @@ void OnDisplayStatusChanged()
 }
 ```
 
+#### [C#](#tab/csharp)
+
+```csharp
+private void OnDisplayStatusChanged()
+{
+    DisplayStatus displayStatus = PowerManager.DisplayStatus;
+    string status = displayStatus switch
+    {
+        DisplayStatus.Dimmed => "Dimmed",
+        DisplayStatus.Off => "Off",
+        DisplayStatus.On => "On",
+        _ => "Unknown"
+    };
+
+    OutputFormattedMessage($"Display status changed: {status}");
+    if (displayStatus == DisplayStatus.Off)
+    {
+        // The screen is off, let's stop rendering foreground graphics,
+        // and instead kick off some background work now.
+        StopUpdatingGraphics();
+        StartDoingBackgroundWork();
+    }
+}
+```
+
+---
+
 ## Unsubscribe from events
 
 Apps can register and deregister for notifications during their lifecycle. Use your language's preferred event registration management system if your app doesn't need to receive power status notifications during its entire lifecycle.
 
+#### [C++/WinRT](#tab/cpp)
+
 ```cpp
 void UnregisterPowerManagerCallbacks()
 {
@@ -181,6 +302,22 @@ void UnregisterPowerManagerCallbacks()
 }
 ```
 
+#### [C#](#tab/csharp)
+
+```csharp
+private void UnregisterPowerManagerCallbacks()
+{
+    OutputMessage("Unregistering state notifications");
+    PowerManager.BatteryStatusChanged -= batteryToken;
+    PowerManager.PowerSupplyStatusChanged -= powerToken;
+    PowerManager.PowerSourceKindChanged -= powerSourceToken;
+    PowerManager.RemainingChargePercentChanged -= chargeToken;
+    PowerManager.RemainingDischargeTimeChanged -= dischargeToken;
+}
+```
+
+---
+
 ## Related topics
 
 * [Windows.System.Power.PowerManager](/uwp/api/Windows.System.Power.PowerManager)

hub/apps/windows-app-sdk/applifecycle/applifecycle-rich-activation.md

@@ -2,7 +2,7 @@
 description: Describes how to use rich activation features with the app lifecycle API in unpackaged apps (Windows App SDK).
 title: Rich activation with the app lifecycle API (Windows App SDK)
 ms.topic: article
-ms.date: 11/16/2021
+ms.date: 03/07/2024
 keywords: AppLifecycle, Windows, activation, activation contracts, rich activation, win32, win32 activation, unpackaged app, unpackaged app activation
 ms.localizationpriority: medium
 ---
@@ -18,12 +18,9 @@ Supporting rich activations requires two steps:
 
 ## Prerequisites
 
-> [!IMPORTANT]
-> The app lifecycle API is currently supported in the [preview release channel](../preview-channel.md) and [experimental release channel](../experimental-channel.md) of the Windows App SDK. This feature is not currently supported for use by apps in production environments.
-
 To use the app lifecycle API in the Windows App SDK:
 
-1. Download and install the latest preview or experimental release of the Windows App SDK. For more information, see [Install tools for the Windows App SDK](../set-up-your-development-environment.md).
+1. Download and install the latest release of the Windows App SDK. For more information, see [Install tools for the Windows App SDK](../set-up-your-development-environment.md).
 2. Follow the instructions to [Create your first WinUI 3 project](../../winui/winui3/create-your-first-winui3-app.md) or to [use the Windows App SDK in an existing project](../use-windows-app-sdk-in-existing-project.md).
 
 ## Activation details for unpackaged apps
@@ -32,10 +29,10 @@ The current version of the Windows App SDK supports the four most common activat
 
 | Activation kind | Description                                                  |
 | --------------- | ------------------------------------------------------------ |
-| `Launch`          | Activate the app from the command line, when the user double-clicks the app's icon, or programmatically via [ShellExecute](/windows/win32/api/shellapi/nf-shellapi-shellexecuteexw) or [CreateProcess](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw). |
-| `File`            | Activate an app that has registered for a file type when a file of the type is opened via [ShellExecute](/windows/win32/api/shellapi/nf-shellapi-shellexecuteexw), [Launcher.LaunchFileAsync](/uwp/api/windows.system.launcher.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](/windows/win32/api/shellapi/nf-shellapi-shellexecuteexw), [Launcher.LaunchUriAsync](/uwp/api/windows.system.launcher.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. |
+| `Launch` | Activate the app from the command line, when the user double-clicks the app's icon, or programmatically via [ShellExecute](/windows/win32/api/shellapi/nf-shellapi-shellexecuteexw) or [CreateProcess](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw). |
+| `File` | Activate an app that has registered for a file type when a file of the type is opened via [ShellExecute](/windows/win32/api/shellapi/nf-shellapi-shellexecuteexw), [Launcher.LaunchFileAsync](/uwp/api/windows.system.launcher.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](/windows/win32/api/shellapi/nf-shellapi-shellexecuteexw), [Launcher.LaunchUriAsync](/uwp/api/windows.system.launcher.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, C++ 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), because arguments will not be automatically passed to them.