Add orphans to TOC (#29113)

docs/core/diagnostics/diagnostic-port.md

@@ -5,19 +5,25 @@ ms.date: 4/11/2022
 ms.topic: overview
 ---
 
-# Diagnostic Port
+# Diagnostic port
 
 **This article applies to: ✔️** .NET Core 3.1 and later versions
 
-The .NET Core runtime exposes a service endpoint that allows other processes to send diagnostic commands and receive responses over an [IPC channel](https://en.wikipedia.org/wiki/Inter-process_communication). This endpoint is called a diagnostic port. Some of the commands that can be sent to the diagnostic port are capturing a memory dump, starting an [EventPipe](./eventpipe.md) trace, or requesting the command-line used to launch the app. The diagnostic port supports different transports depending on platform. Currently both the CoreCLR and Mono runtime implementations use Named Pipes on Windows and Unix Domain Sockets on Linux and macOS. The Mono runtime implementation on Android, iOS, and tvOS uses TCP/IP. The channel uses a [custom binary protocol](https://github.com/dotnet/diagnostics/blob/main/documentation/design-docs/ipc-protocol.md). Most developers will never directly interact with the underlying channel and protocol, but rather will use GUI or CLI tools that communicate on their behalf. For example the [dotnet-dump](./dotnet-dump.md) and [dotnet-trace](./dotnet-trace.md) tools abstract sending protocol commands to capture dumps and start traces. For developers that want to write custom tooling the [Microsoft.Diagnsotics.NETCore.Client NuGet package](./diagnostics-client-library.md) provides a .NET API abstraction of the underlying transport and protocol.
+The .NET Core runtime exposes a service endpoint that allows other processes to send diagnostic commands and receive responses over an [IPC channel](https://en.wikipedia.org/wiki/Inter-process_communication). This endpoint is called a *diagnostic port*. Commands can be sent to the diagnostic port to:
 
-## Security Considerations
+- Capture a memory dump.
+- Start an [EventPipe](./eventpipe.md) trace.
+- Request the command-line used to launch the app.
+
+The diagnostic port supports different transports depending on platform. Currently both the CoreCLR and Mono runtime implementations use Named Pipes on Windows and Unix Domain Sockets on Linux and macOS. The Mono runtime implementation on Android, iOS, and tvOS uses TCP/IP. The channel uses a [custom binary protocol](https://github.com/dotnet/diagnostics/blob/main/documentation/design-docs/ipc-protocol.md). Most developers will never directly interact with the underlying channel and protocol, but rather will use GUI or CLI tools that communicate on their behalf. For example, the [dotnet-dump](./dotnet-dump.md) and [dotnet-trace](./dotnet-trace.md) tools abstract sending protocol commands to capture dumps and start traces. For developers that want to write custom tooling, the [Microsoft.Diagnsotics.NETCore.Client NuGet package](./diagnostics-client-library.md) provides a .NET API abstraction of the underlying transport and protocol.
+
+## Security considerations
 
 The diagnostic port exposes sensitive information about a running application. If an untrusted user gains access to this channel they could observe detailed program state, including any secrets that are in memory, and arbitrarily modify the execution of the program. On the CoreCLR runtime, the default diagnostic port is configured to only be accessible by the same user account that launched the app or by an account with super-user permissions. If your security model does not trust other processes with the same user account credentials, all diagnostic ports can be disabled by setting environment variable `DOTNET_EnableDiagnostics=0`. Doing this will block your ability to use external tooling such as .NET debugging or any of the dotnet-* diagnostic tools.
 
 [!INCLUDE [complus-prefix](../../../includes/complus-prefix.md)]
 
-## Default Diagnostic Port
+## Default diagnostic port
 
 On Windows, Linux, and macOS, the runtime has one diagnostic port open by default at a well-known endpoint. This is the port that the dotnet-* diagnostic tools are connecting to automatically when they haven't been explicitly configured to use an alternate port. The endpoint is:
 
@@ -26,11 +32,11 @@ On Windows, Linux, and macOS, the runtime has one diagnostic port open by defaul
 
 `{pid}` is the process id written in decimal, `{temp}` is the `TMPDIR` environment variable or the value `/tmp` if `TMPDIR` is undefined/empty, and `{disambiguation_key}` is the process start time written in decimal. On macOS and NetBSD, the process start time is number of seconds since UNIX epoch time and on all other platforms it is jiffies since boot time.
 
-## Suspending the runtime at startup
+## Suspend the runtime at startup
 
 By default the runtime executes managed code as soon as it starts, regardless whether any diagnostic tools have connected to the diagnostic port. Sometime it is useful to have the runtime wait to run managed code until after a diagnostic tool is connected, to observe the initial program behavior. Setting environment variable `DOTNET_DefaultDiagnosticPortSuspend=1` causes the runtime to wait until a tool connects to the default port. If no tool is attached after several seconds, the runtime prints a warning message to the console explaining that it is still waiting for a tool to attach.
 
-## Configuring additional diagnostic ports
+## Configure additional diagnostic ports
 
 > [!IMPORTANT]
 > This works for apps running .NET 5 or later only.
@@ -56,6 +62,6 @@ The complete syntax for a port is `address[,(listen|connect)][,(suspend|nosuspen
 
 Tools such as [dotnet-dump](./dotnet-dump.md), [dotnet-counters](./dotnet-counters.md), or [dotnet-trace](./dotnet-trace.md) all support `collect` or `monitor` verbs which communicate to a .NET app via the diagnostic port. When these tools are using the `--processId` argument the tool automatically computes the default diagnostic port address and connects to it. When specifying the `--diagnostic-port` argument, the tool listens at the given address and you should use the `DOTNET_DiagnosticPorts` environment variable to configure your app to connect. For a complete example with dotnet-counters, see [Using the Diagnostic Port](./dotnet-counters.md#using-diagnostic-port).
 
-## Using ds-router to proxy the diagnostic port
+## Use ds-router to proxy the diagnostic port
 
 All of the dotnet-* diagnostic tools expect to connect to a diagnostic port that is a local Named Pipe or Unix Domain Socket. Mono often runs on isolated hardware or in emulators that need a proxy over TCP to become accessible. The [dotnet-dsrouter tool](./dotnet-dsrouter.md) can proxy a local Named Pipe or Unix Domain Socket to TCP so that the tools can be used in those environments. For more information, see [dotnet-dsrouter](./dotnet-dsrouter.md).

docs/framework/interop/toc.yml

@@ -53,21 +53,21 @@
       - name: "How to: Implement Callback Functions"
         href: how-to-implement-callback-functions.md
   - name: Interop Marshaling
-    href: /dotnet/framework/interop/interop-marshalling
+    href: interop-marshalling.md
     items:
     - name: Default Marshalling Behavior
-      href: /dotnet/framework/interop/default-marshalling-behavior
+      href: default-marshalling-behavior.md
       items:
       - name: Blittable and Non-Blittable Types
         href: blittable-and-non-blittable-types.md
       - name: Copying and Pinning
         href: copying-and-pinning.md
       - name: Default Marshalling for Arrays
-        href: /dotnet/framework/interop/default-marshalling-for-arrays
+        href: default-marshalling-for-arrays.md
       - name: Default Marshalling for Objects
-        href: /dotnet/framework/interop/default-marshalling-for-objects
+        href: default-marshalling-for-objects.md
       - name: Default Marshalling for Strings
-        href: /dotnet/framework/interop/default-marshalling-for-strings
+        href: default-marshalling-for-strings.md
     - name: Marshalling Data with Platform Invoke
       href: marshalling-data-with-platform-invoke.md
       items:

docs/fundamentals/toc.yml

@@ -621,6 +621,8 @@ items:
       href: ../core/diagnostics/index.md
     - name: Managed debuggers
       href: ../core/diagnostics/managed-debuggers.md
+    - name: Diagnostic port
+      href: ../core/diagnostics/diagnostic-port.md
     - name: Dumps
       items:
       - name: Overview
@@ -2820,17 +2822,19 @@ items:
     - name: P/Invoke
       href: ../standard/native-interop/pinvoke.md
     - name: Type marshalling
-      href: /dotnet/standard/native-interop/type-marshalling
+      href: ../standard/native-interop/type-marshalling.md
     - name: Customize structure marshalling
-      href: /dotnet/standard/native-interop/customize-struct-marshalling
+      href: ../standard/native-interop/customize-struct-marshalling.md
     - name: Customize parameter marshalling
-      href: /dotnet/standard/native-interop/customize-parameter-marshalling
-    - name: Cross platform P/Invoke
+      href: ../standard/native-interop/customize-parameter-marshalling.md
+    - name: Cross-platform P/Invoke
       href: ../standard/native-interop/cross-platform.md
     - name: Interop guidance
       href: ../standard/native-interop/best-practices.md
     - name: Charsets and marshalling
       href: ../standard/native-interop/charset.md
+    - name: Disabled marshalling
+      href: ../standard/native-interop/disabled-marshalling.md
     - name: Expose .NET components to COM
       href: ../core/native-interop/expose-components-to-com.md
     - name: Host .NET from native code

docs/standard/native-interop/best-practices.md

@@ -130,7 +130,7 @@ You can see if a type is blittable or contains blittable contents by attempting
 
 ### Blittable types when runtime marshalling is disabled
 
-When [runtime marshalling is disabled](disabled-marshalling.md), the rules for which types are blittable are significantly simpler. All types that are [C# `unmanaged`](../../csharp/language-reference/builtin-types/unmanaged-types.md) types and do not have any fields that are marked with `[StructLayout(LayoutKind.Auto)]` are blittable. All types that are not C# `unmanaged` types are not blittable. The concept of types with blittable contents, such as arrays or strings, does not apply when runtime marshalling is disabled. Any type that is not considered blittable by the aforementioned rule is unsupported when runtime marshalling is disabled.
+When [runtime marshalling is disabled](disabled-marshalling.md), the rules for which types are blittable are significantly simpler. All types that are [C# `unmanaged`](../../csharp/language-reference/builtin-types/unmanaged-types.md) types and don't have any fields that are marked with `[StructLayout(LayoutKind.Auto)]` are blittable. All types that are not C# `unmanaged` types are not blittable. The concept of types with blittable contents, such as arrays or strings, does not apply when runtime marshalling is disabled. Any type that is not considered blittable by the aforementioned rule is unsupported when runtime marshalling is disabled.
 
 These rules differ from the built-in system primarily in situations where `bool` and `char` are used. When marshalling is disabled, `bool` is passed as a 1-byte value and not normalized and `char` is always passed as a 2-byte value. When runtime marshalling is enabled, `bool` can map to a 1, 2, or 4-byte value and is always normalized, and `char` maps to either a 1 or 2-byte value depending on the [`CharSet`](charset.md).
 

docs/standard/native-interop/customize-parameter-marshalling.md

@@ -5,15 +5,15 @@ ms.date: 01/18/2019
 ms.topic: how-to
 ---
 
-# Customizing parameter marshalling
+# Customize parameter marshalling
 
 When the .NET runtime's default parameter marshalling behavior doesn't do what you want, use can use the <xref:System.Runtime.InteropServices.MarshalAsAttribute?displayProperty=nameWithType> attribute to customize how your parameters are marshalled. These customization features do not apply when [runtime marshalling is disabled](disabled-marshalling.md).
 
 ## Customizing string parameters
 
 .NET has a variety of formats for marshalling strings. These methods are split into distinct sections on C-style strings and Windows-centric string formats.
 
-### C-Style strings
+### C-style strings
 
 Each of these formats passes a null-terminated string to native code. They differ by the encoding of the native string.
 
@@ -38,9 +38,9 @@ If you're interacting with WinRT APIs, you can use the <xref:System.Runtime.Inte
 
 If you're using COM APIs, you'll likely have to marshal your array parameters as `SAFEARRAY*`s. To do so, you can use the <xref:System.Runtime.InteropServices.UnmanagedType.SafeArray?displayProperty=nameWithType> unmanaged type. The default type of the elements of the `SAFEARRAY` can be seen in the table on [customizing `object` fields](customize-struct-marshalling.md#marshal-systemobject). You can use the <xref:System.Runtime.InteropServices.MarshalAsAttribute.SafeArraySubType?displayProperty=nameWithType> and <xref:System.Runtime.InteropServices.MarshalAsAttribute.SafeArrayUserDefinedSubType?displayProperty=nameWithType> fields to customize the exact element type of the `SAFEARRAY`.
 
-## Customizing boolean or decimal parameters
+## Customizing Boolean or decimal parameters
 
-For information on marshalling boolean or decimal parameters, see [Customizing structure marshalling](customize-struct-marshalling.md).
+For information on marshalling Boolean or decimal parameters, see [Customizing structure marshalling](customize-struct-marshalling.md).
 
 ## Customizing object parameters (Windows-only)
 

docs/standard/native-interop/customize-struct-marshalling.md

@@ -21,9 +21,9 @@ Sometimes the default marshalling rules for structures aren't exactly what you n
 
 ❌ AVOID using `LayoutKind.Explicit` when marshalling structures on non-Windows platforms if you need to target runtimes before .NET Core 3.0. The .NET Core runtime before 3.0 doesn't support passing explicit structures by value to native functions on Intel or AMD 64-bit non-Windows systems. However, the runtime supports passing explicit structures by reference on all platforms.
 
-## Customizing boolean field marshalling
+## Customizing Boolean field marshalling
 
-Native code has many different boolean representations. On Windows alone, there are three ways to represent boolean values. The runtime doesn't know the native definition of your structure, so the best it can do is make a guess on how to marshal your boolean values. The .NET runtime provides a way to indicate how to marshal your boolean field. The following examples show how to marshal .NET `bool` to different native boolean types.
+Native code has many different Boolean representations. On Windows alone, there are three ways to represent Boolean values. The runtime doesn't know the native definition of your structure, so the best it can do is make a guess on how to marshal your Boolean values. The .NET runtime provides a way to indicate how to marshal your Boolean field. The following examples show how to marshal .NET `bool` to different native Boolean types.
 
 Boolean values default to marshalling as a native 4-byte Win32 [`BOOL`](/windows/desktop/winprog/windows-data-types#BOOL) value as shown in the following example:
 
@@ -75,7 +75,7 @@ struct CBool
 };
 ```
 
-On Windows, you can use the <xref:System.Runtime.InteropServices.UnmanagedType.VariantBool?displayProperty=nameWithType> value to tell the runtime to marshal your boolean value to a 2-byte `VARIANT_BOOL` value:
+On Windows, you can use the <xref:System.Runtime.InteropServices.UnmanagedType.VariantBool?displayProperty=nameWithType> value to tell the runtime to marshal your Boolean value to a 2-byte `VARIANT_BOOL` value:
 
 ```csharp
 public struct VariantBool

docs/standard/native-interop/disabled-marshalling.md

@@ -6,7 +6,7 @@ ms.date: 01/12/2022
 
 # Disabled runtime marshalling
 
-When the [`System.Runtime.CompilerServices.DisableRuntimeMarshallingAttribute`](xref:System.Runtime.CompilerServices.DisableRuntimeMarshallingAttribute) attribute is applied to an assembly, the runtime disables most built-in support for data marshalling between managed and native representations. This document describes the features that are disabled and how .NET types map to native types when marshalling is disabled.
+When the [`System.Runtime.CompilerServices.DisableRuntimeMarshallingAttribute`](xref:System.Runtime.CompilerServices.DisableRuntimeMarshallingAttribute) attribute is applied to an assembly, the runtime disables most built-in support for data marshalling between managed and native representations. This article describes the features that are disabled and how .NET types map to native types when marshalling is disabled.
 
 ## Scenarios where marshalling is disabled
 
@@ -16,7 +16,7 @@ When the `DisableRuntimeMarshallingAttribute` is applied to an assembly, it affe
 
 When the `DisableRuntimeMarshallingAttribute` is applied to an assembly, the following attributes will have no effect or throw an exception:
 
-- [`LCIDConversionAttribute`](xref:System.Runtime.InteropServices.LCIDConversionAttribute) on a P/Invoke or a delegate
+- <xref:System.Runtime.InteropServices.LCIDConversionAttribute> on a P/Invoke or a delegate
 - `SetLastError=true` on a P/Invoke
 - `ThrowOnUnmappableChar=true` on a P/Invoke
 - `BestFitMapping=true` on a P/Invoke

docs/standard/native-interop/type-marshalling.md

@@ -15,7 +15,7 @@ Marshalling is needed because the types in the managed and unmanaged code are di
 static extern int MethodA([MarshalAs(UnmanagedType.LPStr)] string parameter);
 ```
 
-If the [`System.Runtime.CompilerServices.DisableRuntimeMarshallingAttribute`](xref:System.Runtime.CompilerServices.DisableRuntimeMarshallingAttribute) attribute is applied to the assembly, the below rules do not apply. See the documentation on [disabled runtime marshalling](disabled-marshalling.md) for information on how .NET values are exposed to native code when this attribute is applied.
+If you apply the [`System.Runtime.CompilerServices.DisableRuntimeMarshallingAttribute`](xref:System.Runtime.CompilerServices.DisableRuntimeMarshallingAttribute) attribute to the assembly, the rules in the following section don't apply. For information on how .NET values are exposed to native code when this attribute is applied, see [disabled runtime marshalling](disabled-marshalling.md).
 
 ## Default rules for marshalling common types