Add a sample middle tier implementation for .NET (using ASP.NET Core MVC) (#105)

* initial implementation of a dotnet middle tier

* move folder name for consistency

Author: trrwilson

samples/middle-tier/dotnet-aspnetcore-mvc/AspNetCoreMvcRealtimeMiddletier.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" Version="2.1.0-beta.2" />
+    <PackageReference Include="Azure.Identity" Version="1.13.1" />
+  </ItemGroup>
+
+</Project>

samples/middle-tier/dotnet-aspnetcore-mvc/AspNetCoreMvcRealtimeMiddletier.sln

@@ -0,0 +1,25 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.11.35431.28
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AspNetCoreMvcRealtimeMiddletier", "AspNetCoreMvcRealtimeMiddletier.csproj", "{B98EE1EC-288D-4EF5-B813-64E8F2FB476C}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{B98EE1EC-288D-4EF5-B813-64E8F2FB476C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B98EE1EC-288D-4EF5-B813-64E8F2FB476C}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B98EE1EC-288D-4EF5-B813-64E8F2FB476C}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B98EE1EC-288D-4EF5-B813-64E8F2FB476C}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {73B1440A-2054-4ED0-AA09-75FA0EC80DF2}
+	EndGlobalSection
+EndGlobal

samples/middle-tier/dotnet-aspnetcore-mvc/ClientMessages/ClientMessage.cs

@@ -0,0 +1,45 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace AspNetCoreMvcRealtimeMiddletier.ClientMessages;
+
+/// <summary>
+/// A base representation of a simplified protocol message communicated between the client frontend and this middle
+/// tier implementation.
+/// </summary>
+/// <param name="type"></param>
+[JsonConverter(typeof(ClientMessageJsonConverter))]
+public abstract class ClientMessage(string type)
+{
+    [JsonPropertyName("type")]
+    public string Type { get; set; } = type;
+
+    /// <summary>
+    /// A converter is used to work around limitations with nested polymorphism via [JsonPolymorphic] and [JsonDerivedType].
+    /// </summary>
+    private class ClientMessageJsonConverter : JsonConverter<ClientMessage>
+    {
+        public override ClientMessage? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        {
+            using JsonDocument messageDocument = JsonDocument.ParseValue(ref reader);
+
+            foreach (JsonProperty property in messageDocument.RootElement.EnumerateObject())
+            {
+                if (property.NameEquals("type"u8) && property.Value.GetString() is string typeDiscriminator)
+                {
+                    if (typeDiscriminator == "user_message")
+                    {
+                        return messageDocument.Deserialize<ClientReceivableUserMessage>();
+                    }
+                }
+            }
+
+            throw new NotImplementedException();
+        }
+
+        public override void Write(Utf8JsonWriter writer, ClientMessage value, JsonSerializerOptions options)
+        {
+            JsonSerializer.Serialize(writer, value, value.GetType(), options);
+        }
+    }
+}

samples/middle-tier/dotnet-aspnetcore-mvc/ClientMessages/ClientReceivableMessage.cs

@@ -0,0 +1,21 @@
+using System.Text.Json.Serialization;
+
+namespace AspNetCoreMvcRealtimeMiddletier.ClientMessages;
+
+/// <summary>
+/// The base representation of a simplified protocol message that can sent by the frontend client and received by
+/// this middle tier implementation.
+/// </summary>
+/// <param name="type"></param>
+public abstract class ClientReceivableMessage(string type) : ClientMessage(type)
+{ }
+
+/// <summary>
+/// A user message input, typically associated with text provided by the user.
+/// </summary>
+/// <param name="text"></param>
+public class ClientReceivableUserMessage(string text) : ClientReceivableMessage("user_message")
+{
+    [JsonPropertyName("text")]
+    public string Text { get; } = text;
+}

samples/middle-tier/dotnet-aspnetcore-mvc/ClientMessages/ClientSendableMessage.cs

@@ -0,0 +1,72 @@
+using System.Text.Json.Serialization;
+
+namespace AspNetCoreMvcRealtimeMiddletier.ClientMessages;
+
+/// <summary>
+/// A base representation of a simplified protocol message that can be sent from this middle tier implementation to
+/// a client frontend.
+/// </summary>
+/// <param name="type"></param>
+public abstract class ClientSendableMessage(string type) : ClientMessage(type)
+{ }
+
+/// <summary>
+/// A base representation of a simplified protocol control message that can be sentfrom this middle tier implementation
+/// to a client frontend.
+/// </summary>
+/// <param name="action"></param>
+public abstract class ClientSendableControlMessage(string action) : ClientSendableMessage("control")
+{
+    [JsonPropertyName("action")]
+    public string Action { get; } = action;
+}
+
+/// <summary>
+/// A message sent from this middle tier implementation to the client frontend upon successful connection
+/// establishment. Includes a brief greeting message.
+/// </summary>
+/// <param name="greeting"></param>
+public class ClientSendableConnectedMessage(string greeting) : ClientSendableControlMessage("connected")
+{
+    [JsonPropertyName("greeting")]
+    public string Greeting { get; set; } = greeting;
+}
+
+/// <summary>
+/// A message sent from this middle tier implementation to the client frontend when a start of speech is detected in
+/// the user input audio.
+/// </summary>
+public class ClientSendableSpeechStartedMessage : ClientSendableControlMessage
+{
+    public ClientSendableSpeechStartedMessage() : base("speech_started") { }
+}
+
+/// <summary>
+/// A message sent from this middle tier implementation to the client frontend when a new, incremental piece of
+/// generated text content is available.
+/// </summary>
+/// <param name="delta"></param>
+/// <param name="contentId"></param>
+public class ClientSendableTextDeltaMessage(string delta, string contentId) : ClientSendableMessage("text_delta")
+{
+    [JsonPropertyName("delta")]
+    public string Delta { get; set; } = delta;
+
+    [JsonPropertyName("id")]
+    public string ContentId { get; set; } = contentId;
+}
+
+/// <summary>
+/// A message sent from this middle tier implementation to the client frontend when a transcription of user input
+/// audio is available.
+/// </summary>
+/// <param name="eventId"></param>
+/// <param name="transcription"></param>
+public class ClientSendableTranscriptionMessage(string eventId, string transcription) : ClientSendableMessage("transcription")
+{
+    [JsonPropertyName("id")]
+    public string EventId { get; set; } = eventId;
+
+    [JsonPropertyName("text")]
+    public string Transcription { get; set; } = transcription;
+}