How to Work with Styles in .NET

This guide shows how to look up, apply, and create paragraph, character, table, and list styles in Aspose.Words FOSS for .NET, using the Style, StyleCollection, and TableStyle classes. It covers reading a document’s style collection, looking up styles reliably across languages, applying styles to paragraphs and runs, creating and copying styles, and configuring per-region conditional formatting on table styles.

Step-by-Step Guide

Step 1: Install the Package

Aspose.Words FOSS for .NET does not yet publish a NuGet package – build the library from source instead. Clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, then build Aspose.Words.sln in Release configuration with the .NET SDK and reference the resulting Aspose.Words assembly from your project. The library targets .NET Standard 2.0, so it runs on .NET Framework 4.6.2+ and .NET 6/8/10.

Step 2: Import Required Classes

Add a using Aspose.Words; directive – Style, StyleCollection, TableStyle, StyleType, StyleIdentifier, ConditionalStyle, ConditionalStyleCollection, and ConditionalStyleType all live in the Aspose.Words namespace alongside Document.

Step 3: Read a Document’s Style Collection

Document.Styles returns a StyleCollection – every built-in and user-defined Style attached to the document. StyleCollection.Count reports how many styles it holds, and DefaultFont / DefaultParagraphFormat describe the document-wide default formatting new content inherits before any explicit style is applied.

Step 4: Look Up a Style Reliably

Retrieve a style by its display name using the StyleCollection indexer, styles[name]. For built-in styles, prefer the same indexer with a StyleIdentifier enum value instead – styles[sti] – names are localized, but StyleIdentifier values are not, so lookup by identifier works the same way regardless of the document’s language. Check Style.Aliases for alternate names Word recognizes for the same style if the indexer doesn’t find what you expect, and check Style.BuiltIn before removing or renaming a style programmatically, since built-in styles are often referenced by name elsewhere in the document.

Step 5: Apply a Style to Paragraphs or Runs

Formatting objects that carry a style expose both a Style property (the Style object itself) and a StyleName property (a shortcut that resolves, or creates, a style by name). Set ParagraphFormat.Style or ParagraphFormat.StyleName to apply a paragraph style, and Font.Style or Font.StyleName to apply a character style to a run’s formatting. Assigning StyleName with a name that doesn’t already exist in the collection creates that style – confirm the style exists with the StyleCollection indexer first, or assign the Style object directly, if that isn’t the intended behavior.

Step 6: Build Style Hierarchies

Read BaseStyleName to find the style a given style inherits unset formatting from, LinkedStyleName for a paired paragraph/character style (as Word defines for built-in styles such as a heading and its linked character style), and NextParagraphStyleName for the style Word assigns to a new paragraph typed after one using this style. Set BaseStyleName when defining a set of related styles – such as a family of heading styles that should all inherit font choices from one base style – instead of repeating the same formatting on every style.

Step 7: Create or Copy a Style

Call StyleCollection.Add(type, name) with a StyleType (Paragraph, Character, Table, or List) and a name to create a new, empty style, then set its Font and ParagraphFormat properties as needed. To duplicate an existing style – including one from a different Document’s StyleCollection – call StyleCollection.AddCopy(style) rather than manually reading and reapplying every formatting property. Call Style.Remove() to delete a style from its collection.

Step 8: Configure Table Styles and Conditional Formatting

TableStyle extends Style with table-layout properties – Alignment, CellSpacing, LeftIndent, Shading, VerticalAlignment, and the four padding properties (LeftPadding, RightPadding, TopPadding, BottomPadding) – plus RowStripe and ColumnStripe, which control how many rows or columns a banding pattern repeats over. For per-region formatting, configure TableStyle.ConditionalStyles – a ConditionalStyleCollection holding one ConditionalStyle per region: FirstRow, LastRow, FirstColumn, LastColumn, OddRowBanding, EvenRowBanding, OddColumnBanding, EvenColumnBanding, and the four corner cells (TopLeftCell, TopRightCell, BottomLeftCell, BottomRightCell). Each ConditionalStyle carries its own Font, ParagraphFormat, Shading, Borders, and cell padding, with Type reporting which ConditionalStyleType region it represents; set formatting on these regions rather than on individual table rows to get banded, header-row, or corner-cell formatting that survives table edits.

Step 9: Reset or Remove Formatting

Call ConditionalStyle.ClearFormatting() to reset one conditional region, or ConditionalStyleCollection.ClearFormatting() to reset every region on a TableStyle at once. StyleCollection.ClearQuickStyleGallery() removes every style from the Word UI’s quick-style gallery without deleting the styles themselves – useful for trimming the gallery down without touching document content.

Common Issues and Fixes

StyleCollection indexer returns null for a name lookup The style name doesn’t exist in this document, or a built-in style hasn’t been used yet, so Word hasn’t materialized it. Check Style.Aliases for alternate names, or use the StyleCollection indexer with a StyleIdentifier for built-in styles instead.

Setting StyleName unexpectedly creates a new style StyleName creates the named style if it doesn’t already exist in the collection. Use the StyleCollection indexer first to confirm the style exists, or assign the Style object directly through the Style property instead of StyleName.

Table banding doesn’t appear after applying a TableStyle The conditional formatting regions – OddRowBanding, EvenRowBanding, and similar – were never configured on TableStyle.ConditionalStyles. Set formatting on the relevant ConditionalStyle entries in ConditionalStyleCollection.

A style change doesn’t affect content that already uses the style Direct (manual) formatting applied on top of the style takes precedence over the style’s own settings. Clear direct formatting on the affected runs or paragraphs, or set Style.AutomaticallyUpdate so the style redefines itself from that manual formatting.

A built-in style lookup fails in a document authored in another language The StyleCollection indexer matches on the display name, which is localized, when called with a name. Use the same indexer with the corresponding StyleIdentifier enum value instead, since that identifier is locale-independent.

Frequently Asked Questions

How do I get the collection of all styles in a document?

Read Document.Styles, which returns a StyleCollection containing every built-in and user-defined Style in that document.

What is the difference between Style and StyleIdentifier?

Style is the actual style object with its formatting; StyleIdentifier is a locale-independent enum value used to look up a specific built-in style regardless of the document’s language, via the StyleCollection indexer.

How do table styles differ from paragraph or character styles?

TableStyle is a subclass of Style that adds table-layout properties (Alignment, CellSpacing, padding) and a ConditionalStyles collection for region-specific formatting such as banded rows, header rows, and corner cells – formatting concepts that don’t apply to paragraph or character styles.

Can I create a brand-new style instead of modifying an existing one?

Yes – call StyleCollection.Add(type, name) with the desired StyleType and a new name to create an empty style, then set its formatting properties (Font, ParagraphFormat, and so on for paragraph or character styles).

How do I duplicate a style, including from another document?

Call StyleCollection.AddCopy(style), passing a Style object – which can come from a different Document’s StyleCollection – to add a copy of it to the target collection.