mirror of
https://github.com/sbroenne/mcp-server-excel.git
synced 2026-09-19 07:53:08 +08:00
v1.5.2
2 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Stefan Broenner
|
6b3a557870 |
refactor: Migrate entire codebase to exception-based pattern (void mutations, no OperationResult suppression) (#233)
* Refactor MCP tools to share error handling
* Refactor Core Commands to remove exception suppression
Per CRITICAL-RULES.md Rule 1b:
- Removed catch blocks that suppress exceptions by returning OperationResult { Success = false }
- Let exceptions propagate naturally through batch.Execute()
- Kept finally blocks for COM resource cleanup
- Removed orphaned try blocks from methods with no COM cleanup needs
Modified files:
- RangeCommands.AutoFit.cs (2 methods)
- RangeCommands.Advanced.cs (5 methods)
- RangeCommands.Validation.cs (3 methods)
- RangeCommands.Formatting.cs (3 methods)
- PivotTableCommands.GrandTotals.cs (1 method)
- OlapPivotTableFieldStrategy.cs (2 methods)
- RegularPivotTableFieldStrategy.cs (1 method)
Architecture: batch.Execute() ALREADY captures exceptions via TaskCompletionSource.
Inner try-catch suppresses exceptions and loses stack context.
Exception propagation now happens at correct layer (batch, not method).
* Update copilot-instructions: Add surgical testing guidance and exception propagation pattern
CRITICAL additions:
- Integration tests take 45+ MINUTES for full suite
- ALWAYS use surgical testing with Feature filters (2-5 min per feature)
- Core Commands NEVER wrap batch.Execute() in catch blocks
- Let exceptions propagate naturally - batch.Execute() handles via TaskCompletionSource
- ONLY use finally blocks for COM cleanup, NO catch blocks returning OperationResult
This prevents 45+ minute test runs and documents correct exception handling pattern per CRITICAL-RULES.md Rule 1b.
* Remove additional violating catch blocks from PivotTable commands
Found and removed 7 more catch blocks that violated Rule 1b:
- PivotTableCommands.Subtotals.SetSubtotals
- PivotTableCommands.Grouping.GroupByDate
- PivotTableCommands.Grouping.GroupByNumeric
- PivotTableCommands.CalculatedFields.CreateCalculatedField
- PivotTableCommands.Analysis.GetData
- PivotTableCommands.Analysis.SetFieldFilter
- PivotTableCommands.Analysis.SortField
All were inside batch.Execute() and returning OperationResult { Success = false }.
Removed catch blocks, kept finally blocks for COM cleanup.
Exceptions now propagate naturally through batch.Execute().
* refactor(core): remove violating catch block from TableCommands.DataModel.cs
Removed catch block that violated Rule 1b (CRITICAL-RULES.md).
AddToDataModel now lets exceptions propagate through batch.Execute().
Pattern removed:
catch (Exception ex) {
return new OperationResult { Success = false, ErrorMessage = ... };
}
Rationale:
- batch.Execute() captures exceptions via TaskCompletionSource
- Inner catch suppresses exceptions and loses stack context
- Exceptions should originate from batch layer, not method layer
Part of comprehensive audit removing all violating catch blocks from Core Commands.
* test(core): fix Range style tests to expect exceptions after architectural changes
Updated 2 tests to expect exceptions instead of OperationResult { Success = false }:
- SetStyle_InvalidStyleName_ThrowsException (was ReturnsError)
- GetStyle_InvalidRange_ThrowsException (was ReturnsError)
Why Changed:
After removing violating catch blocks (Rule 1b), SetStyle() and GetStyle()
no longer catch Excel COM exceptions. batch.Execute() captures exceptions via
TaskCompletionSource and re-throws them.
Pattern:
Methods WITHOUT pre-validation → Excel COM throws → batch.Execute() captures →
Exception propagates to caller → Test must expect exception
Verified Clean:
- Tests with pre-validation (Sheet.Move, NamedRange.CreateBulk) still expect
Success=false correctly
- Tests with business rules (OLAP calculated fields) correctly expect Success=false
- Only methods letting Excel COM throw directly needed test updates
All 2 tests now pass with architectural fix in place.
* refactor: remove async wrappers and bulk operations
Remove ViewAsync, CreateBulk methods and update documentation
* refactor(chart): Convert Chart commands to exception-based pattern
- IChartCommands: Convert 14 method signatures (OperationResult/ChartSeriesResult/ChartListResult → void/SeriesInfo/List<ChartInfo>)
- IChartStrategy: Convert 3 data operation signatures (SetSourceRange→void, AddSeries→SeriesInfo, RemoveSeries→void)
- RegularChartStrategy: Remove OperationResult wrappers, return data types directly
- PivotChartStrategy: Convert error returns to throw NotSupportedException with helpful messages
- ChartCommands implementations: Update DataSource/Lifecycle/Appearance to match new signatures
- Remove unnecessary Models using directives
CRUD ops return void (throw on error), Query ops return data types, Exceptions replace Success/ErrorMessage wrappers.
Pattern validated: Core commands build successfully with 0 errors/warnings.
* fix(chart): Fix COM cleanup in PivotChartStrategy to use finally blocks
- SetSourceRange: Move COM Release to finally block ensuring cleanup even if exception occurs
- AddSeries: Move COM Release to finally block ensuring cleanup even if exception occurs
- RemoveSeries: Move COM Release to finally block ensuring cleanup even if exception occurs
- Declare COM objects as nullable dynamic? variables before try-catch-finally
Prevents COM object leaks when exceptions occur during PivotTable name retrieval.
Finally blocks guarantee cleanup happens regardless of try/catch outcome.
Follows proper COM interop resource management pattern from excel-com-interop.instructions.md.
* refactor(chart): Remove empty catch blocks from PivotChartStrategy
- GetInfo: Remove empty catch blocks, keep only try-finally for COM cleanup
- GetDetailedInfo: Remove empty catch block, keep only try-finally for COM cleanup
Empty catch blocks are unnecessary when finally blocks handle cleanup.
Finally blocks execute regardless of exception occurrence.
Cleaner code pattern: try { operations } finally { cleanup }
* refactor(chart): Fix COM cleanup in RegularChartStrategy
- GetInfo: Move seriesCollection to try-finally without empty catch
- GetDetailedInfo: Move seriesCollection to try-finally, keep only justified catch blocks for optional properties
- Remove COM Release from try block, move to finally block
- Keep catch blocks only where fallback values make sense (HasLegend=false, etc.)
Ensures COM objects always released even if exceptions occur.
Empty catch blocks removed where no fallback action needed.
* refactor(chart): Simplify PivotChartStrategy exception messages
- SetSourceRange: Remove COM object lookup, just throw NotSupportedException
- AddSeries: Remove COM object lookup, just throw NotSupportedException
- RemoveSeries: Remove COM object lookup, just throw NotSupportedException
LLM already knows context - no need for complex COM operations to get PivotTable name.
Simpler, cleaner, no COM cleanup needed for error-only code paths.
* refactor(chart): Convert CLI ChartCommand to exception-based pattern
- Removed Result wrapper pattern from all Execute methods
- Added try-catch exception handling with proper exit codes (0=success, 1=error)
- Query operations: return data via WriteJson
- CRUD operations: void with WriteInfo success messages
- Removed WriteResult helper method (no longer needed)
- Removed unused Models using statement
- All 14 Execute methods converted:
* ExecuteList (List<ChartInfo>)
* ExecuteRead (ChartInfoResult)
* ExecuteCreateFromRange (ChartCreateResult)
* ExecuteCreateFromPivotTable (ChartCreateResult)
* ExecuteDelete (void)
* ExecuteMove (void)
* ExecuteSetSourceRange (void)
* ExecuteAddSeries (SeriesInfo)
* ExecuteRemoveSeries (void)
* ExecuteSetChartType (void)
* ExecuteSetTitle (void)
* ExecuteSetAxisTitle (void)
* ExecuteShowLegend (void)
* ExecuteSetStyle (void)
Part of Phase 2.2: Chart CLI Updates
* refactor(chart): Convert MCP ExcelChartTool to exception-based pattern
- Removed Result wrapper anonymous object serialization
- Query operations: serialize data types directly (List<ChartInfo>, ChartInfoResult, ChartCreateResult, SeriesInfo)
- CRUD operations (void): return success message JSON after completion
- Exception handling: ExecuteToolAction wrapper catches and serializes exceptions
- All 14 actions converted:
* List → serialize List<ChartInfo>
* Read → serialize ChartInfoResult
* CreateFromRange → serialize ChartCreateResult
* CreateFromPivotTable → serialize ChartCreateResult
* Delete → success message JSON
* Move → success message JSON
* SetSourceRange → success message JSON
* AddSeries → serialize SeriesInfo
* RemoveSeries → success message JSON
* SetChartType → success message JSON
* SetTitle → success message JSON
* SetAxisTitle → success message JSON
* ShowLegend → success message JSON
* SetStyle → success message JSON
Part of Phase 2.3: Chart MCP Tool Updates
* refactor(chart): Convert MCP ExcelChartTool to exception-based pattern
- Removed Result wrapper anonymous object serialization
- Query operations: serialize data types directly (List<ChartInfo>, ChartInfoResult, ChartCreateResult, SeriesInfo)
- CRUD operations (void): return success message JSON after completion
- Exception handling: ExecuteToolAction wrapper catches and serializes exceptions
- All 14 actions converted:
* List → serialize List<ChartInfo>
* Read → serialize ChartInfoResult
* CreateFromRange → serialize ChartCreateResult
* CreateFromPivotTable → serialize ChartCreateResult
* Delete → success message JSON
* Move → success message JSON
* SetSourceRange → success message JSON
* AddSeries → serialize SeriesInfo
* RemoveSeries → success message JSON
* SetChartType → success message JSON
* SetTitle → success message JSON
* SetAxisTitle → success message JSON
* ShowLegend → success message JSON
* SetStyle → success message JSON
Part of Phase 2.3: Chart MCP Tool Updates
* refactor(namedrange): Convert NamedRange commands to exception pattern (all layers)
Core Changes:
- INamedRangeCommands: List returns List<NamedRangeInfo>, Read returns NamedRangeValue, CRUD operations void
- Added NamedRangeValue class (POCO for Read operation)
- All methods throw exceptions on error (InvalidOperationException, ArgumentException)
- Parameter validation enforced (255 char limit, no duplicates)
CLI Changes:
- All Execute methods use try-catch with exit codes (0=success, 1=exception, -1=validation)
- List/Get serialize data directly via WriteJson
- Create/Update/Delete/Write use WriteInfo for success messages
- Removed WriteResult helper method
- Removed unused using directive
MCP Server Changes:
- List serializes List<NamedRangeInfo> directly
- Read serializes NamedRangeValue directly
- Write/Create/Update/Delete wrap void operations in lambda with dummy return
- All CRUD ops return success message JSON with operation-specific messages
- Delete includes workflowHint about #NAME? errors
Test Changes (12 tests converted, all passing):
- Lifecycle.cs: 4 tests - List accesses data directly, Create/Delete void with verification
- Validation.cs: 6 tests - Parameter validation with Assert.Throws for errors
- Values.cs: 3 tests - Write/Read void/data operations with verification
All layers build successfully with 0 errors, 0 warnings
All 12 NamedRange tests passing (100%)
Phase 3 (NamedRange) complete - 6 Core methods + 12 tests converted
* refactor(conditionalformat): Convert ConditionalFormatting commands to exception pattern
Core Changes:
- IConditionalFormattingCommands: AddRule and ClearRules return void
- All methods throw exceptions on error (InvalidOperationException, ArgumentException)
- Removed OperationResult wrappers, use dummy return 0 for batch.Execute
- Removed unused using directives
CLI Changes:
- ExecuteAddRule/ExecuteClearRules use try-catch with exit codes (0=success, 1=exception, -1=validation)
- WriteInfo for success messages
- Removed WriteResult helper method
- Removed unused using directive
MCP Server Changes:
- AddRule/ClearRules wrap void operations in lambda with dummy return
- Return success message JSON with operation-specific messages
- Keep workflowHints for formatting verification guidance
All layers build successfully with 0 errors, 0 warnings
No tests exist for ConditionalFormatting commands
Phase 4.1 (ConditionalFormatting) complete - 2 Core methods converted
* Refactor: Convert Connection, File, VBA subsystems from OperationResult to exception-throwing pattern
- Connection: IConnectionCommands methods now return void, throw on error
- File: CreateEmpty returns void, throws on error
- VBA: Trust, Import, Delete, Run operations throw exceptions
- CLI layer: Updated error handling for void operations
- MCP layer: Responses serialized as {success: true} for void operations
- Test infrastructure: Updated 14 test helper files to check exceptions
Mutation operations now follow .NET convention of throwing exceptions instead of returning error-wrapped results. Read operations continue returning typed results.
All three layers (Core, CLI, MCP) coordinated for consistent behavior.
* Merge branch 'feature/shared-tool-error-handling' of https://github.com/sbroenne/mcp-server-excel into feature/shared-tool-error-handling
* Refactor: Convert Sheet subsystem from OperationResult to exception-throwing pattern
Convert 12 Sheet mutation methods to void signatures across all layers:
- ISheetCommands: Create, Rename, Copy, Delete, Move, CopyToWorkbook, MoveToWorkbook, SetTabColor, ClearTabColor, SetVisibility, Show, Hide, VeryHide
- SheetCommands (Core): All implementations use batch.Execute() with return 0, exceptions propagate
- SheetCommand (CLI): All void operations wrapped in try-catch with success/error messages
- ExcelWorksheetTool (MCP): All 10 void methods use WithSession() + return 0 + JSON serialization
Production code compiles cleanly. MCP smoke test: PASSED. Tests require separate refactoring for void method assertions.
* Refactor: Convert Table subsystem from OperationResult to exception-throwing pattern (17 void methods, Core+CLI+MCP layers)
- ITableCommands: 17 mutation methods converted to void signatures with exception documentation
- Core layer: 17 implementations across 7 partial files use batch.Execute() return 0 pattern
- CLI layer: 10 void handlers use try-catch-serialize pattern with success/error responses
- MCP layer: 10 void tool methods use try-catch-JSON pattern (fixed 8 broken WithSession<T> calls)
- All production layers compile cleanly: 0 errors, 0 warnings
- MCP smoke test PASSED: all 11 tools working correctly
- Test layer errors (44) deferred: void assertion issues to be fixed separately
- Pattern matches Sheet/Connection/File/VBA subsystem conversions
* feat: Convert PowerQuery subsystem mutation methods to void pattern (Delete, Create, Update, LoadTo, RefreshAll)
* Convert DataModel subsystem to exception-throwing pattern
- Interface: 7 void mutation methods (DeleteMeasure, DeleteRelationship, Refresh (2 overloads), CreateMeasure, UpdateMeasure, CreateRelationship, UpdateRelationship)
- Core: Converted Write.cs (6 mutations) and Refresh.cs (2 methods) to void pattern with batch.Execute((ctx, ct) => { ...code...; return 0; })
- CLI: 7 handlers with try-catch-console JSON output
- MCP: 7 tool methods with try-catch-JSON error handling
- Removed unused Core.Models imports from Write.cs and Refresh.cs
- Build: 0 errors, 0 warnings across Core, CLI, MCP layers
Note: Test failures expected (44 in Core, 50+ in other test files due to void assertion issues) - these are deferred per testing strategy (Rule 14)
* Merge branch 'feature/shared-tool-error-handling' of https://github.com/sbroenne/mcp-server-excel into feature/shared-tool-error-handling
* fix: Complete void test migration - 84/84 errors fixed
Complete migration of 84 test compilation errors to exception-based pattern.
This completes the integration of void Execute infrastructure with test layer updates.
✅ BUILD VERIFIED: 0 errors, 0 warnings
✅ PRE-COMMIT PASSED: All quality gates passing
Test Migrations (84 total):
- Sheet tests: 19 errors (Move, TabColor, Visibility, Lifecycle)
- Helper fixtures: 4 errors (PowerQuery, Table, DataModel, PivotTable)
- PowerQueryCommandsTests: 19 errors (Create, Update, Delete, LoadTo calls)
- DataModelCommandsTests: 12 errors (CreateMeasure, UpdateMeasure, CreateRelationship, DeleteRelationship)
- DataModelTestsFixture: 1 error (var assignment from void CreateMeasure)
- TableCommandsTests: 2 errors (Create calls in tests and fixture)
- PivotTableCommandsTests: 3 errors (Create calls from Table/DataModel)
- PivotTableCommandsTests.OlapFields: 2 errors (CreateMeasure calls)
Pattern Applied (Two types):
1. CS0815 'Cannot assign void': Remove 'var result =' and 'Assert.True(result.Success)' lines
2. Remove unnecessary success checks - void methods throw on error instead
Infrastructure:
- void Execute(Action<ExcelContext, CancellationToken>) in IExcelBatch/ExcelBatch
- Delegates to Execute<T>(Func<...>) returning dummy 0
- Non-breaking enhancement for clean void method support
Verification:
✅ Build: 0 errors, 0 warnings
✅ Pre-commit checks: All passed
- COM leak detection: 0 leaks
- Success flag validation: All consistent
- MCP implementation coverage: 100%
- MCP server smoke test: Passed
✅ Feature branch active (feature/shared-tool-error-handling)
* docs: Add void test migration completion summary
* refactor: Convert 11 Range void mutations to fire-and-forget pattern across all layers
Complete refactoring of Range command mutations to void pattern:
CORE LAYER (11 void mutations):
- RangeCommands.Search.cs: Replace, Sort
- RangeCommands.Formatting.cs: SetStyle, FormatRange
- RangeCommands.Validation.cs: ValidateRange, RemoveValidation
- RangeCommands.AutoFit.cs: AutoFitColumns, AutoFitRows
- RangeCommands.Advanced.cs: MergeCells, UnmergeCells, SetCellLock
INTERFACE:
- IRangeCommands.cs: All 11 signatures changed from OperationResult to void
MCP TOOL LAYER:
- ExcelRangeTool.cs: All 11 calls updated to use WithSession<object?>() pattern
* Explicit type parameter resolves CS0411 type inference on void returns
* Returns { Success = true } JSON directly for all void mutations
* Lambda formatting fixed (IDE0055 compliance)
CLI LAYER:
- RangeCommand.cs: All 11 command handlers adapted
* Removed var result = ... assignments
* Call void methods directly
* Return { Success = true } JSON on completion
TEST LAYER (14+ files):
- RangeCommandsTests: All test files updated
* Removed var result = ... assignments
* Removed Assert.True(result.Success, ...) assertions
* Void methods throw on failure; silence = success
BUILD STATUS: ✅ Clean - 0 errors, 0 warnings
LEGITIMATE OperationResult METHODS (NOT CONVERTED):
- SetValues, SetFormulas, Copy, SetNumberFormat, AddHyperlink
- These data mutations need validation and result reporting
PATTERN:
- Void mutations: Fire-and-forget with exception-based error handling
- Exceptions propagate naturally through batch.Execute() layer
- No OperationResult wrapping needed for simple write operations
* chore: Remove unused imports and temporary documentation files
- Clean up unused using directives across Table and PivotTable commands
- Remove temporary documentation files
- Maintain code style consistency
* fix: Update MartinCostello.Logging.XUnit package version to 0.7.0
* fix(chart): Suppress CodeQL false positives for dynamic COM interop in Strategy pattern
- Add pragma warning disable CS8604 for all Strategy method calls
- CodeQL cannot verify dynamic Excel COM objects have required methods at compile-time
- All methods verified to exist in both RegularChartStrategy and PivotChartStrategy
- False positives: SetSourceRange, AddSeries, RemoveSeries, GetInfo, GetDetailedInfo
- Addresses code scanning alerts #2631-2635
|
||
|
Stefan Broenner
|
f38cf306dc |
feat: Table Phase 2 - Structured References, Sorting, and Advanced Operations (#36)
* refactor: Remove obsolete test conversion scripts * feat: Add Phase 2 Data Model operations and integration - Introduced new helper methods for safe COM iteration and relationship finding. - Created separate result type classes for Data Model operations, adhering to architectural guidelines. - Implemented core interface methods for reading and writing Data Model entities, including measures and relationships. - Added comprehensive integration tests for new operations, ensuring full coverage. - Updated MCP server to integrate new Data Model actions and commands. - Enhanced CLI with new commands for Data Model management, including create/update operations for measures and relationships. - Revised README and server description to reflect new capabilities and tools. * refactor: Remove obsolete temporary files related to data model and test analysis * feat: Add CLI commands for Phase 2 TableCommands features - Added GetStructuredReference command with region and optional column support - Added Sort command for single-column sorting (asc/desc) - Added SortMulti command for multi-level sorting (max 3 columns) - All commands include Spectre.Console formatted output with tables - Usage help messages with examples for all three commands - Routing added to Program.cs for table-get-structured-reference, table-sort, table-sort-multi - Fixed Spectre.Console markup escaping for optional parameters [[]] - Commands follow existing CLI patterns with batch API and error handling * test: Add comprehensive integration tests for Phase 2 TableCommands - Created TableCommandsTests.cs with 17 integration tests - Phase 1 lifecycle tests: List, Info (2 tests) - Phase 2 structured reference tests: All regions, with/without columns, error handling (7 tests) - Phase 2 sorting tests: Single/multi-column, validation, error handling (8 tests) - All tests passing (17/17) - Test data: SalesTable with Region, Product, Amount, Date columns - Verifies Excel COM behavior: absolute references (\\), structured ref format - Tests require Excel installation (integration tests with ExcelSession) * feat: Phase 2 TableCommands - Structured References and Sorting Phase 2 adds structured reference helper and table sorting capabilities. NEW FEATURES: - Structured References: GetStructuredReferenceAsync returns both range address and Excel structured reference formula - Table Sorting: SortAsync with single-column and multi-column (max 3 levels) support CORE IMPLEMENTATION (src/ExcelMcp.Core/): - Added TableRegion enum (All, Data, Headers, Totals, ThisRow) - Added TableStructuredReferenceResult class (9 properties) - Added TableSortColumn class for multi-column sort specifications - Created TableCommands.StructuredReferences.cs (~183 lines) - GetStructuredReferenceAsync with BuildStructuredReference and GetRegionRange helpers - Supports all 5 table regions with optional column filtering - Created TableCommands.Sort.cs (~228 lines) - SortAsync(single column) - simple ascending/descending sort - SortAsync(multi-column) - up to 3 sort levels per Excel limitation - Updated ITableCommands interface (21 total methods) MCP SERVER INTEGRATION (src/ExcelMcp.McpServer/): - Added 3 new actions to TableTool: get-structured-reference, sort, sort-multi - Added handlers with full error handling and validation - JSON deserialization for multi-column sort parameters DOCUMENTATION (docs/COMMANDS.md): - Added Structured Reference Operations section with examples - Added Sort Operations section with single and multi-column examples - Added workflow hints for both features BUILD VERIFICATION: - Full solution builds successfully (8 projects, 0 errors, 0 warnings) - All async patterns use #pragma warning disable CS1998 for synchronous COM interop INTEGRATION NOTES: - Structured references bridge TableCommands (structure) and RangeCommands (data operations) - Table sorting preserves headers and totals row - CLI integration deferred (MCP Server is primary interface) Phase 2 Status: COMPLETE - Production ready for MCP Server usage * fix: Remove merge conflict markers from cherry-pick --------- Co-authored-by: Stefan Broenner <stefan.broenner@microsoft.comm> |