Merged PR 21313: Add more context around PFN property being optional or required

Add more context around the TargetApplicationPackageFamilyName property being optional or required

Author: alvinashcraft

windows.system/launcher_launchuriasync_569877360.md

@@ -11,25 +11,35 @@ public Windows.Foundation.IAsyncOperation<bool> LaunchUriAsync(Windows.Foundatio
 # Windows.System.Launcher.LaunchUriAsync
 
 ## -description
+
 Starts the default app associated with the URI scheme name for the specified URI, using the specified options and input data.
 
 ## -parameters
+
 ### -param uri
+
 The URI.
 
 ### -param options
+
 The launch options for the app.
 
+> [!IMPORTANT]
+> The [TargetApplicationPackageFamilyName](launcheroptions_targetapplicationpackagefamilyname.md) property of the *options* parameter, while sometimes optional, is required for this overload of the **LaunchUriAsync** method.
+
 ### -param inputData
+
 The input data for the app.
 
 > [!IMPORTANT]
 > The amount of data that can be transferred must not exceed 100 KB.
 
 ## -returns
+
 Returns **true** if the default app for the URI scheme was launched; **false** otherwise.
 
 ## -remarks
+
 Unless you are calling this API from a Windows desktop application, this API must be called from within an ASTA thread (also known as the UI thread).
 
 This API may also be called from a Windows desktop application.
@@ -39,4 +49,5 @@ This API launches the default app for the scheme whether it be a Universal Windo
 ## -examples
 
 ## -see-also
+
 [LaunchUriAsync(Uri)](launcher_launchuriasync_53691900.md), [LaunchUriAsync(Uri, LauncherOptions)](launcher_launchuriasync_68890748.md)

windows.system/launcheroptions.md

@@ -17,6 +17,15 @@ In a desktop app, before using an instance of this class in a way that displays
 
 ## -remarks
 
+In some cases, when you call [Launcher](launcher.md) static methods to launch an app associated with a file type or URI protocol, you must specify exactly which app you want to be launched by passing a **LauncherOptions** parameter with the [TargetApplicationPackageFamilyName](launcheroptions_targetapplicationpackagefamilyname.md) property set to the package family name for the app package containing that app.
+
+Two such cases are as follows:
+
+1. You want to launch an app with a URI and pass extra input data to the launched app, using [Launcher.LaunchUriAsync(Uri, LauncherOptions, ValueSet)](launcher_launchuriasync_569877360.md).
+1. You want to launch an app with a URI and wait for the app to send output data back to your app, using any overload of [Launcher.LaunchUriForResultsAsync](launcher_launchuriforresultsasync_148601521.md).
+
+In these cases, both the calling app and launched app need to agree on how to interpret the extra data passed from one app to the other. The calling app cannot launch any app that happens to be the default for that URI protocol. In other cases, the **TargetApplicationPackageFamilyName** property is optional.
+
 ### Version history
 
 | Windows version | SDK version | Value added |

windows.system/launcheroptions_targetapplicationpackagefamilyname.md

@@ -10,16 +10,28 @@ public string TargetApplicationPackageFamilyName { get;  set; }
 # Windows.System.LauncherOptions.TargetApplicationPackageFamilyName
 
 ## -description
-The package family name of the target package that should be used to launch a file or URI. This property is optional.
+
+The package family name of the target package that should be used to launch a file or URI. This property is optional in some cases. See **Remarks**.
 
 ## -property-value
-The package family name of the target package that should be used to launch a file or URI. This property is optional.
+
+The package family name of the target package that should be used to launch a file or URI. This property is optional in some cases. See **Remarks**.
 
 ## -remarks
+
 An application's PackageFamilyName can be obtained via the [PackageID class](/en-us/uwp/api/Windows.ApplicationModel.PackageId#Windows_ApplicationModel_PackageId_FamilyName)
 
 A PackageFamilyName can vary depending on how an application has been published, but it will generally follow the form of `[package name]_[publisher_id]`. For example, an unpublished app has a family name similar to `c04742a8-1c87-41c1-b951-cc6e6f353400_g3nsfcgfwzqga`
 
+In some cases, when you call [Launcher](launcher.md) static methods to launch an app associated with a file type or URI protocol, you must specify exactly which app you want to be launched by passing a [LauncherOptions](launcheroptions.md) parameter with the **TargetApplicationPackageFamilyName** property set to the package family name for the app package containing that app.
+
+Two such cases are as follows:
+
+1. You want to launch an app with a URI and pass extra input data to the launched app, using [Launcher.LaunchUriAsync(Uri, LauncherOptions, ValueSet)](launcher_launchuriasync_569877360.md).
+1. You want to launch an app with a URI and wait for the app to send output data back to your app, using any overload of [Launcher.LaunchUriForResultsAsync](launcher_launchuriforresultsasync_148601521.md).
+
+In these cases, both the calling app and launched app need to agree on how to interpret the extra data passed from one app to the other. The calling app cannot launch any app that happens to be the default for that URI protocol.
+
 ## -examples
 
 ## -see-also