Document multiple client proxy patterns (#1470)

Add comprehensive documentation and working examples for the three patterns
to construct multiple client proxies over a single JSON-RPC connection:

1. Create one proxy implementing multiple interfaces at once
2. Create JsonRpc first, then call instance Attach<T> multiple times
3. Create the first proxy with static Attach<T>, extract the JsonRpc instance
   through IJsonRpcClientProxy, then call instance Attach<T>

This addresses the common mistake of calling static Attach<T> multiple times
on the same stream (which creates multiple distinct JsonRpc instances that
cannot safely share one transport).

Includes code samples in samples/Proxies.cs with dedicated regions for each
pattern and reference documentation in docfx/docs/proxies.md.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: AArnott

docfx/docs/proxies.md

@@ -14,6 +14,28 @@ This changes the above example to something like this:
 
 [!code-csharp[](../../samples/Proxies.cs#WithProxies)]
 
+## Multiple proxies on one connection
+
+Do not call static `JsonRpc.Attach<T>` multiple times on the same stream. Each static call creates a distinct <xref:StreamJsonRpc.JsonRpc> instance, and multiple instances cannot safely share one transport.
+
+The following examples use this second RPC interface in addition to `ICalculator`.
+
+[!code-csharp[](../../samples/Proxies.cs#MultipleProxiesInterfaces)]
+
+When you need multiple client proxies over one connection, use one of these patterns:
+
+1. Create one proxy that implements multiple interfaces at once.
+
+   [!code-csharp[](../../samples/Proxies.cs#MultipleProxiesPattern1)]
+
+1. Create the <xref:StreamJsonRpc.JsonRpc> connection first, then call instance `Attach<T>` for each proxy.
+
+   [!code-csharp[](../../samples/Proxies.cs#MultipleProxiesPattern2)]
+
+1. Create the first proxy with the static `Attach<T>` method, then get its <xref:StreamJsonRpc.JsonRpc> instance through <xref:StreamJsonRpc.IJsonRpcClientProxy> and create additional proxies with instance `Attach<T>` calls.
+
+   [!code-csharp[](../../samples/Proxies.cs#MultipleProxiesPattern3)]
+
 ## Proxy traits
 
 Generated proxies have the following traits:

samples/Proxies.cs

@@ -27,6 +27,59 @@ internal partial interface ICalculator
         }
         #endregion
 
+        #region MultipleProxiesInterfaces
+        [JsonRpcContract, GenerateShape(IncludeMethods = MethodShapeFlags.PublicInstance)]
+        internal partial interface IAdvancedCalculator
+        {
+            Task<int> MultiplyAsync(int a, int b);
+        }
+        #endregion
+
+        static async Task MultipleProxiesOption1(Stream rpcStream)
+        {
+            #region MultipleProxiesPattern3
+            ICalculator calculator = JsonRpc.Attach<ICalculator>(rpcStream);
+            JsonRpc rpc = ((IJsonRpcClientProxy)calculator).JsonRpc;
+            IAdvancedCalculator advancedCalculator = rpc.Attach<IAdvancedCalculator>();
+            using (calculator as IDisposable)
+            using (advancedCalculator as IDisposable)
+            {
+                int sum = await calculator.AddAsync(2, 5);
+                int product = await advancedCalculator.MultiplyAsync(2, 5);
+            }
+            #endregion
+        }
+
+        static async Task MultipleProxiesOption2(Stream rpcStream)
+        {
+            #region MultipleProxiesPattern2
+            using JsonRpc rpc = JsonRpc.Attach(rpcStream);
+            ICalculator calculator = rpc.Attach<ICalculator>();
+            IAdvancedCalculator advancedCalculator = rpc.Attach<IAdvancedCalculator>();
+            using (calculator as IDisposable)
+            using (advancedCalculator as IDisposable)
+            {
+                int sum = await calculator.AddAsync(2, 5);
+                int product = await advancedCalculator.MultiplyAsync(2, 5);
+            }
+            #endregion
+        }
+
+        static async Task MultipleProxiesOption3(Stream rpcStream)
+        {
+            #region MultipleProxiesPattern1
+            using JsonRpc rpc = JsonRpc.Attach(rpcStream);
+            object combinedProxy = rpc.Attach([typeof(ICalculator), typeof(IAdvancedCalculator)], options: null);
+            ICalculator calculator = (ICalculator)combinedProxy;
+            IAdvancedCalculator advancedCalculator = (IAdvancedCalculator)combinedProxy;
+            using (combinedProxy as IDisposable)
+            {
+                int sum = await calculator.AddAsync(2, 5);
+                int product = await advancedCalculator.MultiplyAsync(2, 5);
+            }
+            #endregion
+        }
+
         partial class ServerWithoutInterface
         {
             #region ServerWithoutInterface