Add notes about native unions. (#33698)

* Add notes about native unions.

Co-authored-by: Genevieve Warren <[email protected]>

Author: AaronRobinsonMSFT

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

@@ -14,6 +14,7 @@ The guidance in this section applies to all interop scenarios.
 - ✔️ DO use the same naming and capitalization for your methods and parameters as the native method you want to call.
 - ✔️ CONSIDER using the same naming and capitalization for constant values.
 - ✔️ DO use .NET types that map closest to the native type. For example, in C#, use `uint` when the native type is `unsigned int`.
+- ✔️ DO prefer expressing higher level native types using .NET structs rather than classes.
 - ✔️ DO only use `[In]` and `[Out]` attributes when the behavior you want differs from the default behavior.
 - ✔️ CONSIDER using <xref:System.Buffers.ArrayPool%601?displayProperty=nameWithType> to pool your native array buffers.
 - ✔️ CONSIDER wrapping your P/Invoke declarations in a class with the same name and capitalization as your native library.
@@ -328,6 +329,8 @@ Pointers to structs in definitions must either be passed by `ref` or use `unsafe
 
 ✔️ DO use the C# `sizeof()` instead of `Marshal.SizeOf<MyStruct>()` for blittable structures to improve performance.
 
+❌ AVOID using classes to express complex native types through inheritance.
+
 ❌ AVOID using `System.Delegate` or `System.MulticastDelegate` fields to represent function pointer fields in structures.
 
 Since <xref:System.Delegate?displayProperty=fullName> and <xref:System.MulticastDelegate?displayProperty=fullName> don't have a required signature, they don't guarantee that the delegate passed in will match the signature the native code expects. Additionally, in .NET Framework and .NET Core, marshalling a struct containing a `System.Delegate` or `System.MulticastDelegate` from its native representation to a managed object can destabilize the runtime if the value of the field in the native representation isn't a function pointer that wraps a managed delegate. In .NET 5 and later versions, marshalling a `System.Delegate` or `System.MulticastDelegate` field from a native representation to a managed object is not supported. Use a specific delegate type instead of `System.Delegate` or `System.MulticastDelegate`.

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

@@ -19,6 +19,8 @@ Sometimes the default marshalling rules for structures aren't exactly what you n
 
 ✔️ DO only use `LayoutKind.Explicit` in marshalling when your native struct also has an explicit layout, such as a union.
 
+❌ AVOID using classes to express complex native types through inheritance.
+
 ❌ 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
@@ -111,7 +113,7 @@ public struct DefaultArray
 ```cpp
 struct DefaultArray
 {
-    int* values;
+    int32_t* values;
 };
 ```
 
@@ -329,6 +331,66 @@ struct Currency
 };
 ```
 
+### Unions
+
+A union is a data type that can contain different types of data atop the same memory. It's a common form of data in the C language. A union can be expressed in .NET using `LayoutKind.Explicit`. It's recommended to use structs when defining a union in .NET. Using classes can cause layout issues and produce unpredictable behavior.
+
+```cpp
+struct device1_config
+{
+    void* a;
+    void* b;
+    void* c;
+};
+struct device2_config
+{
+    int32_t a;
+    int32_t b;
+};
+struct config
+{
+    int32_t type;
+
+    union
+    {
+        device1_config dev1;
+        device2_config dev2;
+    };
+};
+```
+
+```csharp
+public unsafe struct Device1Config
+{
+    void* a;
+    void* b;
+    void* c;
+}
+
+public struct Device2Config
+{
+    int a;
+    int b;
+}
+
+public struct Config
+{
+    public int Type;
+
+    public _Union Anonymous;
+
+    [StructLayout(LayoutKind.Explicit)]
+    public struct _Union
+    {
+        [FieldOffset(0)]
+        public Device1Config Dev1;
+
+        [FieldOffset(0)]
+        public Device2Config Dev2;
+    }
+}
+```
+
 ## Marshal `System.Object`
 
 On Windows, you can marshal `object`-typed fields to native code. You can marshal these fields to one of three types: