Introduction
Word documents place images, text boxes, and other free-floating objects in a drawing layer that sits apart from the regular flow of paragraphs and tables. Aspose.Words FOSS for .NET exposes this drawing layer through the Shape and ShapeBase classes, giving programmatic access to the same AutoShape, picture, text box, and OLE object model that Word itself uses internally. This guide shows how the library represents and manipulates these drawing objects — positioning, fill and outline formatting, embedded pictures, and text laid out inside a shape — across DOCX, DOCM, DOTX, and DOTM documents.
This is useful for code that builds report or letterhead templates with a positioned logo or graphic, generates documents with floating text boxes and callouts, or inspects shapes already present in an uploaded document — extracting an embedded picture’s bytes, reading a signature line’s signer name, or repositioning an existing image.
Aspose.Words FOSS for .NET is released under the MIT license and targets .NET Standard 2.0, so it runs on .NET Framework 4.6.2+ and .NET 6, 8, and 10 with no native dependencies. A NuGet package has not been published yet — build the library from source (see Quick Start below). It is the same Aspose.Words document engine used commercially, not a rewrite or a wrapper, so the Shape and drawing-layer classes described here are the production API.
Key Features
The Shape and ShapeBase Object Model
Every AutoShape, text box, embedded picture, OLE object, or ActiveX control anchored in a Word document is represented by the Shape class — sealed, and built on the abstract ShapeBase base class. Both share the same positioning and formatting surface: Shape.Left, Shape.Top, Shape.Width, Shape.Height, Shape.Rotation, and Shape.ZOrder for geometry, plus Shape.IsGroup, Shape.IsImage, Shape.IsWordArt, and Shape.IsInline flags describing what kind of object a given instance holds. The ShapeType enum enumerates the concrete shape kinds Word recognizes — Rectangle, Ellipse, Line, Arrow, a family of callout and connector types, TextBox, Image, and OleObject among more than eighty values — so code walking a document’s shapes can branch on Shape.ShapeType to decide how to handle each one. Multiple shapes can be combined into a single GroupShape, itself a ShapeBase subclass, which keeps a set of shapes positioned and resized together; DocumentBuilder.InsertGroupShape(shapes) builds one from an existing array of shapes.
Text Boxes and WordArt
Any Shape can carry its own text through the TextBox class, exposed as Shape.TextBox. TextBox properties control how that text sits inside the shape: TextBox.InternalMarginLeft, TextBox.InternalMarginRight, TextBox.InternalMarginTop, and TextBox.InternalMarginBottom for padding, TextBox.FitShapeToText to let the shape grow with its content, LayoutFlow for text direction, TextBoxWrapMode for how text wraps inside the box, and TextBox.VerticalAnchor — a TextBoxAnchor value such as Top, Middle, BottomCentered, or TopBaseline — for vertical alignment. Linked text boxes, where overflow text continues into a second box, are modeled with TextBox.Next and TextBox.Previous. A related but distinct class, TextPath, defines WordArt-style text that follows a shape’s outline instead of sitting inside it, with properties such as TextPath.Text, TextPath.FontFamily, TextPath.Bold, and TextPath.RotateLetters, plus a TextPathAlignment enum with values such as Stretch, Center, and LetterJustify.
Pictures and Embedded Images
When a shape holds a picture, Shape.HasImage is true and Shape.ImageData returns an ImageData object. ImageData exposes the raw bytes through ImageData.ImageBytes, the detected format through ImageType (values including Jpeg, Png, Bmp, Gif, Emf, Wmf, Pict, Eps, and WebP), pixel dimensions and resolution through ImageSize, and cropping via ImageData.CropTop, ImageData.CropBottom, ImageData.CropLeft, and ImageData.CropRight. Color adjustments — ImageData.Brightness, ImageData.Contrast, ImageData.GrayScale, ImageData.BiLevel, and ImageData.ChromaKey — are properties on the same object, and ImageData.IsLink/ImageData.IsLinkOnly distinguish an embedded picture from one that only references an external file path. DocumentBuilder.InsertImage() has overloads that accept an image, a file path, a byte array, or a stream, including variants that also set explicit width, height, horizontal and vertical position, and WrapType at insertion time.
Fill, Stroke, and Shape Effects
Every Shape and GroupShape carries a Fill object and a Stroke object for its interior and outline. Fill supports six fill kinds through FillType, with values including Solid, Patterned, Gradient, Textured, Background, and Picture, set with methods such as Fill.Solid(color), Fill.OneColorGradient(style, variant, degree), Fill.TwoColorGradient(color1, color2, style, variant), Fill.Patterned(patternType), or Fill.SetImage(fileName). Stroke controls the outline: Stroke.Weight, DashStyle, JoinStyle, EndCap, and Stroke.LineStyle (a ShapeLineStyle value) cover the line itself, while Stroke.StartArrowType and Stroke.EndArrowType, paired with ArrowWidth and ArrowLength enums, configure arrowheads on connector and line shapes. Beyond fill and stroke, Shape exposes four further effect objects — ShadowFormat, ReflectionFormat, GlowFormat, and SoftEdgeFormat — each carrying its own color and transparency properties for the corresponding visual effect.
Positioning and Text Wrapping
Shapes that float relative to the page or paragraph use RelativeHorizontalPosition and RelativeVerticalPosition to anchor themselves — to the margin, page, or column, for example — paired with RelativeHorizontalSize and RelativeVerticalSize for size anchoring, plus HorizontalAlignment and VerticalAlignment for simple left/center/right or top/middle/bottom placement. How surrounding text reacts to a shape is controlled by WrapType, with values including Inline, Square, Tight, TopBottom, and None; for Square and Tight wrapping, WrapSide narrows it further to Left, Right, Both, or Largest. FlipOrientation mirrors a shape horizontally or vertically without changing its coordinates, and the Shape.AllowOverlap/Shape.BehindText flags control how a shape interacts with other floating content and the text layer beneath it.
Signature Lines and Horizontal Rules
Two more specialized shape kinds live in the same drawing model. SignatureLine, configured at insertion time through SignatureLineOptions (properties include SignatureLineOptions.Signer, SignatureLineOptions.SignerTitle, SignatureLineOptions.Email, SignatureLineOptions.Instructions, SignatureLineOptions.ShowDate, and SignatureLineOptions.AllowComments), renders the visual signature block seen in printable documents and exposes SignatureLine.IsSigned and SignatureLine.IsValid once a signature has been applied to it — this is distinct from the cryptographic digital-signature verification covered elsewhere, which works with signed document parts rather than the shape itself. HorizontalRuleFormat covers the plain divider line inserted with DocumentBuilder.InsertHorizontalRule(), with HorizontalRuleFormat.WidthPercent, HorizontalRuleFormat.Height, HorizontalRuleFormat.NoShade, HorizontalRuleFormat.Color, and HorizontalRuleFormat.Alignment properties (the last a HorizontalRuleAlignment value).
Quick Start
A NuGet package has not been published yet; build the library from source:
git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release
Add a project reference to Aspose.Words.csproj from your application. From there, working with the drawing layer follows the pattern used throughout this post: load or create a Document, walk its shapes with Document.GetChildNodes(NodeType.Shape, true) or insert a new one with a DocumentBuilder method such as DocumentBuilder.InsertImage(), DocumentBuilder.InsertGroupShape(), or DocumentBuilder.InsertHorizontalRule(), then read or set properties on the returned Shape — Shape.ImageData, Shape.TextBox, Shape.Fill, Shape.Stroke, Shape.WrapType, and the rest — before calling Document.Save().
Supported Formats
| Format | Extension | Read | Write |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (all variants) | (various) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
This edition intentionally excludes page layout and rendering — no PDF, XPS, or image export, and no printing — so a shape’s Shape.Bounds and layout-dependent geometry reflect the values stored in the document rather than a computed page layout. The additional format converters (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3, and WordML) are not read or written; these are the same subsystems removed from the commercial codebase to keep this edition free.
Open Source & Licensing
Aspose.Words FOSS for .NET is released under the MIT license, free for both commercial and personal use with no royalties or redistribution restrictions. The full source is available on GitHub in the Aspose.Words FOSS for .NET repository.