Imported from majiayu000/claude-skill-registry (skills/data/aspose-slides/SKILL.md). Install upstream with npx skills add majiayu000/claude-skill-registry --skill aspose-slides. Copyright stays with the author.

Aspose.Slides for .NET - PowerPoint Manipulation Skill

Overview

This skill enables Claude Code to effectively manipulate Microsoft PowerPoint presentations using the Aspose.Slides.NET library. It provides comprehensive guidance for working with presentations programmatically without requiring Microsoft PowerPoint installation.

Core Capabilities

Presentation Structure

Creating presentations: New presentations from scratch or from templates
Loading presentations: PPT, PPTX, ODP, and other formats
Saving presentations: Multiple format support (PPTX, PDF, HTML, images)
Slide management: Add, remove, clone, reorder slides
Master slides and layouts: Work with slide masters and apply layouts

Content Manipulation

Text handling: TextFrames, Paragraphs, Portions with formatting
Shapes: AutoShapes, custom shapes, grouping, positioning
Tables: Create, format, populate table data
Charts: Create and customize various chart types
Images: Add, replace, extract images and SVGs
Media: Embed and configure audio/video

Formatting and Styling

Text formatting: Fonts, colors, alignment, spacing
Shape formatting: Fill, line, effects, 3D properties
Themes and color schemes: Apply and customize themes
Backgrounds: Solid colors, gradients, patterns, images

Advanced Features

Animations: Timeline, effects, triggers
Transitions: Slide transitions and timing
Comments: Add and manage presentation comments
Properties: Document properties (built-in and custom)
SmartArt: Work with SmartArt graphics
VBA macros: Access and manipulate VBA code

Object Model Understanding

Core Hierarchy

Presentation (IPresentation)
├── Slides (ISlideCollection)
│   ├── Slide (ISlide)
│   │   ├── Shapes (IShapeCollection)
│   │   │   ├── AutoShape (IAutoShape)
│   │   │   ├── Table (ITable)
│   │   │   ├── Chart (IChart)
│   │   │   ├── PictureFrame (IPictureFrame)
│   │   │   └── GroupShape (IGroupShape)
│   │   ├── Background (IBackground)
│   │   └── SlideShowTransition
│   └── NotesSlide (INotesSlide)
├── Masters (IMasterSlideCollection)
│   └── MasterSlide (IMasterSlide)
├── Layouts (ILayoutSlideCollection)
│   └── LayoutSlide (ILayoutSlide)
└── DocumentProperties (IDocumentProperties)

Text Hierarchy

TextFrame (ITextFrame)
├── Paragraphs (IParagraphCollection)
│   └── Paragraph (IParagraph)
│       ├── Portions (IPortionCollection)
│       │   └── Portion (IPortion)
│       │       └── PortionFormat (IPortionFormat)
│       └── ParagraphFormat (IParagraphFormat)
└── TextFrameFormat (ITextFrameFormat)

Modern C# Patterns

Resource Management

Always use using statements for proper disposal:

using Aspose.Slides;

// Single presentation
using var presentation = new Presentation("input.pptx");
// Work with presentation
presentation.Save("output.pptx", SaveFormat.Pptx);

// Multiple resources
using var sourcePresentation = new Presentation("source.pptx");
using var targetPresentation = new Presentation();
// Combine presentations

Functional Collection Processing

Leverage LINQ and functional patterns:

// Find shapes by type
var textShapes = slide.Shapes
    .OfType<IAutoShape>()
    .Where(s => s.TextFrame != null)
    .ToList();

// Process all text portions
var allText = slide.Shapes
    .OfType<IAutoShape>()
    .Where(s => s.TextFrame != null)
    .SelectMany(s => s.TextFrame.Paragraphs)
    .SelectMany(p => p.Portions)
    .Select(p => p.Text);

// Update text declaratively
slide.Shapes
    .OfType<IAutoShape>()
    .Where(s => s.Name == "Title")
    .Select(s => s.TextFrame)
    .Where(tf => tf != null)
    .ToList()
    .ForEach(tf => tf.Text = "New Title");

Pattern Matching and Switch Expressions

Use modern C# features for shape handling:

foreach (var shape in slide.Shapes)
{
    var result = shape switch
    {
        IAutoShape autoShape when autoShape.TextFrame != null 
            => ProcessTextShape(autoShape),
        ITable table 
            => ProcessTable(table),
        IChart chart 
            => ProcessChart(chart),
        IPictureFrame picture 
            => ProcessImage(picture),
        _ => null
    };
}

Immutability and Builder Patterns

Create helper methods for declarative configuration:

IAutoShape AddConfiguredShape(
    ISlide slide,
    ShapeType shapeType,
    float x, float y, float width, float height,
    Action<IAutoShape> configure)
{
    var shape = slide.Shapes.AddAutoShape(shapeType, x, y, width, height);
    configure(shape);
    return shape;
}

// Usage
var titleShape = AddConfiguredShape(
    slide, 
    ShapeType.Rectangle, 
    50, 50, 600, 100,
    shape =>
    {
        shape.TextFrame.Text = "Title";
        shape.FillFormat.FillType = FillType.Solid;
        shape.FillFormat.SolidFillColor.Color = Color.Blue;
    });

Common Task Patterns

Creating a Presentation from Template

using var presentation = new Presentation("template.pptx");

// Populate placeholder text
foreach (var slide in presentation.Slides)
{
    foreach (var shape in slide.Shapes.OfType<IAutoShape>())
    {
        if (shape.Placeholder != null)
        {
            var placeholderType = shape.Placeholder.Type;
            shape.TextFrame.Text = placeholderType switch
            {
                PlaceholderType.Title => "Dynamic Title",
                PlaceholderType.Body => "Dynamic Content",
                _ => shape.TextFrame.Text
            };
        }
    }
}

presentation.Save("output.pptx", SaveFormat.Pptx);

Adding a Table with Data

// Define table dimensions
var columnWidths = new[] { 100.0, 150.0, 200.0 };
var rowHeights = new[] { 50.0, 40.0, 40.0, 40.0 };

var table = slide.Shapes.AddTable(
    x: 50, 
    y: 50, 
    columnWidths, 
    rowHeights);

// Populate headers
var headers = new[] { "Name", "Value", "Description" };
for (int col = 0; col < headers.Length; col++)
{
    table[col, 0].TextFrame.Text = headers[col];
    table[col, 0].CellFormat.FillFormat.FillType = FillType.Solid;
    table[col, 0].CellFormat.FillFormat.SolidFillColor.Color = 
        Color.FromArgb(68, 114, 196);
    table[col, 0].TextFrame.Paragraphs[0].Portions[0].PortionFormat
        .FillFormat.SolidFillColor.Color = Color.White;
}

// Populate data rows
var data = new[]
{
    new[] { "Item 1", "100", "First item" },
    new[] { "Item 2", "200", "Second item" },
    new[] { "Item 3", "300", "Third item" }
};

for (int row = 0; row < data.Length; row++)
{
    for (int col = 0; col < data[row].Length; col++)
    {
        table[col, row + 1].TextFrame.Text = data[row][col];
    }
}

Creating a Chart

// Add chart to slide
var chart = slide.Shapes.AddChart(
    ChartType.ClusteredColumn,
    x: 50,
    y: 50,
    width: 500,
    height: 400);

// Clear default data
chart.ChartData.Series.Clear();
chart.ChartData.Categories.Clear();

// Set categories
var categories = new[] { "Q1", "Q2", "Q3", "Q4" };
foreach (var category in categories)
{
    chart.ChartData.Categories.Add(
        chart.ChartData.ChartDataWorkbook.GetCell(0, 0, 0, category));
}

// Add data series
var series1 = chart.ChartData.Series.Add(
    chart.ChartData.ChartDataWorkbook.GetCell(0, 0, 1, "Sales"),
    chart.Type);

var salesData = new[] { 120, 150, 180, 160 };
for (int i = 0; i < salesData.Length; i++)
{
    series1.DataPoints.AddDataPointForBarSeries(
        chart.ChartData.ChartDataWorkbook.GetCell(0, i + 1, 1, salesData[i]));
}

// Style the chart
series1.Format.Fill.FillType = FillType.Solid;
series1.Format.Fill.SolidFillColor.Color = Color.FromArgb(68, 114, 196);
chart.HasTitle = true;
chart.ChartTitle.AddTextFrameForOverriding("Quarterly Sales");

Text Replacement with Formatting Preservation

void ReplaceTextPreservingFormat(
    IPresentation presentation, 
    string searchText, 
    string replacementText)
{
    foreach (var slide in presentation.Slides)
    {
        foreach (var shape in slide.Shapes.OfType<IAutoShape>())
        {
            if (shape.TextFrame == null) continue;

            foreach (var paragraph in shape.TextFrame.Paragraphs)
            {
                foreach (var portion in paragraph.Portions)
                {
                    if (portion.Text.Contains(searchText))
                    {
                        portion.Text = portion.Text.Replace(
                            searchText, 
                            replacementText);
                    }
                }
            }
        }
    }
}

Working with Images

// Add image from file
using var image = Image.FromFile("logo.png");
var ppImage = presentation.Images.AddImage(image);

var pictureFrame = slide.Shapes.AddPictureFrame(
    ShapeType.Rectangle,
    x: 100,
    y: 100,
    width: 200,
    height: 150,
    ppImage);

// Extract all images from presentation
var imageIndex = 0;
foreach (var slide in presentation.Slides)
{
    foreach (var shape in slide.Shapes.OfType<IPictureFrame>())
    {
        var image = shape.PictureFormat.Picture.Image.SystemImage;
        image.Save($"extracted_image_{imageIndex++}.png");
    }
}

JSON Data Population Pattern

For data-driven presentations, use a declarative approach:

public class SlideDataModel
{
    public string Title { get; set; }
    public List<BulletPoint> BulletPoints { get; set; }
    public TableData TableData { get; set; }
    public ChartData ChartData { get; set; }
}

void PopulateSlideFromJson(ISlide slide, SlideDataModel data)
{
    // Update title
    var titleShape = slide.Shapes
        .OfType<IAutoShape>()
        .FirstOrDefault(s => s.Placeholder?.Type == PlaceholderType.Title);
    
    if (titleShape != null && data.Title != null)
    {
        titleShape.TextFrame.Text = data.Title;
    }

    // Update bullet points
    var bodyShape = slide.Shapes
        .OfType<IAutoShape>()
        .FirstOrDefault(s => s.Placeholder?.Type == PlaceholderType.Body);
    
    if (bodyShape != null && data.BulletPoints != null)
    {
        bodyShape.TextFrame.Paragraphs.Clear();
        
        foreach (var bullet in data.BulletPoints)
        {
            var paragraph = new Paragraph();
            paragraph.Text = bullet.Text;
            paragraph.ParagraphFormat.Bullet.Type = BulletType.Symbol;
            bodyShape.TextFrame.Paragraphs.Add(paragraph);
        }
    }

    // Populate table if present
    if (data.TableData != null)
    {
        PopulateTable(slide, data.TableData);
    }

    // Populate chart if present
    if (data.ChartData != null)
    {
        PopulateChart(slide, data.ChartData);
    }
}

Performance Considerations

Memory Management for Large Presentations

// Use BlobManagementOptions for large presentations
var blobOptions = new BlobManagementOptions
{
    PresentationLockingBehavior = PresentationLockingBehavior.KeepLocked,
    IsTemporaryFilesAllowed = true,
    TempFilesRootPath = Path.GetTempPath()
};

var loadOptions = new LoadOptions { BlobManagementOptions = blobOptions };
using var presentation = new Presentation("large.pptx", loadOptions);

Efficient Batch Processing

async Task ProcessPresentationsAsync(IEnumerable<string> files)
{
    var processingTasks = files.Select(async file =>
    {
        using var presentation = new Presentation(file);
        
        // Process presentation
        await Task.Run(() => ProcessSlides(presentation));
        
        var outputPath = Path.ChangeExtension(file, ".processed.pptx");
        presentation.Save(outputPath, SaveFormat.Pptx);
    });

    await Task.WhenAll(processingTasks);
}

Error Handling Patterns

Robust Presentation Processing

Result<Presentation> LoadPresentationSafely(string path)
{
    try
    {
        var presentation = new Presentation(path);
        return Result<Presentation>.Success(presentation);
    }
    catch (Exception ex) when (ex is InvalidOperationException or IOException)
    {
        return Result<Presentation>.Failure($"Failed to load presentation: {ex.Message}");
    }
}

// Usage with pattern matching
var result = LoadPresentationSafely("presentation.pptx");

result switch
{
    { IsSuccess: true } => ProcessPresentation(result.Value),
    { IsSuccess: false } => LogError(result.Error)
};

Export and Conversion

PDF Export with Options

var pdfOptions = new PdfOptions
{
    Compliance = PdfCompliance.Pdf15,
    JpegQuality = 90,
    TextCompression = PdfTextCompression.Flate,
    EmbedFullFonts = true,
    DrawSlidesFrame = false
};

// Include notes in PDF
pdfOptions.NotesCommentsLayouting.NotesPosition = NotesPositions.BottomFull;

presentation.Save("output.pdf", SaveFormat.Pdf, pdfOptions);

HTML Export

var htmlOptions = new HtmlOptions
{
    EmbedImages = true,
    HtmlFormatter = HtmlFormatter.CreateDocumentFormatter(string.Empty, false)
};

presentation.Save("output.html", SaveFormat.Html, htmlOptions);

Image Export for Each Slide

foreach (var slide in presentation.Slides)
{
    using var bitmap = slide.GetThumbnail(2.0f, 2.0f); // 2x scale
    bitmap.Save(
        $"slide_{slide.SlideNumber}.png", 
        System.Drawing.Imaging.ImageFormat.Png);
}

Best Practices

1. Fitness for Purpose

Use templates when possible to maintain consistent design
Prefer placeholder manipulation over direct shape creation
Consider export format requirements when designing slides
Balance visual quality with file size constraints

2. Declarative Configuration

Extract repeated configuration into helper methods
Use object initializers and collection initializers
Leverage LINQ for collection transformations
Prefer expression-bodied members for simple operations

3. Type Safety

Use strongly-typed enumerations (ShapeType, PlaceholderType, etc.)
Avoid magic numbers and strings
Create domain-specific value objects for measurements
Use records for immutable data transfer objects

4. Maintainability

Separate data from presentation logic
Create reusable components for common slide patterns
Use consistent naming conventions for shapes
Document complex shape hierarchies

5. Testing

Create minimal test presentations for validation
Use presentation properties to verify changes
Extract testable pure functions
Consider round-trip testing (save/load/verify)

Troubleshooting Common Issues

Issue: Shape positioning inconsistent

Solution: Use slide dimensions as reference

var slideWidth = presentation.SlideSize.Size.Width;
var slideHeight = presentation.SlideSize.Size.Height;

// Center shape
var shape = slide.Shapes.AddAutoShape(
    ShapeType.Rectangle,
    x: (slideWidth - shapeWidth) / 2,
    y: (slideHeight - shapeHeight) / 2,
    width: shapeWidth,
    height: shapeHeight);

Issue: Text overflow in shapes

Solution: Enable auto-fit or adjust shape size

var textFrame = shape.TextFrame;
textFrame.TextFrameFormat.AutofitType = TextAutofitType.Shape;
// or
textFrame.TextFrameFormat.AutofitType = TextAutofitType.Normal;

Issue: Font not embedded

Solution: Embed fonts explicitly

var fontData = File.ReadAllBytes("customfont.ttf");
presentation.FontsManager.AddEmbeddedFont(fontData, EmbedFontCharacters.All);

Issue: Chart data not updating

Solution: Refresh chart data workbook

chart.ChartData.ChartDataWorkbook.Clear(0);
// Re-populate data

Resource Discovery Strategy

When implementing Aspose.Slides functionality:

Check the namespace hierarchy - Aspose.Slides types are organized logically by domain
Explore interface contracts - Most functionality is exposed through interfaces (IPresentation, ISlide, etc.)
Review enumerations - Aspose uses comprehensive enums for options and types
Consult XML documentation - IntelliSense provides detailed API documentation
Reference GitHub examples - Real-world usage patterns for specific scenarios
Leverage type inference - Let the compiler guide you through valid operations

Example-Driven Development

Start with the desired outcome and work backward:

// Goal: Create a data-driven presentation from JSON

// 1. Define the data structure
var slideData = JsonSerializer.Deserialize<PresentationData>(jsonContent);

// 2. Load or create presentation
using var presentation = LoadTemplate("template.pptx") 
    ?? CreateNewPresentation();

// 3. Apply data to slides
foreach (var (slide, data) in presentation.Slides.Zip(slideData.Slides))
{
    ApplyDataToSlide(slide, data);
}

// 4. Save with appropriate options
SavePresentation(presentation, "output.pptx", slideData.ExportOptions);

Summary

This skill enables Claude Code to manipulate PowerPoint presentations using modern C# patterns with Aspose.Slides. Focus on:

Declarative, functional approaches to slide manipulation
Proper resource management with using statements
Type-safe operations using the comprehensive object model
Data-driven presentation generation
Efficient processing of large presentations

When tackling a new task, understand the object hierarchy, leverage LINQ for collection operations, and prefer composition over complex imperative code.

About