From cad8e9516cc1349ef4e6362fc9282bae47753bb1 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 19 Apr 2022 14:19:07 -0700 Subject: [PATCH] Add orphans to TOC (#29113) --- docs/core/diagnostics/diagnostic-port.md | 20 ++++++++++++------- docs/framework/interop/toc.yml | 10 +++++----- docs/fundamentals/toc.yml | 12 +++++++---- .../standard/native-interop/best-practices.md | 2 +- .../customize-parameter-marshalling.md | 8 ++++---- .../customize-struct-marshalling.md | 6 +++--- .../native-interop/disabled-marshalling.md | 4 ++-- .../native-interop/type-marshalling.md | 2 +- 8 files changed, 37 insertions(+), 27 deletions(-) diff --git a/docs/core/diagnostics/diagnostic-port.md b/docs/core/diagnostics/diagnostic-port.md index a4aad45abb2d5..3c4558f832dc5 100644 --- a/docs/core/diagnostics/diagnostic-port.md +++ b/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). diff --git a/docs/framework/interop/toc.yml b/docs/framework/interop/toc.yml index c20ab6d00319a..24fd7b45aa8ab 100644 --- a/docs/framework/interop/toc.yml +++ b/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: diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index df2154f1ab3df..270ef2894ff3d 100644 --- a/docs/fundamentals/toc.yml +++ b/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 diff --git a/docs/standard/native-interop/best-practices.md b/docs/standard/native-interop/best-practices.md index 297d0c71556e0..2122751ed2916 100644 --- a/docs/standard/native-interop/best-practices.md +++ b/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). diff --git a/docs/standard/native-interop/customize-parameter-marshalling.md b/docs/standard/native-interop/customize-parameter-marshalling.md index 6ec029da37d6f..aa27992d87d16 100644 --- a/docs/standard/native-interop/customize-parameter-marshalling.md +++ b/docs/standard/native-interop/customize-parameter-marshalling.md @@ -5,7 +5,7 @@ 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 attribute to customize how your parameters are marshalled. These customization features do not apply when [runtime marshalling is disabled](disabled-marshalling.md). @@ -13,7 +13,7 @@ When the .NET runtime's default parameter marshalling behavior doesn't do what y .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 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 and 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) diff --git a/docs/standard/native-interop/customize-struct-marshalling.md b/docs/standard/native-interop/customize-struct-marshalling.md index ea7566a9cb84e..ffd8bc1ff7e51 100644 --- a/docs/standard/native-interop/customize-struct-marshalling.md +++ b/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 value to tell the runtime to marshal your boolean value to a 2-byte `VARIANT_BOOL` value: +On Windows, you can use the value to tell the runtime to marshal your Boolean value to a 2-byte `VARIANT_BOOL` value: ```csharp public struct VariantBool diff --git a/docs/standard/native-interop/disabled-marshalling.md b/docs/standard/native-interop/disabled-marshalling.md index ced8b0c705af9..bf7d226bd76b9 100644 --- a/docs/standard/native-interop/disabled-marshalling.md +++ b/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 +- 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 diff --git a/docs/standard/native-interop/type-marshalling.md b/docs/standard/native-interop/type-marshalling.md index db6104a6c0a26..331aa03736fb6 100644 --- a/docs/standard/native-interop/type-marshalling.md +++ b/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