Copilot instructions

1---
2applyTo: "src/libraries/System.Net.Primitives/**,src/libraries/System.Net.NameResolution/**,src/libraries/System.Net.NetworkInformation/**,src/libraries/System.Net.Ping/**,src/libraries/System.Net.WebSockets/**,src/libraries/System.Net.WebSockets.Client/**,src/libraries/System.Net.Mail/**,src/libraries/System.Net.Requests/**"
3---
4 
5# System.Net Common Libraries — Folder-Specific Guidance
6 
7## Cross-Platform PAL
8 
9- Each library may have Windows, Unix, and macOS implementations — changes to one PAL must be evaluated for all platforms
10- Use platform-abstraction layers (e.g., SocketPal, NetworkInterfacePal) rather than #if directives in shared code
11- Platform-specific files follow the naming convention `*.Windows.cs`, `*.Unix.cs`, `*.OSX.cs` — place new platform code in the correct file
12 
13## DNS and Name Resolution
14 
15- DNS resolution results may be cached — ensure cache invalidation logic handles TTL and negative caching correctly
16- Dns.GetHostEntryAsync must handle both forward (hostname → IP) and reverse (IP → hostname) lookups
17- DNS failures must produce SocketException with the correct SocketError (HostNotFound, TryAgain, NoData)
18- Test DNS behavior with both IPv4 and IPv6 addresses, including IPv6 scope IDs
19 
20## IP Address and Endpoint Handling
21 
22- IPAddress.Parse and TryParse must handle all valid formats: dotted-decimal, IPv6, IPv4-mapped IPv6, and scoped addresses
23- Avoid allocating when parsing well-formed addresses on hot paths — use Span-based TryFormat/TryParse overloads
24- IPEndPoint equality comparisons must account for scope ID differences in IPv6 addresses
25 
26## URI Handling
27 
28- URI parsing changes must preserve backward compatibility — many callers depend on current escaping and normalization behavior
29- Handle internationalized domain names (IDN) correctly through Punycode encoding
30- Percent-encoding must round-trip correctly — do not double-encode or decode reserved characters
31 
32## WebSocket Specifics
33 
34- WebSocket connection upgrade must validate the HTTP 101 response including Sec-WebSocket-Accept header
35- WebSocket framing (mask, opcode, payload length) must follow RFC 6455 exactly
36- WebSocket close handshake requires sending and receiving Close frames — track close state to avoid double-close
37- Dispose must abort the underlying connection if the close handshake has not completed
38 
39## Legacy API Compatibility (HttpWebRequest, SmtpClient)
40 
41- HttpWebRequest and SmtpClient are legacy APIs — fixes should maintain behavioral compatibility, not modernize the API surface
42- HttpWebRequest delegates to HttpClient internally — changes must not break this delegation layer
43- SmtpClient changes must handle both synchronous Send and async SendMailAsync code paths
44 
45## Ping
46 
47- Ping uses raw sockets on Unix and ICMP APIs on Windows — test on all platforms
48- Ping timeout and TTL handling differs per platform — ensure consistent behavior at the managed API level
49 
50## Diagnostics
51 
52- Use NetEventSource for tracing in all System.Net libraries — maintain consistent event IDs across libraries
53- Never log personally identifiable information, email content, or credentials
54