[release/9.0.1xx] [msbuild] Compute DOTNET_DiagnosticPorts using MSBuild properties. (#23629)

If you run `dotnet-dsrouter ios`, it says:

    Start an application on ios device with ONE of the following environment variables set:
    [Default Tracing]
    DOTNET_DiagnosticPorts=127.0.0.1:9000,nosuspend,listen
    [Startup Tracing]
    DOTNET_DiagnosticPorts=127.0.0.1:9000,suspend,listen

Setting `$DOTNET_DiagnosticPorts` is non-trivial, so as a step to simplify this, we are adding multiple MSBuild properties to configure this value.

This would allow the log message to say:

    Build and run an iOS application such as:
    [Default Tracing]
    dotnet run -c Release -p:ios-arm64 -p:DiagnosticAddress=127.0.0.1 -p:DiagnosticPort=9000 -p:DiagnosticSuspend=false -p:DiagnosticListenMode=listen
    [Startup Tracing]
    dotnet run -c Release -p:ios-arm64 -p:DiagnosticAddress=127.0.0.1 -p:DiagnosticPort=9000 -p:DiagnosticSuspend=true -p:DiagnosticListenMode=listen

Since these are all default values, it can be simplified to:

    Build and run an iOS application such as:
    [Default Tracing]
    dotnet run -p:ios-arm64 -c Release -p:EnableDiagnostics=true
    [Startup Tracing]
    dotnet run -p:ios-arm64 -c Release -p:EnableDiagnostics=true

Setting any of the new properties also implicitly means that `$(EnableDiagnostics)` is set to `true` (first example), or alternatively `$(EnableDiagnostics)` can be set to true to get the default value for all the new properties (second example).

Ref: dotnet/android#10351

Backport of #23429.

---------

Co-authored-by: Jonathan Peppers <[email protected]>

Author: rolfbjarne

docs/building-apps/build-properties.md

@@ -279,6 +279,80 @@ The output path to use when device-specific builds are enabled.
 
 Applicable to all platforms that support device-specific builds (currently iOS and tvOS).
 
+## DiagnosticAddress
+
+The IP address where `dotnet-dsrouter` is executing. This is typcially
+`127.0.0.1` when profiling on the simulator, and the IP address of the machine
+where `dotnet-dsrouter` when profiling on a device.
+
+This is the IP address component of [DiagnosticConfiguration](#diagnosticconfiguration)`.
+
+Implicitly sets [EnableDiagnostics](#enablediagnostics) to `true`.
+
+Defaults to `127.0.0.1`.
+
+## DiagnosticConfiguration
+
+A value provided by `dotnet-dsrouter` for `DOTNET_DiagnosticPorts` such as:
+
+* `127.0.0.1:9000,suspend,connect`
+* `127.0.0.1:9000,nosuspend,connect`
+
+Note that the `,` character will need to be escaped with `%2c` if
+passed in command-line to `dotnet build`:
+
+```dotnetcli
+dotnet build -c Release -p:DiagnosticConfiguration=127.0.0.1:9000%2csuspend%2cconnect
+```
+
+This will automatically set the `DOTNET_DiagnosticPorts` environment variable
+packaged inside the application, so that the environment variable is set when
+the app launches.
+
+Implicitly sets [EnableDiagnostics](#enablediagnostics) to `true`.
+
+The default behavior is to compute this value from the other diagnostics
+properties ([DiagnosticAddress](#diagnosticaddress),
+[DiagnosticPort](#diagnosticport),
+[DiagnosticListenMode](#diagnosticlistenmode), and
+[DiagnosticSuspend](#diagnosticsuspend)).
+
+If set, any of the other diagnostic properties will be ignored.
+
+## DiagnosticListenMode
+
+A value provided by `dotnet-dsrouter` such as `connect` or `listen`, the
+listening mode component of
+[DiagnosticConfiguration](#diagnosticconfiguration)`.
+
+Implicitly sets [EnableDiagnostics](#enablediagnostics) to `true`.
+
+Defaults to `listen`.
+
+## DiagnosticPort
+
+A value provided by `dotnet-dsrouter` such as `9000`, the port
+component of [DiagnosticConfiguration](#diagnosticconfiguration)`.
+
+Implicitly sets [EnableDiagnostics](#enablediagnostics) to `true`.
+
+Defaults to `9000`.
+
+## DiagnosticSuspend
+
+A value that specifies the startup behavior when profiling an application.
+
+Set to `true` to suspend the app at startup (waiting for the diagnostics
+server to connect to the app) or `false` to launch the app as usual (and
+connect the diagnostics server to the app later).
+
+This corresponds with the `suspend/nosuspend` value in
+[DiagnosticConfiguration](#diagnosticconfiguration)`.
+
+Implicitly sets [EnableDiagnostics](#enablediagnostics) to `true`.
+
+Defaults to `false`.
+
 ## DittoPath
 
 The full path to the `ditto` executable.

msbuild/Xamarin.Shared/Xamarin.Shared.props

@@ -237,7 +237,20 @@ Copyright (C) 2020 Microsoft. All rights reserved.
 		<!-- that also encapsulates whether we're a library or not (this makes conditions simpler) -->
 		<_BundleOriginalResources Condition="'$(OutputType)' == 'Library' And '$(IsAppExtension)' != 'true' And '$(BundleOriginalResources)' == 'true'">true</_BundleOriginalResources>
 
-		<EnableDiagnostics Condition="'$(EnableDiagnostics)' == '' And '$(_BundlerDebug)' == 'true'">true</EnableDiagnostics>
+		<EnableDiagnostics Condition="'$(EnableDiagnostics)' == '' And ('$(DiagnosticConfiguration)' != '' Or '$(DiagnosticAddress)' != '' Or '$(DiagnosticPort)' != '' Or '$(DiagnosticSuspend)' != '' Or '$(DiagnosticListenMode)' != '')">true</EnableDiagnostics>
+	</PropertyGroup>
+
+	<PropertyGroup Condition="'$(EnableDiagnostics)' == 'true' And '$(DiagnosticConfiguration)' == ''">
+		<DiagnosticAddress Condition="'$(DiagnosticAddress)' == ''">127.0.0.1</DiagnosticAddress>
+		<DiagnosticPort Condition="'$(DiagnosticPort)' == ''">9000</DiagnosticPort>
+		<DiagnosticSuspend Condition="'$(DiagnosticSuspend)' == ''">false</DiagnosticSuspend>
+		<DiagnosticListenMode Condition="'$(DiagnosticListenMode)' == ''">listen</DiagnosticListenMode>
+		<DiagnosticConfiguration>$(DiagnosticAddress):$(DiagnosticPort),$(DiagnosticListenMode)</DiagnosticConfiguration>
+		<DiagnosticConfiguration Condition="'$(DiagnosticSuspend)' == 'true'">$(DiagnosticConfiguration),suspend</DiagnosticConfiguration>
+		<DiagnosticConfiguration Condition="'$(DiagnosticSuspend)' != 'true'">$(DiagnosticConfiguration),nosuspend</DiagnosticConfiguration>
+	</PropertyGroup>
+	<PropertyGroup Condition="'$(EnableDiagnostics)' == 'true' And '$(DiagnosticConfiguration)' != '' And '$(DiagnosticConfiguration)' != 'disable'">
+		<AppBundleExtraOptions>$(AppBundleExtraOptions) --setenv=DOTNET_DiagnosticPorts=$(DiagnosticConfiguration)</AppBundleExtraOptions>
 	</PropertyGroup>
 
 	<PropertyGroup Condition="'$(IsBindingProject)' == 'true'">