diff --git a/docs/framework/interop/marshalling-data-with-platform-invoke.md b/docs/framework/interop/marshalling-data-with-platform-invoke.md index 4ab251b8279da..30fcb3b3b9c17 100644 --- a/docs/framework/interop/marshalling-data-with-platform-invoke.md +++ b/docs/framework/interop/marshalling-data-with-platform-invoke.md @@ -1,14 +1,17 @@ --- title: "Marshalling Data with Platform Invoke" description: Marshal data with platform invoke in .NET. See a list of data types used in Windows APIs and C-style functions, and find their .NET managed type equivalents. -ms.date: "03/20/2019" +ms.date: "03/06/2026" dev_langs: + - "csharp" + - "vb" - "cpp" helpviewer_keywords: - "platform invoke, marshalling data" - "data marshalling, platform invoke" - "marshaling, platform invoke" ms.assetid: dc5c76cf-7b12-406f-b79c-d1a023ec245d +ai-usage: ai-assisted --- # Marshalling Data with Platform Invoke @@ -52,7 +55,7 @@ For corresponding types in Visual Basic, C#, and C++, see the [Introduction to t ## PinvokeLib.dll -The following code defines the library functions provided by Pinvoke.dll. Many samples described in this section call this library. +The following code defines the library functions provided by PInvokeLib.dll. Many samples described in this section call this library. ### Example @@ -60,17 +63,21 @@ The following code defines the library functions provided by Pinvoke.dll. Many s [!code-cpp[PInvokeLib#2](../../../samples/snippets/cpp/VS_Snippets_CLR/pinvokelib/cpp/pinvokelib.h#2)] -To call the library functions from managed code, first implement the managed prototypes for each function you want to invoke. -If the unmanaged code uses any custom types, you must also declare those types in your managed code. -Decorate the prototype with the attribute. +To call the library functions from managed code, implement managed prototypes for each function you want to invoke. If the unmanaged code uses any custom types, you must also declare those types in your managed code. Decorate each prototype with the attribute, and use to control the layout of managed structures so they match the unmanaged equivalents. -The following code shows an example prototype: +### Managed type declarations -```csharp -// Managed prototype for TestingStructInStruct, which is declared and defined in an unmanaged library. -[DllImport("..\\LIB\\PinvokeLib.dll", CallingConvention = CallingConvention.Cdecl)] -internal static extern int TestStructInStruct(ref MyPerson2 person2); -``` +The following code shows the managed equivalents of the unmanaged types defined in `PInvokeLib.h`. Each structure uses `StructLayout` to ensure the field layout matches the unmanaged layout: + +:::code language="csharp" source="./snippets/marshalling-data-with-platform-invoke/csharp/PInvokeLibManaged/NativeMethods.cs" id="ManagedTypes"::: +:::code language="vb" source="./snippets/marshalling-data-with-platform-invoke/vb/PInvokeLibManaged/NativeMethods.vb" id="ManagedTypes"::: + +### Managed function prototypes + +The following code shows the `DllImport` declarations that expose the unmanaged functions from `PinvokeLib.dll` to managed code: + +:::code language="csharp" source="./snippets/marshalling-data-with-platform-invoke/csharp/PInvokeLibManaged/NativeMethods.cs" id="NativeMethods"::: +:::code language="vb" source="./snippets/marshalling-data-with-platform-invoke/vb/PInvokeLibManaged/NativeMethods.vb" id="NativeMethods"::: For more information and examples, see the following articles: diff --git a/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/csharp/PInvokeLibManaged/NativeMethods.cs b/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/csharp/PInvokeLibManaged/NativeMethods.cs new file mode 100644 index 0000000000000..95ad89611b78d --- /dev/null +++ b/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/csharp/PInvokeLibManaged/NativeMethods.cs @@ -0,0 +1,90 @@ +using System.Runtime.InteropServices; + +// +// Managed type declarations that correspond to the unmanaged types in PinvokeLib.dll. + +[StructLayout(LayoutKind.Sequential)] +internal struct MyPoint +{ + public int x; + public int y; +} + +[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Ansi)] +internal struct MyPerson +{ + public string first; + public string last; +} + +[StructLayout(LayoutKind.Sequential)] +internal struct MyPerson2 +{ + public IntPtr person; // Pointer to a MyPerson structure + public int age; +} + +[StructLayout(LayoutKind.Sequential)] +internal struct MyPerson3 +{ + public MyPerson person; // Embedded MyPerson structure + public int age; +} + +[StructLayout(LayoutKind.Explicit)] +internal struct MyUnion +{ + [FieldOffset(0)] public int i; + [FieldOffset(0)] public double d; +} + +[StructLayout(LayoutKind.Sequential)] +internal struct MyArrayStruct +{ + public bool flag; + + [MarshalAs(UnmanagedType.ByValArray, SizeConst = 3)] + public int[] vals; +} +// + +// +internal static class NativeMethods +{ + [DllImport("PinvokeLib.dll", CallingConvention = CallingConvention.Cdecl)] + internal static extern int TestArrayOfInts( + [In, Out] int[] array, int size); + + [DllImport("PinvokeLib.dll", CallingConvention = CallingConvention.Cdecl)] + internal static extern int TestRefArrayOfInts( + ref IntPtr array, ref int size); + + [DllImport("PinvokeLib.dll", CallingConvention = CallingConvention.Cdecl)] + internal static extern int TestMatrixOfInts( + [In, Out] int[,] matrix, int row); + + [DllImport("PinvokeLib.dll", CallingConvention = CallingConvention.Cdecl)] + internal static extern int TestArrayOfStrings( + [In, Out] string[] array, int size); + + [DllImport("PinvokeLib.dll", CallingConvention = CallingConvention.Cdecl)] + internal static extern int TestArrayOfStructs( + [In, Out] MyPoint[] pointArray, int size); + + [DllImport("PinvokeLib.dll", CallingConvention = CallingConvention.Cdecl)] + internal static extern int TestArrayOfStructs2( + [In, Out] MyPerson[] personArray, int size); + + [DllImport("PinvokeLib.dll", CallingConvention = CallingConvention.Cdecl)] + internal static extern int TestStructInStruct(ref MyPerson2 person2); + + [DllImport("PinvokeLib.dll", CallingConvention = CallingConvention.Cdecl)] + internal static extern void TestStructInStruct3(MyPerson3 person3); + + [DllImport("PinvokeLib.dll", CallingConvention = CallingConvention.Cdecl)] + internal static extern void TestUnion(MyUnion u, int type); + + [DllImport("PinvokeLib.dll", CallingConvention = CallingConvention.Cdecl)] + internal static extern void TestArrayInStruct(ref MyArrayStruct myStruct); +} +// diff --git a/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/csharp/PInvokeLibManaged/PInvokeLibManaged.csproj b/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/csharp/PInvokeLibManaged/PInvokeLibManaged.csproj new file mode 100644 index 0000000000000..ed9781c223ab9 --- /dev/null +++ b/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/csharp/PInvokeLibManaged/PInvokeLibManaged.csproj @@ -0,0 +1,10 @@ + + + + Exe + net10.0 + enable + enable + + + diff --git a/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/csharp/PInvokeLibManaged/Program.cs b/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/csharp/PInvokeLibManaged/Program.cs new file mode 100644 index 0000000000000..3220232a7de24 --- /dev/null +++ b/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/csharp/PInvokeLibManaged/Program.cs @@ -0,0 +1,2 @@ + +Console.WriteLine("Hello, World!"); diff --git a/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/vb/PInvokeLibManaged/NativeMethods.vb b/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/vb/PInvokeLibManaged/NativeMethods.vb new file mode 100644 index 0000000000000..bbccef564a151 --- /dev/null +++ b/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/vb/PInvokeLibManaged/NativeMethods.vb @@ -0,0 +1,94 @@ +Imports System.Runtime.InteropServices + +' +' Managed type declarations that correspond to the unmanaged types in PinvokeLib.dll. + + +Friend Structure MyPoint + Public x As Integer + Public y As Integer +End Structure + + +Friend Structure MyPerson + Public first As String + Public last As String +End Structure + + +Friend Structure MyPerson2 + Public person As IntPtr ' Pointer to a MyPerson structure + Public age As Integer +End Structure + + +Friend Structure MyPerson3 + Public person As MyPerson ' Embedded MyPerson structure + Public age As Integer +End Structure + + +Friend Structure MyUnion + Public i As Integer + Public d As Double +End Structure + + +Friend Structure MyArrayStruct + Public flag As Boolean + + + Public vals As Integer() +End Structure +' + +' +Friend Class NativeMethods + + Friend Shared Function TestArrayOfInts( + <[In], Out> ByVal array() As Integer, ByVal size As Integer) As Integer + End Function + + + Friend Shared Function TestRefArrayOfInts( + ByRef array As IntPtr, ByRef size As Integer) As Integer + End Function + + + Friend Shared Function TestMatrixOfInts( + <[In], Out> ByVal matrix(,) As Integer, ByVal row As Integer) As Integer + End Function + + + Friend Shared Function TestArrayOfStrings( + <[In], Out> ByVal array() As String, ByVal size As Integer) As Integer + End Function + + + Friend Shared Function TestArrayOfStructs( + <[In], Out> ByVal pointArray() As MyPoint, ByVal size As Integer) As Integer + End Function + + + Friend Shared Function TestArrayOfStructs2( + <[In], Out> ByVal personArray() As MyPerson, ByVal size As Integer) As Integer + End Function + + + Friend Shared Function TestStructInStruct( + ByRef person2 As MyPerson2) As Integer + End Function + + + Friend Shared Sub TestStructInStruct3(ByVal person3 As MyPerson3) + End Sub + + + Friend Shared Sub TestUnion(ByVal u As MyUnion, ByVal type As Integer) + End Sub + + + Friend Shared Sub TestArrayInStruct(ByRef myStruct As MyArrayStruct) + End Sub +End Class +' diff --git a/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/vb/PInvokeLibManaged/PInvokeLibManaged.vbproj b/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/vb/PInvokeLibManaged/PInvokeLibManaged.vbproj new file mode 100644 index 0000000000000..b8078e4079e89 --- /dev/null +++ b/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/vb/PInvokeLibManaged/PInvokeLibManaged.vbproj @@ -0,0 +1,9 @@ + + + + Exe + PInvokeLibManaged + net10.0 + + + diff --git a/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/vb/PInvokeLibManaged/Program.vb b/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/vb/PInvokeLibManaged/Program.vb new file mode 100644 index 0000000000000..46283ca23175e --- /dev/null +++ b/docs/framework/interop/snippets/marshalling-data-with-platform-invoke/vb/PInvokeLibManaged/Program.vb @@ -0,0 +1,7 @@ +Imports System + +Module Program + Sub Main(args As String()) + Console.WriteLine("Hello World!") + End Sub +End Module