Copilot instructions

1---
2applyTo: "src/libraries/Common/src/Interop/Windows/HttpApi/**,src/libraries/Common/src/Interop/Windows/IpHlpApi/**,src/libraries/Common/src/Interop/Windows/WinHttp/**,src/libraries/Common/src/Interop/Windows/WinSock/**,src/libraries/Common/src/Interop/Unix/System.Native/**,src/libraries/Common/src/Interop/Unix/System.Net.Security.Native/**,src/native/libs/System.Native/pal_network*"
3---
4 
5# System.Net Interop — Folder-Specific Guidance
6 
7## P/Invoke Declarations
8 
9- Use `LibraryImport` (source-generated) for all new P/Invoke declarations — do not use `DllImport`
10- Mark string parameters with `StringMarshalling.Utf16` (Windows) or `StringMarshalling.Utf8` (Unix) explicitly
11- Use `[return: MarshalAs(UnmanagedType.Bool)]` for native functions returning BOOL to avoid misinterpretation of non-zero values
12- Verify that `SetLastError = true` is set only when the native function documents setting the thread error code
13 
14## SafeHandle Usage
15 
16- Every native handle must be wrapped in a SafeHandle-derived type — never store raw IntPtr in managed fields
17- Override `ReleaseHandle` to call the correct native close/free function — never throw from ReleaseHandle
18- Use `DangerousAddRef`/`DangerousRelease` only when passing handles to native code that may outlive the managed call — prefer CriticalHandle patterns where possible
19- Ensure SafeHandle instances are not disposed while a P/Invoke call using that handle is in flight
20 
21## Error Code Mapping
22 
23- Map Windows error codes (HRESULT, Win32, WSA*) to specific .NET exception types — do not use generic Exception
24- Map Unix errno values to SocketException with the correct SocketError value
25- Use `Marshal.GetLastPInvokeError()` (not `Marshal.GetLastWin32Error()`) to retrieve error codes after LibraryImport calls
26- Preserve the native error code in the exception for diagnostic purposes (e.g., as NativeErrorCode or inner exception)
27 
28## Native Memory Management
29 
30- Allocate native memory with `NativeMemory.Alloc` or `Marshal.AllocHGlobal` — always free in a finally block or via SafeHandle
31- Pin managed arrays with `GCHandle.Alloc(array, GCHandleType.Pinned)` before passing to native code — release in finally
32- For variable-length native structures, allocate sufficient buffer space and handle ERROR_INSUFFICIENT_BUFFER / ERANGE retry patterns
33- Never access native memory after the owning SafeHandle is disposed
34 
35## Struct Layout and Marshaling
36 
37- Use `[StructLayout(LayoutKind.Sequential)]` for all interop structs — verify field order matches the native definition
38- Ensure struct sizes and field offsets are correct for both 32-bit and 64-bit architectures
39- Use fixed-size buffers (`fixed byte[N]`) for inline arrays in native structs rather than MarshalAs.ByValArray
40- Test struct marshaling on all target platforms — padding and alignment rules differ between Windows and Unix
41 
42## Native PAL Code (pal_network*)
43 
44- C PAL functions must return error codes, not throw — the managed caller is responsible for mapping errors
45- Use portable POSIX APIs where possible; isolate platform-specific code behind #ifdef guards
46- Ensure all native allocations are freed on both success and error paths
47- Do not include system headers that are not available on all supported Unix platforms — check build on Linux, macOS, and FreeBSD
48