fix: prevent orphaned Power Query connections during worksheet loading (#299)

Root Cause: ListObjects.Add() with connection STRING creates orphaned connections with generic names (Connection, Connection1, etc.) Solution: - Use Connections.Add2() to create properly named connections first - Pass connection OBJECT to ListObjects.Add() to reuse the connection - For LoadToBoth: create TWO connections with distinct names: - Worksheet: 'Query - {name}' - Data Model: 'Query - {name} (Data Model)' - Updated pattern matching in Delete/Unload/List/GetLoadConfig Test Coverage: - 14 new worksheet cleanup tests - 9 lifecycle cleanup tests - All 74+ Power Query tests passing Fixes #298 Co-authored-by: Stefan Broenner <stefan.broenner@microsoft.comm>

Author: sbroenne

src/ExcelMcp.Core/Commands/Connection/ConnectionCommands.Lifecycle.cs

@@ -174,6 +174,11 @@ public void Refresh(IExcelBatch batch, string connectionName, TimeSpan? timeout)
  // Check if this is a Power Query connection (handle separately)
  if (PowerQueryHelpers.IsPowerQueryConnection(conn))
  {
+ // Check if this is an orphaned Power Query connection
+ if (PowerQueryHelpers.IsOrphanedPowerQueryConnection(ctx.Book, conn))
+ {
+ throw new InvalidOperationException($"Connection '{connectionName}' is an orphaned Power Query connection with no corresponding query. Use excel_connection 'delete' to remove it.");
+ }
  throw new InvalidOperationException($"Connection '{connectionName}' is a Power Query connection. Use excel_powerquery 'refresh' instead.");
  }
 
@@ -200,7 +205,13 @@ public void Delete(IExcelBatch batch, string connectionName)
  // Check if this is a Power Query connection
  if (PowerQueryHelpers.IsPowerQueryConnection(conn))
  {
- throw new InvalidOperationException($"Connection '{connectionName}' is a Power Query connection. Use excel_powerquery with action 'Delete' instead.");
+ // Check if this is an orphaned Power Query connection (no corresponding query exists)
+ // Orphaned connections can be safely deleted via the connection API
+ if (!PowerQueryHelpers.IsOrphanedPowerQueryConnection(ctx.Book, conn))
+ {
+ throw new InvalidOperationException($"Connection '{connectionName}' is a Power Query connection. Use excel_powerquery with action 'Delete' instead.");
+ }
+ // Orphaned connection - allow deletion to proceed
  }
 
  // Remove associated QueryTables first

src/ExcelMcp.Core/Commands/PowerQuery/PowerQueryCommands.Create.cs

@@ -98,23 +98,11 @@ public void Create(
  break;
 
  case PowerQueryLoadMode.LoadToBoth:
- // Load to worksheet first
- if (LoadQueryToWorksheet(ctx.Book, queryName, targetSheet!, targetCellAddress!, result))
- {
- // Preserve worksheet properties before loading to Data Model
- int worksheetRows = result.RowsLoaded;
- string? worksheetCell = result.TargetCellAddress;
- string? worksheetName = result.WorksheetName;
-
- // Then also load to Data Model
- if (LoadQueryToDataModel(ctx.Book, queryName, result))
- {
- // Restore worksheet properties (Data Model sets them to null/-1)
- result.RowsLoaded = worksheetRows;
- result.TargetCellAddress = worksheetCell;
- result.WorksheetName = worksheetName;
- }
- }
+ // For LoadToBoth, create TWO separate properly-named connections:
+ // 1. Worksheet connection: "Query - {name}" (created by LoadQueryToWorksheet)
+ // 2. Data Model connection: "Query - {name} (Data Model)" (with suffix to avoid conflict)
+ LoadQueryToWorksheet(ctx.Book, queryName, targetSheet!, targetCellAddress!, result);
+ LoadQueryToDataModel(ctx.Book, queryName, result, " (Data Model)");
  break;
  }
 

src/ExcelMcp.Core/Commands/PowerQuery/PowerQueryCommands.Lifecycle.cs

@@ -149,9 +149,13 @@ public PowerQueryListResult List(IExcelBatch batch)
  string connName = conn.Name?.ToString() ?? "";
 
  // Check if this is a Data Model connection for our query
- // Pattern: "Query - {queryName}" or "Query - {queryName} - suffix"
+ // Patterns:
+ // - "Query - {queryName}" (worksheet connection)
+ // - "Query - {queryName} (Data Model)" (Data Model connection)
+ // - "Query - {queryName} - suffix" (legacy pattern)
  if (connName.Equals($"Query - {name}", StringComparison.OrdinalIgnoreCase) ||
- connName.StartsWith($"Query - {name} -", StringComparison.OrdinalIgnoreCase))
+ connName.StartsWith($"Query - {name} -", StringComparison.OrdinalIgnoreCase) ||
+ connName.StartsWith($"Query - {name} (", StringComparison.OrdinalIgnoreCase))
  {
  // Has Data Model connection - NOT connection-only
  isConnectionOnly = false;
@@ -324,8 +328,15 @@ public PowerQueryLoadConfigResult GetLoadConfig(IExcelBatch batch, string queryN
  string connName = conn.Name?.ToString() ?? "";
 
  // Check if this connection is related to our query
+ // Patterns:
+ // - "{queryName}" (exact match)
+ // - "Query - {queryName}" (worksheet connection)
+ // - "Query - {queryName} (Data Model)" (Data Model connection)
+ // - "Query - {queryName} - suffix" (legacy pattern)
  bool isQueryConnection = connName.Equals(queryName, StringComparison.OrdinalIgnoreCase) ||
- connName.Equals($"Query - {queryName}", StringComparison.OrdinalIgnoreCase);
+ connName.Equals($"Query - {queryName}", StringComparison.OrdinalIgnoreCase) ||
+ connName.StartsWith($"Query - {queryName} -", StringComparison.OrdinalIgnoreCase) ||
+ connName.StartsWith($"Query - {queryName} (", StringComparison.OrdinalIgnoreCase);
 
  // Also check connection string for Power Query pattern
  if (!isQueryConnection)
@@ -513,9 +524,14 @@ public void Delete(IExcelBatch batch, string queryName)
  conn = connections.Item(c);
  string connName = conn.Name?.ToString() ?? "";
 
- // Check if this is a Data Model connection for our query
+ // Check if this is a connection for our query
+ // Patterns:
+ // - "Query - {queryName}" (worksheet connection)
+ // - "Query - {queryName} (Data Model)" (Data Model connection)
+ // - "Query - {queryName} - suffix" (legacy pattern)
  if (connName.Equals($"Query - {queryName}", StringComparison.OrdinalIgnoreCase) ||
- connName.StartsWith($"Query - {queryName} -", StringComparison.OrdinalIgnoreCase))
+ connName.StartsWith($"Query - {queryName} -", StringComparison.OrdinalIgnoreCase) ||
+ connName.StartsWith($"Query - {queryName} (", StringComparison.OrdinalIgnoreCase))
  {
  connectionsToDelete.Add(connName);
  }
@@ -714,10 +730,14 @@ public static OperationResult Unload(IExcelBatch batch, string queryName)
  conn = connections.Item(i);
  string connName = conn.Name?.ToString() ?? "";
 
- // Check if this is a Data Model connection for our query
- // Pattern: "Query - {queryName}" or "Query - {queryName} - Model" etc.
+ // Check if this is a connection for our query
+ // Patterns:
+ // - "Query - {queryName}" (worksheet connection)
+ // - "Query - {queryName} (Data Model)" (Data Model connection)
+ // - "Query - {queryName} - suffix" (legacy pattern)
  if (connName.Equals($"Query - {queryName}", StringComparison.OrdinalIgnoreCase) ||
- connName.StartsWith($"Query - {queryName} -", StringComparison.OrdinalIgnoreCase))
+ connName.StartsWith($"Query - {queryName} -", StringComparison.OrdinalIgnoreCase) ||
+ connName.StartsWith($"Query - {queryName} (", StringComparison.OrdinalIgnoreCase))
  {
  connectionsToDelete.Add(connName);
  }

src/ExcelMcp.Core/Commands/PowerQuery/PowerQueryCommands.LoadTo.cs

@@ -103,21 +103,11 @@ public void LoadTo(
  break;
 
  case PowerQueryLoadMode.LoadToBoth:
- // Load to worksheet first
- if (LoadQueryToWorksheet(ctx.Book, queryName, targetSheet!, targetCellAddress, result))
- {
- // Preserve worksheet properties before loading to Data Model
- int worksheetRows = result.RowsLoaded;
- string? worksheetCell = result.TargetCellAddress;
-
- // Then also load to Data Model
- if (LoadQueryToDataModel(ctx.Book, queryName, result))
- {
- // Restore worksheet properties (Data Model sets them to null/-1)
- result.RowsLoaded = worksheetRows;
- result.TargetCellAddress = worksheetCell;
- }
- }
+ // For LoadToBoth, create TWO separate properly-named connections:
+ // 1. Worksheet connection: "Query - {name}" (created by LoadQueryToWorksheet)
+ // 2. Data Model connection: "Query - {name} (Data Model)" (with suffix to avoid conflict)
+ LoadQueryToWorksheet(ctx.Book, queryName, targetSheet!, targetCellAddress, result);
+ LoadQueryToDataModel(ctx.Book, queryName, result, " (Data Model)");
  break;
 
  case PowerQueryLoadMode.ConnectionOnly:
@@ -166,6 +156,8 @@ private static bool LoadQueryToWorksheet(
  dynamic? worksheets = null;
  dynamic? sheet = null;
  dynamic? destination = null;
+ dynamic? connections = null;
+ dynamic? connection = null;
  dynamic? listObjects = null;
  dynamic? listObject = null;
  dynamic? queryTable = null;
@@ -275,15 +267,30 @@ private static bool LoadQueryToWorksheet(
  }
  }
 
- // Build OLE DB connection string for Power Query
- string connectionString = $"OLEDB;Provider=Microsoft.Mashup.OleDb.1;Data Source=$Workbook$;Location={queryName};Extended Properties=\"\"";
+ // Step 1: Create connection with Connections.Add2() using proper naming
+ // This ensures the connection is named "Query - {queryName}" instead of generic "Connection", "Connection1", etc.
+ connections = workbook.Connections;
+ string connectionName = $"Query - {queryName}";
+ string connectionDescription = $"Connection to the '{queryName}' query in the workbook.";
+ string connectionString = $"OLEDB;Provider=Microsoft.Mashup.OleDb.1;Data Source=$Workbook$;Location={queryName}";
+ string commandText = $"SELECT * FROM [{queryName}]";
+
+ connection = connections.Add2(
+ Name: connectionName,
+ Description: connectionDescription,
+ ConnectionString: connectionString,
+ CommandText: commandText,
+ lCmdtype: 2, // xlCmdSql
+ CreateModelConnection: false, // Worksheet loading, NOT Data Model
+ ImportRelationships: false
+ );
 
- // Add ListObject (Excel Table) with external data source
- // This is the CORRECT way to load Power Query to worksheet
+ // Step 2: Add ListObject using the connection object (not connection string)
+ // This reuses the properly-named connection instead of creating a new generic one
  listObjects = sheet.ListObjects;
  listObject = listObjects.Add(
  0, // SourceType: 0 = xlSrcExternal
- connectionString, // Source: connection string
+ connection,  // Source: connection object (reuses existing named connection)
  Type.Missing, // LinkSource
  1, // XlListObjectHasHeaders: xlYes
  destination // Destination: starting cell
@@ -317,6 +324,8 @@ private static bool LoadQueryToWorksheet(
  ComUtilities.Release(ref queryTable);
  ComUtilities.Release(ref listObject);
  ComUtilities.Release(ref listObjects);
+ ComUtilities.Release(ref connection);
+ ComUtilities.Release(ref connections);
  ComUtilities.Release(ref destination);
  ComUtilities.Release(ref sheet);
  ComUtilities.Release(ref worksheets);
@@ -327,10 +336,15 @@ private static bool LoadQueryToWorksheet(
  /// Loads query data to the Data Model using Connections.Add2.
  /// SHARED IMPLEMENTATION - Used by both Create and LoadTo.
  /// </summary>
+ /// <param name="workbook">The workbook to load into.</param>
+ /// <param name="queryName">The Power Query name.</param>
+ /// <param name="result">Result object to populate.</param>
+ /// <param name="connectionNameSuffix">Optional suffix for connection name to avoid conflicts (e.g., " (Data Model)").</param>
  private static bool LoadQueryToDataModel(
  dynamic workbook,
  string queryName,
- dynamic result)
+ dynamic result,
+ string? connectionNameSuffix = null)
  {
  dynamic? connections = null;
  dynamic? connection = null;
@@ -339,7 +353,10 @@ private static bool LoadQueryToDataModel(
  {
  connections = workbook.Connections;
 
- string connectionName = $"Query - {queryName}";
+ // Use suffix if provided (for LoadToBoth to avoid conflict with worksheet connection)
+ string connectionName = string.IsNullOrEmpty(connectionNameSuffix)
+ ? $"Query - {queryName}"
+ : $"Query - {queryName}{connectionNameSuffix}";
  string description = $"Connection to the '{queryName}' query in the workbook.";
  string connectionString = $"OLEDB;Provider=Microsoft.Mashup.OleDb.1;Data Source=$Workbook$;Location={queryName}";
  string commandText = $"\"{queryName}\"";

src/ExcelMcp.Core/Commands/PowerQuery/PowerQueryHelpers.cs

@@ -7,6 +7,65 @@ namespace Sbroenne.ExcelMcp.Core.PowerQuery;
 /// </summary>
 public static class PowerQueryHelpers
 {
+ /// <summary>
+ /// Determines if a Power Query connection is orphaned (no corresponding query exists).
+ /// An orphaned connection is one that appears to be a Power Query connection (based on
+ /// connection string or naming pattern) but has no matching entry in the Queries collection.
+ /// This commonly occurs after query deletions, renames, or copy/paste operations in Excel.
+ /// 
+ /// A connection is considered orphaned if:
+ /// 1. It's a Power Query connection (uses Microsoft.Mashup provider)
+ /// 2. AND EITHER:
+ /// a. It doesn't follow the standard "Query - {queryName}" naming pattern (e.g., "Connection", "Connection1")
+ /// b. OR it follows the pattern but the corresponding query no longer exists in Workbook.Queries
+ /// </summary>
+ /// <param name="workbook">Excel workbook COM object</param>
+ /// <param name="connection">Connection COM object</param>
+ /// <returns>True if connection is a Power Query connection with no corresponding query</returns>
+ public static bool IsOrphanedPowerQueryConnection(dynamic workbook, dynamic connection)
+ {
+ // First check if this is even a Power Query connection
+ if (!IsPowerQueryConnection(connection))
+ {
+ return false;
+ }
+
+ string connectionName = connection.Name?.ToString() ?? "";
+
+ // Check if connection follows the standard "Query - {queryName}" naming pattern
+ // Only connections with this pattern are considered "proper" Power Query connections
+ if (!connectionName.StartsWith("Query - ", StringComparison.OrdinalIgnoreCase))
+ {
+ // Generic names like "Connection", "Connection1", etc. are ALWAYS orphaned
+ // even if their Location= points to an existing query.
+ // The proper connection for a query is always named "Query - {queryName}".
+ return true;
+ }
+
+ // Extract the query name from the "Query - {queryName}" pattern
+ string expectedQueryName = connectionName["Query - ".Length..];
+
+ // Handle potential suffixes like "Query - Name - Model" (though rare)
+ int dashIndex = expectedQueryName.IndexOf(" -", StringComparison.Ordinal);
+ if (dashIndex > 0)
+ {
+ expectedQueryName = expectedQueryName[..dashIndex];
+ }
+
+ // Check if a query with this name exists
+ dynamic? query = null;
+ try
+ {
+ query = ComUtilities.FindQuery(workbook, expectedQueryName);
+ // If query is null, the connection is orphaned
+ return query == null;
+ }
+ finally
+ {
+ ComUtilities.Release(ref query);
+ }
+ }
+
  /// <summary>
  /// Determines if a connection is a Power Query connection
  /// </summary>