mcp-server-ppt: Instructions file for GitHub Copilot

PowerPoint COM Interop Patterns

Essential patterns for PowerPoint COM automation

Core Principles

1. Use Late Binding - dynamic types with Type.GetTypeFromProgID()
2. 1-Based Indexing - PowerPoint collections start at 1, not 0
3. Exception Propagation - Never wrap in try-catch, let batch.Execute() handle exceptions (see Exception Propagation section)

Reference Resources

NetOffice Library - THE BEST source for ALL PowerPoint COM Interop patterns:

• GitHub: https://github.com/NetOfficeFw/NetOffice
• Use for ALL COM Interop work - slides, shapes, presentations, charts, tables, VBA, everything
• NetOffice wraps Office COM APIs in strongly-typed C# - study their patterns for dynamic interop conversion
• Search NetOffice repository BEFORE implementing any PowerPoint COM automation
• Particularly valuable for: Shapes, Slide layouts, Masters, Animations, complex COM scenarios

Exception Propagation Pattern (CRITICAL)

Core Commands: NEVER wrap operations in try-catch blocks that return error results. Let exceptions propagate naturally.

// ❌ WRONG: Catching and wrapping exceptions
public async Task<OperationResult> CreateAsync(IPptBatch batch, string name)
{
    try
    {
        return await batch.Execute((ctx, ct) => {
            var item = ctx.Create(name);
            return ValueTask.FromResult(new OperationResult { Success = true });
        });
    }
    catch (Exception ex)
    {
        // ❌ WRONG: Double-wrapping suppresses the exception
        return new OperationResult { Success = false, ErrorMessage = ex.Message };
    }
}

// ✅ CORRECT: Let batch.Execute() handle exceptions via TaskCompletionSource
public async Task<OperationResult> CreateAsync(IPptBatch batch, string name)
{
    return await batch.Execute((ctx, ct) => {
        var item = ctx.Create(name);
        return ValueTask.FromResult(new OperationResult { Success = true });
    });
    // Exception flows to batch.Execute() → caught via TaskCompletionSource
    // → Returns OperationResult { Success = false, ErrorMessage }
}

// ✅ CORRECT: Finally blocks are the right place for COM resource cleanup
public async Task<OperationResult> ComplexAsync(IPptBatch batch, string name)
{
    dynamic? temp = null;
    try
    {
        return await batch.Execute((ctx, ct) => {
            temp = ctx.CreateTemp(name);
            // ... operation ...
            return ValueTask.FromResult(new OperationResult { Success = true });
        });
    }
    finally
    {
        // ✅ Finally for resource cleanup, NOT catch for error handling
        if (temp != null)
        {
            ComUtilities.Release(ref temp!);
        }
    }
}