[API Proposal]: Hide NamedPipeClientStream ctor with isConnected argument

[jozkee]

Background and motivation

As described by #32760 (comment), the constructor

public NamedPipeClientStream(System.IO.Pipes.PipeDirection direction, bool isAsync, bool isConnected, Microsoft.Win32.SafeHandles.SafePipeHandle safePipeHandle)

Using isConnected: false is invalid, it will throw an exception when Connect is called because it requires a path to establish the connection. We should discourage the use of this ctor and instead suggest using a new ctor that doesn't take bool isConnected.

To preserve compatibility in the existing ctor, I think we should ignore isConnected rather than throwing.

Related:
#32760
#83073

API Proposal

namespace System.IO.Pipes;

public sealed partial class NamedPipeClientStream : PipeStream
{
+   [EditorBrowsable(EditorBrowsableState.Never)]
+   [Obsolete("This constructor has been deprecated and argument bool isConnected does not have any effect. Use NamedPipeClientStream(PipeDirection direction, bool isAsync, SafePipeHandle safePipeHandle) instead.")]
    public NamedPipeClientStream(PipeDirection direction, bool isAsync, bool isConnected, SafePipeHandle safePipeHandle) : base (default(PipeDirection), default(int)) { }

+   public NamedPipeClientStream(PipeDirection direction, bool isAsync, SafePipeHandle safePipeHandle) : base(default(PipeDirection), default(int)) { }
}

Alternative Designs

None that I can think of, but I considered fixing the issue by using the provided handle to reconnect to the named pipe server. That doesn't seem feasible, A client Connects by obtaining a handle (via CreateFile in Windows and via Socket.Connect on Unix). reconnecting would imply discarding the existing handle.

Risks

No response

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-io
See info in area-owners.md if you want to be subscribed.

[bartonjs]

Video

• Given that we can find very few callers of this constructor, and isConnected: false doesn't seem to make sense, Obsolete+EB-Never makes sense.
• Use the next available SYSLIB diagnostic ID.

namespace System.IO.Pipes;

public sealed partial class NamedPipeClientStream : PipeStream
{
+   [EditorBrowsable(EditorBrowsableState.Never)]
+   [Obsolete("This constructor has been deprecated and argument bool isConnected does not have any effect. Use NamedPipeClientStream(PipeDirection direction, bool isAsync, SafePipeHandle safePipeHandle) instead.")]
    public NamedPipeClientStream(PipeDirection direction, bool isAsync, bool isConnected, SafePipeHandle safePipeHandle) : base (default(PipeDirection), default(int)) { }

+   public NamedPipeClientStream(PipeDirection direction, bool isAsync, SafePipeHandle safePipeHandle) : base(default(PipeDirection), default(int)) { }
}