Add service protocol test case & add doc comments

AzureSignalR.sln

@@ -32,6 +32,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "test", "test", "{2429FBD8-1
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Azure.SignalR.Tests", "test\Microsoft.Azure.SignalR.Tests\Microsoft.Azure.SignalR.Tests.csproj", "{764DCFF5-D28D-4CEF-B186-B7A62FBB3E98}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Azure.SignalR.Protocols.Tests", "test\Microsoft.Azure.SignalR.Protocols.Tests\Microsoft.Azure.SignalR.Protocols.Tests.csproj", "{E2094C87-C0F2-471D-A399-0B78CC32C1AA}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -54,6 +56,10 @@ Global
 		{764DCFF5-D28D-4CEF-B186-B7A62FBB3E98}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{764DCFF5-D28D-4CEF-B186-B7A62FBB3E98}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{764DCFF5-D28D-4CEF-B186-B7A62FBB3E98}.Release|Any CPU.Build.0 = Release|Any CPU
+		{E2094C87-C0F2-471D-A399-0B78CC32C1AA}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{E2094C87-C0F2-471D-A399-0B78CC32C1AA}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{E2094C87-C0F2-471D-A399-0B78CC32C1AA}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{E2094C87-C0F2-471D-A399-0B78CC32C1AA}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -63,6 +69,7 @@ Global
 		{B23C2F84-B0B8-47D1-A8D2-E524F6511215} = {C4BC9889-B49F-41B6-806B-F84941B2549B}
 		{2EBFCD26-6E31-4855-ABF5-0A82E78F87C7} = {DA69F624-5398-4884-87E4-B816698CDE65}
 		{764DCFF5-D28D-4CEF-B186-B7A62FBB3E98} = {2429FBD8-1FCE-4C42-AA28-DF32F7249E77}
+		{E2094C87-C0F2-471D-A399-0B78CC32C1AA} = {2429FBD8-1FCE-4C42-AA28-DF32F7249E77}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {7945A4E4-ACDB-4F6E-95CA-6AC6E7C2CD59}

src/Microsoft.Azure.SignalR.Protocols/Internal/BinaryMessageParser.cs → src/Common/BinaryMessageParser.cs

@@ -4,7 +4,7 @@
 using System;
 using System.Buffers;
 
-namespace Microsoft.Azure.SignalR
+namespace Microsoft.Azure.SignalR.Protocol
 {
     internal static class BinaryMessageParser
     {

src/Microsoft.Azure.SignalR.Protocols/ConnectionMessage.cs

@@ -6,43 +6,82 @@
 
 namespace Microsoft.Azure.SignalR.Protocol
 {
+    /// <summary>
+    /// Base class of connection-specific messages between Azure SignalR Service and SDK.
+    /// </summary>
     public abstract class ConnectionMessage : ServiceMessage
     {
         protected ConnectionMessage(string connectionId)
         {
             ConnectionId = connectionId;
         }
 
+        /// <summary>
+        /// Gets or sets the connection Id.
+        /// </summary>
         public string ConnectionId { get; set; }
     }
 
+    /// <summary>
+    /// A open-connection message.
+    /// </summary>
     public class OpenConnectionMessage : ConnectionMessage
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="OpenConnectionMessage"/> class.
+        /// </summary>
+        /// <param name="connectionId">The connection Id.</param>
+        /// <param name="claims">An array of <see cref="Claim"/> associated with the connection.</param>
         public OpenConnectionMessage(string connectionId, Claim[] claims) : base(connectionId)
         {
             Claims = claims;
         }
 
+        /// <summary>
+        /// Gets or sets the associated claims.
+        /// </summary>
         public Claim[] Claims { get; set; }
     }
 
+    /// <summary>
+    /// A close-connection message.
+    /// </summary>
     public class CloseConnectionMessage : ConnectionMessage
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CloseConnectionMessage"/> class.
+        /// </summary>
+        /// <param name="connectionId">The connection Id.</param>
+        /// <param name="errorMessage">Optional error message.</param>
         public CloseConnectionMessage(string connectionId, string errorMessage) : base(connectionId)
         {
             ErrorMessage = errorMessage;
         }
 
+        /// <summary>
+        /// Gets or sets the error message.
+        /// </summary>
         public string ErrorMessage { get; set; }
     }
 
+    /// <summary>
+    /// A connection data message.
+    /// </summary>
     public class ConnectionDataMessage : ConnectionMessage
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ConnectionDataMessage"/> class.
+        /// </summary>
+        /// <param name="connectionId">The connection Id.</param>
+        /// <param name="payload">Binary data to be delivered.</param>
         public ConnectionDataMessage(string connectionId, ReadOnlyMemory<byte> payload) : base(connectionId)
         {
             Payload = payload;
         }
 
+        /// <summary>
+        /// Gets or sets the binary payload.
+        /// </summary>
         public ReadOnlyMemory<byte> Payload { get; set; }
     }
 }

src/Microsoft.Azure.SignalR.Protocols/GroupMessage.cs

@@ -3,23 +3,53 @@
 
 namespace Microsoft.Azure.SignalR.Protocol
 {
+    /// <summary>
+    /// A join-group message.
+    /// </summary>
     public class JoinGroupMessage : ServiceMessage
     {
+        /// <summary>
+        /// Gets or sets the connection Id.
+        /// </summary>
         public string ConnectionId { get; set; }
+
+        /// <summary>
+        /// Gets or sets the group name.
+        /// </summary>
         public string GroupName { get; set; }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="JoinGroupMessage"/> class.
+        /// </summary>
+        /// <param name="connectionId">The connection Id.</param>
+        /// <param name="groupName">The group name, to which the connection will join.</param>
         public JoinGroupMessage(string connectionId, string groupName)
         {
             ConnectionId = connectionId;
             GroupName = groupName;
         }
     }
 
+    /// <summary>
+    /// A leave-group message.
+    /// </summary>
     public class LeaveGroupMessage : ServiceMessage
     {
+        /// <summary>
+        /// Gets or sets the connection Id.
+        /// </summary>
         public string ConnectionId { get; set; }
+
+        /// <summary>
+        /// Gets or sets the group name.
+        /// </summary>
         public string GroupName { get; set; }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="LeaveGroupMessage"/> class.
+        /// </summary>
+        /// <param name="connectionId">The connection Id.</param>
+        /// <param name="groupName">The group name, from which the connection will leave.</param>
         public LeaveGroupMessage(string connectionId, string groupName)
         {
             ConnectionId = connectionId;

src/Microsoft.Azure.SignalR.Protocols/IServiceProtocol.cs

@@ -6,14 +6,36 @@
 
 namespace Microsoft.Azure.SignalR.Protocol
 {
+    /// <summary>
+    /// A protocol abstraction for communication between Azure SignalR Service and SDK.
+    /// </summary>
     public interface IServiceProtocol
     {
+        /// <summary>
+        /// Gets the version of the protocol.
+        /// </summary>
         int Version { get; }
 
+        /// <summary>
+        /// Creates a new <see cref="ServiceMessage"/> from the specified serialized representation.
+        /// </summary>
+        /// <param name="input">The serialized representation of the message.</param>
+        /// <param name="message">When this method returns <c>true</c>, contains the parsed message.</param>
+        /// <returns>A value that is <c>true</c> if the <see cref="ServiceMessage"/> was successfully parsed; otherwise, <c>false</c>.</returns>
         bool TryParseMessage(ref ReadOnlySequence<byte> input, out ServiceMessage message);
 
+        /// <summary>
+        /// Writes the specified <see cref="ServiceMessage"/> to a writer.
+        /// </summary>
+        /// <param name="message">The message to write.</param>
+        /// <param name="output">The output writer.</param>
         void WriteMessage(ServiceMessage message, IBufferWriter<byte> output);
 
+        /// <summary>
+        /// Converts the specified <see cref="ServiceMessage"/> to its serialized representation.
+        /// </summary>
+        /// <param name="message">The message to convert.</param>
+        /// <returns>The serialized representation of the message.</returns>
         ReadOnlyMemory<byte> GetMessageBytes(ServiceMessage message);
     }
 }

src/Microsoft.Azure.SignalR.Protocols/Microsoft.Azure.SignalR.Protocols.csproj

@@ -1,11 +1,14 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
-    <Description>.NET Standard SDK for Protocol used by Azure SignalR and Azure SignalR service.</Description>
+    <Description>.NET Standard SDK for Azure SignalR Service protocol.</Description>
     <TargetFramework>netstandard2.0</TargetFramework>
-    <RootNamespace>Microsoft.Azure.SignalR</RootNamespace>
+    <RootNamespace>Microsoft.Azure.SignalR.Protocol</RootNamespace>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
   <ItemGroup>
+    <Compile Include="..\Common\BinaryMessageFormatter.cs" Link="Internal\BinaryMessageFormatter.cs" />
+    <Compile Include="..\Common\BinaryMessageParser.cs" Link="Internal\BinaryMessageParser.cs" />
     <Compile Include="..\Common\MemoryBufferWriter.cs" Link="Internal\MemoryBufferWriter.cs" />
   </ItemGroup>
 

src/Microsoft.Azure.SignalR.Protocols/MulticastDataMessage.cs

@@ -6,63 +6,128 @@
 
 namespace Microsoft.Azure.SignalR.Protocol
 {
+    /// <summary>
+    /// Base class for multicast data messages between Azure SignalR Service and SDK.
+    /// </summary>
     public abstract class MulticastDataMessage : ServiceMessage
     {
         protected MulticastDataMessage(IDictionary<string, ReadOnlyMemory<byte>> payloads)
         {
             Payloads = payloads;
         }
 
+        /// <summary>
+        /// Gets or sets the payload dictionary which contains binary payload of multiple protocols.
+        /// </summary>
         public IDictionary<string, ReadOnlyMemory<byte>> Payloads { get; set; }
     }
 
+    /// <summary>
+    /// A data message which will be sent to multiple connections.
+    /// </summary>
     public class MultiConnectionDataMessage : MulticastDataMessage
     {
-        public MultiConnectionDataMessage(IReadOnlyList<string> connectionList, IDictionary<string, ReadOnlyMemory<byte>> payloads) :
-            base(payloads)
+        /// <summary>
+        /// Initializes a new instance of the <see cref="MultiConnectionDataMessage"/> class.
+        /// </summary>
+        /// <param name="connectionList">The list of connection Ids.s</param>
+        /// <param name="payloads">The payload dictionary which contains binary payload of multiple protocols.</param>
+        public MultiConnectionDataMessage(IReadOnlyList<string> connectionList,
+            IDictionary<string, ReadOnlyMemory<byte>> payloads) : base(payloads)
         {
             ConnectionList = connectionList;
         }
 
+        /// <summary>
+        /// Gets or sets the list of connections which will receive this message.
+        /// </summary>
         public IReadOnlyList<string> ConnectionList { get; set; }
     }
 
-    // It is possible that the same user has multiple connections. So it is a multi-cast message.
+    /// <summary>
+    /// A data message which will be sent to a user.
+    /// </summary>
     public class UserDataMessage : MulticastDataMessage
     {
+        /// <summary>
+        /// Gets or sets the user Id.
+        /// </summary>
         public string UserId { get; set; }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="UserDataMessage"/> class.
+        /// </summary>
+        /// <param name="userId">The user Id.</param>
+        /// <param name="payloads">The payload dictionary which contains binary payload of multiple protocols.</param>
         public UserDataMessage(string userId, IDictionary<string, ReadOnlyMemory<byte>> payloads) : base(payloads)
         {
             UserId = userId;
         }
     }
 
+    /// <summary>
+    /// A data message which will be sent to multiple users.
+    /// </summary>
     public class MultiUserDataMessage : MulticastDataMessage
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="MultiUserDataMessage"/> class.
+        /// </summary>
+        /// <param name="userList">The list of user Ids.</param>
+        /// <param name="payloads">The payload dictionary which contains binary payload of multiple protocols.</param>
         public MultiUserDataMessage(IReadOnlyList<string> userList, IDictionary<string, ReadOnlyMemory<byte>> payloads) : base(payloads)
         {
             UserList = userList;
         }
 
+        /// <summary>
+        /// Gets or sets the list of user Ids.
+        /// </summary>
         public IReadOnlyList<string> UserList { get; set; }
     }
 
+    /// <summary>
+    /// A data message which will be broadcasted.
+    /// </summary>
     public class BroadcastDataMessage : MulticastDataMessage
     {
+        /// <summary>
+        /// Gets or sets the list of excluded connection Ids.
+        /// </summary>
         public IReadOnlyList<string> ExcludedList { get; set; }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BroadcastDataMessage"/> class.
+        /// </summary>
+        /// <param name="excludedList">The list of excluded connection Ids.</param>
+        /// <param name="payloads">The payload dictionary which contains binary payload of multiple protocols.</param>
         public BroadcastDataMessage(IReadOnlyList<string> excludedList, IDictionary<string, ReadOnlyMemory<byte>> payloads) : base(payloads)
         {
             ExcludedList = excludedList;
         }
     }
 
+    /// <summary>
+    /// A data message which will be broadcasted within a group.
+    /// </summary>
     public class GroupBroadcastDataMessage : MulticastDataMessage
     {
+        /// <summary>
+        /// Gets or sets the group name.
+        /// </summary>
         public string GroupName { get; set; }
+
+        /// <summary>
+        /// Gets or sets the list of excluded connection Ids.
+        /// </summary>
         public IReadOnlyList<string> ExcludedList { get; set; }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GroupBroadcastDataMessage"/> class.
+        /// </summary>
+        /// <param name="groupName">The group name.</param>
+        /// <param name="excludedList">The list of excluded connection Ids.</param>
+        /// <param name="payloads">The payload dictionary which contains binary payload of multiple protocols.</param>
         public GroupBroadcastDataMessage(string groupName, IReadOnlyList<string> excludedList, IDictionary<string, ReadOnlyMemory<byte>> payloads)
             : base(payloads)
         {
@@ -71,10 +136,21 @@ public GroupBroadcastDataMessage(string groupName, IReadOnlyList<string> exclude
         }
     }
 
+    /// <summary>
+    /// A data message which will be broadcasted within multiple groups.
+    /// </summary>
     public class MultiGroupBroadcastDataMessage : MulticastDataMessage
     {
+        /// <summary>
+        /// Gets or sets the list of group names.
+        /// </summary>
         public IReadOnlyList<string> GroupList { get; set; }
-
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="MultiGroupBroadcastDataMessage"/> class.
+        /// </summary>
+        /// <param name="groupList">The list of group names.</param>
+        /// <param name="payloads">The payload dictionary which contains binary payload of multiple protocols.</param>
         public MultiGroupBroadcastDataMessage(IReadOnlyList<string> groupList, IDictionary<string, ReadOnlyMemory<byte>> payloads) : base(payloads)
         {
             GroupList = groupList;