Add Native AOT diagnostics support documentation for iOS-like platforms

Author: ivanpovazan

.openpublishing.redirection.core.json

@@ -352,6 +352,11 @@
             "redirect_url": "/dotnet/core/deploying/native-aot/index",
             "redirect_document_id": true
         },
+        {
+            "source_path_from_root": "/docs/core/deploying/native-aot/diagnostics.md",
+            "redirect_url": "/dotnet/core/deploying/native-aot/diagnostics/index",
+            "redirect_document_id": true
+        },
         {
             "source_path_from_root": "/docs/core/deploying/prepare-libraries-for-trimming.md",
             "redirect_url": "/dotnet/core/deploying/trimming/prepare-libraries-for-trimming",

docs/core/deploying/native-aot/diagnostics.md renamed to docs/core/deploying/native-aot/diagnostics/desktop-platforms.md

@@ -1,38 +1,24 @@
 ---
-title: Diagnostics and instrumentation
-description: Learn about diagnostics in Native AOT applications
+title: Diagnostics and instrumentation on desktop platforms
+description: Learn about diagnostics in Native AOT applications on desktop platforms
 author: lakshanf
 ms.author: lakshanf
 ms.date: 08/07/2023
 ---
 
-# Diagnostics and instrumentation
-
-Native AOT shares some, but not all, diagnostics and instrumentation capabilities with CoreCLR. Because of CoreCLR's rich selection of diagnostic utilities, it's sometimes appropriate to diagnose and debug problems in CoreCLR. Apps that are [trim-compatible](../trimming/prepare-libraries-for-trimming.md) shouldn't have behavioral differences, so investigations often apply to both runtimes. Nonetheless, some information can only be gathered after publishing, so Native AOT also provides post-publish diagnostic tooling.
-
-## .NET 8 Native AOT diagnostic support
-
-The following table summarizes diagnostic features supported for Native AOT deployments:
-
-| Feature | Fully supported | Partially supported | Not supported |
-| - | - | - | - |
-| [Observability and telemetry](#observability-and-telemetry) | | <span aria-hidden="true">✔️</span><span class="visually-hidden">Partially supported</span> | |
-| [Development-time diagnostics](#development-time-diagnostics) | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
-| [Native debugging](#native-debugging) | | <span aria-hidden="true">✔️</span><span class="visually-hidden">Partially supported</span> | |
-| [CPU Profiling](#cpu-profiling) | | <span aria-hidden="true">✔️</span><span class="visually-hidden">Partially supported</span> | |
-| [Heap analysis](#heap-analysis) | | | <span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> |
+# Native AOT diagnostic support on desktop platforms
 
 ## Observability and telemetry
 
-As of .NET 8, the Native AOT runtime supports [EventPipe](../../diagnostics/eventpipe.md), which is the base layer used by many logging and tracing libraries. You can interface with EventPipe directly through APIs like `EventSource.WriteEvent` or you can use libraries built on top, like [OpenTelemetry](../../diagnostics/observability-with-otel.md). EventPipe support also allows .NET diagnostic tools like [dotnet-trace](../../diagnostics/dotnet-trace.md), [dotnet-counters](../../diagnostics/dotnet-counters.md), and [dotnet-monitor](../../diagnostics/dotnet-monitor.md) to work seamlessly with Native AOT or CoreCLR applications. EventPipe is an optional component in Native AOT. To include EventPipe support, set the `EventSourceSupport` MSBuild property to `true`.
+As of .NET 8, the Native AOT runtime supports [EventPipe](../../../diagnostics/eventpipe.md), which is the base layer used by many logging and tracing libraries. You can interface with EventPipe directly through APIs like `EventSource.WriteEvent` or you can use libraries built on top, like [OpenTelemetry](../../../diagnostics/observability-with-otel.md). EventPipe support also allows .NET diagnostic tools like [dotnet-trace](../../../diagnostics/dotnet-trace.md), [dotnet-counters](../../../diagnostics/dotnet-counters.md), and [dotnet-monitor](../../../diagnostics/dotnet-monitor.md) to work seamlessly with Native AOT or CoreCLR applications. EventPipe is an optional component in Native AOT. To include EventPipe support, set the `EventSourceSupport` MSBuild property to `true`.
 
 ```xml
 <PropertyGroup>
     <EventSourceSupport>true</EventSourceSupport>
 </PropertyGroup>
 ```
 
-Native AOT provides partial support for some [well-known event providers](../../diagnostics/well-known-event-providers.md). Not all [runtime events](../../../fundamentals/diagnostics/runtime-events.md) are supported in Native AOT.
+Native AOT provides partial support for some [well-known event providers](../../../diagnostics/well-known-event-providers.md). Not all [runtime events](../../../../fundamentals/diagnostics/runtime-events.md) are supported in Native AOT.
 
 ## Development-time diagnostics
 
@@ -55,7 +41,7 @@ The Native AOT compiler generates information about line numbers, types, locals,
 To debug managed exceptions, set a breakpoint on the `RhThrowEx` method, which is called whenever a managed exception is thrown. The exception is stored in the `rcx` or `x0` register. If your debugger supports viewing C++ objects, you can cast
 the register to `S_P_CoreLib_System_Exception*` to see more information about the exception.
 
-Collecting a [dump](../../diagnostics/dumps.md) file for a Native AOT application involves some manual steps in .NET 8.
+Collecting a [dump](../../../diagnostics/dumps.md) file for a Native AOT application involves some manual steps in .NET 8.
 
 ### Visual Studio-specific notes
 
@@ -69,12 +55,12 @@ To see what exception was thrown, start debugging (**Debug > Start Debugging** o
 
 When publishing, the Native AOT compiler produces both an executable and a symbol file. Native debugging, and related activities like profiling, require access to the native symbol file. If this file isn't present, you might have degraded or broken results.
 
-For information about the name and location of the symbol file, see [Native debug information](index.md#native-aot-deployment).
+For information about the name and location of the symbol file, see [Native debug information](../index.md#native-aot-deployment).
 
 ## CPU profiling
 
 Platform-specific tools like [PerfView](https://github.com/microsoft/perfview) and [Perf](https://perf.wiki.kernel.org/index.php/Main_Page) can be used to collect CPU samples of a Native AOT application.
 
 ## Heap analysis
 
-Managed heap analysis isn't currently supported in Native AOT. Heap analysis tools like [dotnet-gcdump](../../diagnostics/dotnet-gcdump.md), [PerfView](https://github.com/microsoft/perfview), and Visual Studio heap analysis tools don't work in Native AOT in .NET 8.
+Managed heap analysis isn't currently supported in Native AOT. Heap analysis tools like [dotnet-gcdump](../../../diagnostics/dotnet-gcdump.md), [PerfView](https://github.com/microsoft/perfview), and Visual Studio heap analysis tools don't work in Native AOT in .NET 8.

docs/core/deploying/native-aot/diagnostics/index.md

@@ -0,0 +1,38 @@
+---
+title: Diagnostics and instrumentation
+description: Learn about diagnostics in Native AOT applications
+author: lakshanf
+ms.author: lakshanf
+ms.date: 08/07/2023
+---
+
+# Diagnostics and instrumentation
+
+Native AOT shares some, but not all, diagnostics and instrumentation capabilities with CoreCLR on desktop platforms and Mono on mobile platforms. Because of CoreCLR's and Mono's rich selection of diagnostic utilities, it's sometimes appropriate to diagnose and debug problems in CoreCLR or Mono, rather than with Native AOT. Apps that are [trim-compatible](../../trimming/prepare-libraries-for-trimming.md) shouldn't have behavioral differences, so investigations often apply between runtimes. Nonetheless, some information can only be gathered after publishing, so Native AOT also provides post-publish diagnostic tooling.
+
+## Native AOT diagnostic support
+
+The following table summarizes diagnostic features supported for Native AOT deployments and a more detailed description of diagnostics support on different platforms can be found on dedicated pages:
+
+- [Desktop platforms](./desktop-platforms.md)
+- [iOS-like platforms](./ios-like-platforms.md)
+
+### [Desktop platforms](#tab/desktop-plat)
+
+| Feature | Fully supported | Partially supported | Not supported |
+| - | - | - | - |
+| [Observability and telemetry](./desktop-platforms.md#observability-and-telemetry) | | <span aria-hidden="true">✔️</span><span class="visually-hidden">Partially supported</span> | |
+| [Development-time diagnostics](./desktop-platforms.md#development-time-diagnostics) | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
+| [Native debugging](./desktop-platforms.md#native-debugging) | | <span aria-hidden="true">✔️</span><span class="visually-hidden">Partially supported</span> | |
+| [CPU Profiling](./desktop-platforms.md#cpu-profiling) | | <span aria-hidden="true">✔️</span><span class="visually-hidden">Partially supported</span> | |
+| [Heap analysis](./desktop-platforms.md#heap-analysis) | | | <span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> |
+
+### [iOS-like platforms](#tab/ios-like-plat)
+
+| Feature | Fully supported | Partially supported | Not supported |
+| - | - | - | - |
+| [Observability and telemetry](./ios-like-platforms.md#observability-and-telemetry) | | | <span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> |
+| [Development-time diagnostics](./ios-like-platforms.md#development-time-diagnostics) | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
+| [Native debugging](./ios-like-platforms.md#native-debugging) | | <span aria-hidden="true">✔️</span><span class="visually-hidden">Partially supported</span> | |
+| [CPU Profiling](./ios-like-platforms.md#cpu-profiling) | | <span aria-hidden="true">✔️</span><span class="visually-hidden">Partially supported</span> | |
+| [Heap analysis](./ios-like-platforms.md#heap-analysis) | | | <span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> |

docs/core/deploying/native-aot/diagnostics/ios-like-platforms.md

@@ -0,0 +1,77 @@
+---
+title: Diagnostics and instrumentation on iOS-like platforms
+description: Learn about diagnostics in Native AOT applications on iOS-like platforms
+author: ivanpovazan
+ms.author: ivanpovazan
+ms.date: 11/11/2024
+---
+
+# Native AOT diagnostic support on iOS-like platforms
+
+## Observability and telemetry
+
+Tracing of .NET applications on mobile platforms is enabled through [dotnet-dsrouter](../../../diagnostics/dotnet-dsrouter.md) which connects diagnostic tooling with .NET mobile applications running on iOS-like platforms over TCP/IP. However, Native AOT is currently not compatible with this scenario as it does not support EventPipe/DiagnosticServer components built with TCP/IP stack.
+
+## Development-time diagnostics
+
+The .NET CLI tooling (`dotnet` SDK) offers separate commands for `build` and `publish`. `dotnet build` (or `Start Debugging (F5)` in VS Code), uses Mono by default when building or launching .NET MAUI iOS (or MacCatalyst) applications. Only `dotnet publish` creates a Native AOT application, if this deployment model is enabled in the project file. Publishing your app as Native AOT, produces an app that has been ahead-of-time (AOT) compiled to native code. As described in this document, not all diagnostic tools will work seamlessly with published Native AOT applications.
+However, all applications that are trim and AOT-compatible, i.e., that do not produce any trim and AOT warnings during build time, shouldn't have behavioral differences between Mono and Native AOT.
+Therefore, all .NET development-time diagnostic tools (like Hot Reload) are still available for developers during mobile app development cycle.
+We recommend developing, debugging, and testing the applications as usual and publishing the working app with Native AOT as one of the last steps.
+
+## Native debugging
+
+When you run your .NET MAUI iOS (or MacCatalyst) app during development, like inside VS Code, or with `dotnet build -t:Run`, it runs on Mono by default. However, if `PublishAot` is present in the project file, the behavior is expected to be the same between Mono and Native AOT when the application is not producing any trim and AOT warnings upon build. This characteristic allows you to use the standard VS Code managed debugging engine for development and testing, if your application fulfils the mentioned requirement.
+
+After publishing, Native AOT applications are true native binaries. The managed debugger won't work on them. However, the Native AOT compiler generates fully native executable files that you can debug with `lldb`. Debugging a MacCatalyst app with `lldb` is straight-forward, as it is executed on the same system. However, debugging NativeAOT iOS applications requires a few extra steps which are covered in the following subsection.
+
+### Debugging .NET MAUI iOS applications with NativeAOT
+
+.NET MAUI applications which are compatible with NativeAOT and are properly configured and published with this deployment model (for more information see: [Publish using Native AOT](https://learn.microsoft.com/en-us/dotnet/maui/deployment/nativeaot?view=net-maui-9.0#publish-using-native-aot), can be debugged in the following ways.
+
+#### iOS
+
+1. Publish your app with Native AOT targeting `ios-arm64` and store the following information:
+
+    - Application name - referenced bellow as `<app-name>`
+    - Bundle identifier - referenced bellow as `<bundle-identifier>`
+    - Path to the published application's archive *.ipa* file - referenced bellow as `<path-to-ipa>`
+
+2. Discover physical device ID - referenced bellow as: `<device-identifier>`
+
+    ```bash
+    xcrun devicectl list devices
+    ```
+
+3. Install the app on your physical device
+
+    ```bash
+    xcrun devicectl device install app --device <device-identifier> <path-to-ipa>
+    ```
+
+4. Launch the app stopped on your physical device
+
+    ```bash
+    xcrun devicectl device process launch --device <device-identifier> --start-stopped <bundle-identifier>
+    ```
+
+5. Open `lldb` and connect to your physical device
+
+    ```bash
+    (lldb) device select <device-identifier>
+    (lldb) device process attach -n <app-name>
+    ```
+
+After successfully completing previous steps, you are all set to start debugging your Native AOT .NET MAUI iOS application with `lldb`.
+
+### Importance of the symbol file
+
+By default, debug symbols are stripped from the application's binary file into *.dSYM* files. This file is used by debuggers and post mortem analysis tools to show information about local variables, source line numbers, to recreate stack traces of crash dumps etc. Therefore, it is essential to preserve it before submitting your application to App Store.
+
+## CPU profiling
+
+[Xcode Instruments](https://developer.apple.com/download/) can be used to collect CPU samples of a Native AOT application.
+
+## Heap analysis
+
+Currently not supported with Native AOT.

docs/core/deploying/native-aot/index.md

@@ -113,9 +113,9 @@ By default, Native AOT publishing produces debug information in a separate file:
 
 - Linux: *.dbg*
 - Windows: *.pdb*
-- macOS: *.dSYM* folder
+- MacOS/MacCatalyst/iOS/tvOS: *.dSYM* folder
 
-The debug file is necessary for running the app under the [debugger or inspecting crash dumps](./diagnostics.md#importance-of-the-symbol-file). On Unix-like platforms, set the `StripSymbols` property to `false` to include the debug information in the native binary. Including debug information makes the native binary larger.
+The debug file is necessary for running the app under the debugger or inspecting crash dumps on both: [desktop](./diagnostics/desktop-platforms.md#importance-of-the-symbol-file) and [mobile](./diagnostics/ios-like-platforms.md#importance-of-the-symbol-file) platforms. On Unix-like platforms, set the `StripSymbols` property to `false` to include the debug information in the native binary. Including debug information makes the native binary larger.
 
 ```xml
 <PropertyGroup>
@@ -136,7 +136,7 @@ Native AOT apps have the following limitations:
 - Apps include required runtime libraries (just like [self-contained apps](../index.md#publish-self-contained), increasing their size as compared to framework-dependent apps).
 - <xref:System.Linq.Expressions> always use their interpreted form, which is slower than run-time generated compiled code.
 - Not all the runtime libraries are fully annotated to be Native AOT compatible. That is, some warnings in the runtime libraries aren't actionable by end developers.
-- [Diagnostic support for debugging and profiling](./diagnostics.md) with some limitations.
+- [Diagnostic support for debugging and profiling](./diagnostics/index.md) with some limitations.
 - Support for some ASP.NET Core features. For more information, see [ASP.NET Core support for Native AOT](/aspnet/core/fundamentals/native-aot/).
 
 The publish process analyzes the entire project and its dependencies for possible limitations. Warnings are issued for each limitation the published app might encounter at run time.

docs/core/diagnostics/index.md

@@ -9,7 +9,7 @@ ms.topic: overview
 
 Software doesn't always behave as you would expect, but .NET Core has tools and APIs that will help you diagnose these issues quickly and effectively.
 
-[Native AOT deployment](../../core/deploying/native-aot/index.md) is an application model that's been available since .NET 7. For information about .NET 8 diagnostic support for Native AOT apps, see [Native AOT diagnostics](../../core/deploying/native-aot/diagnostics.md).
+[Native AOT deployment](../../core/deploying/native-aot/index.md) is an application model that's been available since .NET 7. For information about .NET 8 diagnostic support for Native AOT apps, see [Native AOT diagnostics](../../core/deploying/native-aot/diagnostics/index.md).
 
 This article helps you find the various tools you need.
 

docs/navigate/devops-testing/toc.yml

@@ -498,7 +498,13 @@ items:
           - name: Optimize AOT deployments
             href: ../../core/deploying/native-aot/optimizing.md
           - name: AOT diagnostics
-            href: ../../core/deploying/native-aot/diagnostics.md
+            items:
+              - name: Overview
+                href: ../../core/deploying/native-aot/diagnostics/index.md
+              - name: Desktop platforms
+                href: ../../core/deploying/native-aot/diagnostics/desktop-platforms.md
+              - name: iOS-like platforms
+                href: ../../core/deploying/native-aot/diagnostics/ios-like-platforms.md
           - name: Native code interop
             href: ../../core/deploying/native-aot/interop.md
           - name: Build native libraries