Improve emulator connection failure message

CosmosDBShell.Tests/CommandTests/ConnectCommandTests.cs

@@ -68,6 +68,28 @@ public void ConnectCommand_VSCodeCredentialOption_DoesNotProduceUnknownOptionDia
         Assert.DoesNotContain(model.Diagnostics, diagnostic => diagnostic.Code == "SEM002");
     }
 
+    [Fact]
+    public void LocalEmulatorConnectionFailureMessage_ExplainsCommonCauses()
+    {
+        var endpoint = new Uri("https://localhost:8081/");
+        var message = ShellInterpreter.GetLocalEmulatorConnectionFailureMessage(endpoint);
+
+        Assert.Contains("Cosmos DB emulator at https://localhost:8081/", message, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("http://localhost:8081/", message, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("--protocol [https|http]", message, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("https://learn.microsoft.com/en-us/azure/cosmos-db/emulator-linux", message, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public void LocalEmulatorConnectionFailureMessage_SuggestsHttpsWhenHttpFails()
+    {
+        var endpoint = new Uri("http://localhost:8081/");
+        var message = ShellInterpreter.GetLocalEmulatorConnectionFailureMessage(endpoint);
+
+        Assert.Contains("Cosmos DB emulator at http://localhost:8081/", message, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("https://localhost:8081/", message, StringComparison.OrdinalIgnoreCase);
+    }
+
     private static async Task<ConnectCommand> BindConnectCommandAsync(string commandText)
     {
         var parser = new StatementParser(commandText);

CosmosDBShell/Azure.Data.Cosmos.Shell.Core/ShellInterpreter.cs

@@ -641,6 +641,11 @@ internal async Task ConnectAsync(string connectionString, string? loginHint = nu
             catch (Exception ex)
             {
                 client.Dispose();
+                if (isEmulator)
+                {
+                    throw new ShellException(GetLocalEmulatorConnectionFailureMessage(client.Endpoint));
+                }
+
                 throw new ShellException(MessageService.GetString("error-connection_failed"), ex);
             }
 
@@ -903,6 +908,28 @@ private static async Task<AccountProperties> ReadAccountAsync(CosmosClient clien
         return await client.ReadAccountAsync().WaitAsync(token);
     }
 
+    internal static string GetLocalEmulatorConnectionFailureMessage(Uri endpoint)
+    {
+        var alternate = BuildAlternateEmulatorUri(endpoint);
+        return MessageService.GetArgsString(
+            "error-emulator_connection_failed",
+            "endpoint",
+            endpoint.ToString(),
+            "alternate",
+            alternate.ToString());
+    }
+
+    private static Uri BuildAlternateEmulatorUri(Uri endpoint)
+    {
+        var builder = new UriBuilder(endpoint)
+        {
+            Scheme = string.Equals(endpoint.Scheme, Uri.UriSchemeHttps, StringComparison.OrdinalIgnoreCase)
+                ? Uri.UriSchemeHttp
+                : Uri.UriSchemeHttps,
+        };
+        return builder.Uri;
+    }
+
     /// <summary>
     /// Connects to a client & disposes old state.
     /// </summary>

CosmosDBShell/lang/en.ftl

@@ -20,6 +20,12 @@ no_char = N
 
 error = Error:
 error-connection_failed = Failed to connect to the Cosmos DB account.
+error-emulator_connection_failed =
+    Could not reach the Cosmos DB emulator at { $endpoint }.
+    Make sure the emulator is running and reachable.
+    If the protocol is wrong, try { $alternate } (the Linux emulator defaults to HTTP).
+    The emulator container's protocol is set with --protocol [https|http].
+    See: https://learn.microsoft.com/en-us/azure/cosmos-db/emulator-linux
 error-command-not-found = '{ $command }' is not recognized as an internal or external command, operable program or batch file.
 error-shell-not-initialized = Shell is not initialized
 error-start_process = Failed to start the process.