officefileapi-402311-word-processing-document-api-word-processing-document-ole-objects.md
OLE (Object Linking and Embedding) technology allows you to insert data (spreadsheets, images, presentations, charts, equations, etc.) from external applications into your document. Use the Word Processing Document API to load, add, extract, or remove OLE objects. You can print documents with OLE objects and export them to PDF.
Important
The Word Processing Document API does not support OLE objects in OpenDocument Text (.odt) and encrypted DOC files. OLE objects are also not exported to an HTML file.
OLE objects are stored in the SubDocument.Shapes collection. Use the ShapeCollection.Item property to return an OLE object from the collection. The Shape.Type property helps you distinguish between different drawing object types in the document.
The DrawingObject.OleFormat property returns the OLE object’s characteristics.
| Property | Description |
|---|---|
| OleFormat.InsertType | Indicates whether the OLE object is embedded in the document or linked to an external file. |
| OleFormat.ObjectRepresentation | Indicates how the OLE object is displayed in the document (as an image or an icon). |
| OleFormat.ProgId | Returns the content type associated with the OLE object. |
| OleFormat.SourceFileName | Returns a path to the source file associated with the linked OLE object. |
| OleFormat.AutoUpdate | Specifies whether to automatically update the OLE object with data from the linked file. |
| OleFormat.IsLocked | Specifies whether the linked OLE object can be updated. |
| OleFormat.OlePackage | Returns properties for the OLE object of the Package type. |
The following example retrieves all linked objects from the document:
using System.Linq;
// ...
Document document = wordProcessor.Document;
List<DrawingObject> linkedObjects = document.Shapes.Flatten()
.Where(x => x.Type == ShapeType.OleObject &&
x.OleFormat.InsertType == OleInsertType.Linked)
.ToList();
Imports System.Linq
' ...
Dim document As Document = wordProcessor.Document
Dim linkedObjects As List(Of DrawingObject) = document.Shapes.Flatten() _
.Where(Function(x) x.Type = ShapeType.OleObject AndAlso _
x.OleFormat.InsertType = OleInsertType.Linked) _
.ToList()
Use the ShapeCollection.InsertOleObject method overload with the fileName parameter to create an OLE object that stores a link to a specified file. You can use constant fields of the OleObjectType class to specify the file type. The OLE object is displayed in the document as an image.
Document document = wordProcessor.Document;
// Insert an OLE object. Link it to an Excel worksheet.
Shape oleObject = document.Shapes.InsertOleObject(document.CreatePosition(1780), @"D:\ExcelWorkbook.xlsx",
OleObjectType.ExcelWorksheet, DocumentImageSource.FromFile(@"Images\Spreadsheet.png"));
// Specify the object position on the page.
oleObject.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Column;
oleObject.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Paragraph;
oleObject.Offset = new PointF(0, 0);
// Specify how text wraps around the object.
oleObject.TextWrapping = TextWrappingType.TopAndBottom;
Dim document As Document = wordProcessor.Document
' Insert an OLE object. Link it to an Excel worksheet.
Dim oleObject As Shape = document.Shapes.InsertOleObject(document.CreatePosition(1780), "D:\ExcelWorkbook.xlsx", _
OleObjectType.ExcelWorksheet, DocumentImageSource.FromFile("Images\Spreadsheet.png"))
' Specify the object position on the page.
oleObject.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Column
oleObject.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Paragraph
oleObject.Offset = New PointF(0, 0)
' Specify how text wraps around the object.
oleObject.TextWrapping = TextWrappingType.TopAndBottom
Open the document in Microsoft® Word® and double-click the image to open the file associated with the OLE object.
Use the ShapeCollection.InsertOleObject method overload with the stream parameter to embed data from an external file in the document. You can use constant fields of the OleObjectType class to specify the content type. The OLE object is displayed in the document as an image.
Document document = wordProcessor.Document;
// Embed data from an Excel worksheet in the document.
using (Stream excelStream = File.Open(@"D:\ExcelWorkbook.xlsx", FileMode.Open))
{
Shape oleObject = document.Shapes.InsertOleObject(document.CreatePosition(1780), excelStream,
OleObjectType.ExcelWorksheet, DocumentImageSource.FromFile(@"Images\Spreadsheet.png"));
// Specify the object position on the page.
oleObject.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Column;
oleObject.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Paragraph;
oleObject.Offset = new PointF(0, 0);
// Specify how text wraps around the object.
oleObject.TextWrapping = TextWrappingType.TopAndBottom;
}
Dim document As Document = wordProcessor.Document
' Embed data from an Excel worksheet in the document.
Using excelStream As Stream = File.Open("D:\ExcelWorkbook.xlsx", FileMode.Open)
Dim oleObject As Shape = document.Shapes.InsertOleObject(document.CreatePosition(1780), excelStream, _
OleObjectType.ExcelWorksheet, DocumentImageSource.FromFile("Images\Spreadsheet.png"))
' Specify the object position on the page.
oleObject.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Column
oleObject.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Paragraph
oleObject.Offset = New PointF(0, 0)
' Specify how text wraps around the object.
oleObject.TextWrapping = TextWrappingType.TopAndBottom
End Using
Open the document in Microsoft® Word® and double-click the OLE object to modify the embedded data.
Use the ShapeCollection.InsertOleObjectAsIcon method overloads to insert OLE objects as icons.
Document document = wordProcessor.Document;
// Insert an OLE object. Link it to an Excel worksheet.
// The OLE object is displayed in the document as an icon.
Shape oleObject = document.Shapes.InsertOleObjectAsIcon(document.CreatePosition(1780), @"D:\ExcelWorkbook.xlsx",
OleObjectType.ExcelWorksheet, DocumentImageSource.FromFile(@"Images\Excel.ico"));
// Specify the object position on the page.
oleObject.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Column;
oleObject.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Paragraph;
oleObject.Offset = new PointF(0, 0);
// Specify how text wraps around the object.
oleObject.TextWrapping = TextWrappingType.TopAndBottom;
Dim document As Document = wordProcessor.Document
' Insert an OLE object. Link it to an Excel worksheet.
' The OLE object is displayed in the document as an icon.
Dim oleObject As Shape = document.Shapes.InsertOleObjectAsIcon(document.CreatePosition(1780), "D:\ExcelWorkbook.xlsx", _
OleObjectType.ExcelWorksheet, DocumentImageSource.FromFile("Images\Excel.ico"))
' Specify the object position on the page.
oleObject.RelativeHorizontalPosition = ShapeRelativeHorizontalPosition.Column
oleObject.RelativeVerticalPosition = ShapeRelativeVerticalPosition.Paragraph
oleObject.Offset = New PointF(0, 0)
' Specify how text wraps around the object.
oleObject.TextWrapping = TextWrappingType.TopAndBottom
Open the document in Microsoft® Word® and double-click the icon to open the file associated with the OLE object.
Call the ShapeCollection.InsertGroup method to create a shape group. The Shape.GroupItems property returns a collection of group elements. Use the collection’s AddOleObject and AddOleObjectAsIcon methods to add OLE objects to the group.
The following example groups two OLE objects:
Document document = wordProcessor.Document;
// Set measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch;
// Insert a shape group.
Shape group = document.Shapes.InsertGroup(document.Range.Start);
// Specify the group position relative to the left and top edges of the page.
group.Offset = new PointF(1f, 6f);
// Access the collection of group items.
var groupItems = group.GroupItems;
// Add the first OLE object to the group.
groupItems.AddOleObjectAsIcon(@"D:\ExcelWorkbook.xlsx", OleObjectType.ExcelWorksheet,
DocumentImageSource.FromFile(@"Images\Excel.ico"), new PointF(0f, 0f));
// Add the second OLE object to the group.
groupItems.AddOleObjectAsIcon(@"D:\PowerPointPresentation.pptx", OleObjectType.PowerPointPresentation,
DocumentImageSource.FromFile(@"Images\PowerPoint.ico"), new PointF(1.5f, 0f));
Dim document As Document = wordProcessor.Document
' Set measurement unit to inches.
document.Unit = DevExpress.Office.DocumentUnit.Inch
' Insert a shape group.
Dim group As Shape = document.Shapes.InsertGroup(document.Range.Start)
' Specify the group position relative to the left and top edges of the page.
group.Offset = New PointF(1F, 6F)
' Access the collection of group items.
Dim groupItems As GroupShapeCollection = group.GroupItems
' Add the first OLE object to the group.
groupItems.AddOleObjectAsIcon("D:\ExcelWorkbook.xlsx", OleObjectType.ExcelWorksheet, _
DocumentImageSource.FromFile("Images\Excel.ico"), New PointF(0F, 0F))
' Add the second OLE object to the group.
groupItems.AddOleObjectAsIcon("D:\PowerPointPresentation.pptx", OleObjectType.PowerPointPresentation, _
DocumentImageSource.FromFile("Images\PowerPoint.ico"), New PointF(1.5F, 0F))
Use the OleFormat.ChangeRepresentation method to change how an existing OLE object is displayed in the document.
Document document = wordProcessor.Document;
// Insert an OLE object. Link it to an Excel worksheet.
// The OLE object is displayed in the document as an image.
Shape oleObject = document.Shapes.InsertOleObject(document.CreatePosition(1780), @"D:\ExcelWorkbook.xlsx",
OleObjectType.ExcelWorksheet, DocumentImageSource.FromFile(@"Images\Spreadsheet.png"));
// Display the OLE object as an icon.
oleObject.OleFormat.ChangeRepresentation(OleObjectRepresentationType.Icon,
DocumentImageSource.FromFile(@"Images\Excel.ico"));
Dim document As Document = wordProcessor.Document
' Insert an OLE object. Link it to an Excel worksheet.
' The OLE object is displayed in the document as an image.
Dim oleObject As Shape = document.Shapes.InsertOleObject(document.CreatePosition(1780), "D:\ExcelWorkbook.xlsx", _
OleObjectType.ExcelWorksheet, DocumentImageSource.FromFile("Images\Spreadsheet.png"))
' Display the OLE object as an icon.
oleObject.OleFormat.ChangeRepresentation(OleObjectRepresentationType.Icon, DocumentImageSource.FromFile("Images\Excel.ico"))
Use the OleFormat.GetRawData method to retrieve an embedded OLE object’s data.
The following example loads spreadsheet data from a Word document into the Spreadsheet Document API component. You can modify and save this data to a file.
Important
You need a license to the DevExpress Office File API or DevExpress Universal Subscription to use this example in production code. Refer to the following page for pricing information: DevExpress Subscriptions.
using System.Linq;
using DevExpress.XtraRichEdit.API.Native;
// Add references to DevExpress.Docs.dll
// and DevExpress.Spreadsheet.Core.dll.
using DevExpress.Spreadsheet;
// ...
Document document = wordProcessor.Document;
// Obtain an OLE object that stores spreadsheet data.
DevExpress.XtraRichEdit.API.Native.Shape embeddedObject = document.Shapes.FirstOrDefault(
x => x.Type == DevExpress.XtraRichEdit.API.Native.ShapeType.OleObject &&
x.OleFormat.InsertType == OleInsertType.Embedded &&
x.OleFormat.ProgId == OleObjectType.ExcelWorksheet);
if (embeddedObject != null)
{
// Retrieve data from the OLE object.
byte[] spreadsheetData = embeddedObject.OleFormat.GetRawData();
// Create a Workbook instance.
using (Workbook workbook = new Workbook()) {
// Load data into the workbook.
workbook.LoadDocument(spreadsheetData);
// Modify data.
// ...
// Save the document.
workbook.SaveDocument("ExcelDocument.xlsx", DevExpress.Spreadsheet.DocumentFormat.Xlsx);
}
}
Imports System.Linq
Imports DevExpress.XtraRichEdit.API.Native
' Add references to DevExpress.Docs.dll
' and DevExpress.Spreadsheet.Core.dll.
Imports DevExpress.Spreadsheet
' ...
Dim document As Document = wordProcessor.Document
' Obtain an OLE object that stores spreadsheet data.
Dim embeddedObject As DevExpress.XtraRichEdit.API.Native.Shape =
document.Shapes.FirstOrDefault(Function(x) x.Type =
DevExpress.XtraRichEdit.API.Native.ShapeType.OleObject _
AndAlso x.OleFormat.InsertType = OleInsertType.Embedded _
AndAlso x.OleFormat.ProgId = OleObjectType.ExcelWorksheet)
If embeddedObject IsNot Nothing Then
' Retrieve data from the OLE object.
Dim spreadsheetData() As Byte = embeddedObject.OleFormat.GetRawData()
' Create a Workbook instance.
Using workbook As New Workbook()
' Load data into the workbook.
workbook.LoadDocument(spreadsheetData)
' Modify data.
' ...
' Save the document.
workbook.SaveDocument("ExcelDocument.xlsx", DevExpress.Spreadsheet.DocumentFormat.Xlsx)
End Using
End If
Use the OleFormat.SaveAs method to save an embedded OLE object’s data to a file.
using System.Linq;
using DevExpress.XtraRichEdit.API.Native;
// ...
Document document = wordProcessor.Document;
// Obtain an OLE object that stores spreadsheet data.
DevExpress.XtraRichEdit.API.Native.Shape embeddedObject = document.Shapes.FirstOrDefault(
x => x.Type == DevExpress.XtraRichEdit.API.Native.ShapeType.OleObject &&
x.OleFormat.InsertType == OleInsertType.Embedded &&
x.OleFormat.ProgId == OleObjectType.ExcelWorksheet);
if (embeddedObject != null)
{
// Save the OLE object's data as an XLSX document.
embeddedObject.OleFormat.SaveAs("ExcelDocument.xlsx");
}
Imports System.Linq
Imports DevExpress.XtraRichEdit.API.Native
' ...
Dim document As Document = wordProcessor.Document
' Obtain an OLE object that stores spreadsheet data.
Dim embeddedObject As DevExpress.XtraRichEdit.API.Native.Shape =
document.Shapes.FirstOrDefault(Function(x) x.Type =
DevExpress.XtraRichEdit.API.Native.ShapeType.OleObject _
AndAlso x.OleFormat.InsertType = OleInsertType.Embedded _
AndAlso x.OleFormat.ProgId = OleObjectType.ExcelWorksheet)
If embeddedObject IsNot Nothing Then
' Save the OLE object's data as an XLSX document.
embeddedObject.OleFormat.SaveAs("ExcelDocument.xlsx")
End If
Use one of the following methods to remove an OLE object from the document:
ShapeCollection.Remove - removes a specific object from the collection;
ShapeCollection.RemoveAt - removes an object with the specified index from the collection;
ShapeCollection.Clear - clears the shape collection.
The following example removes all OLE objects from the collection:
Document document = wordProcessor.Document;
ShapeCollection shapes = document.Shapes;
for (int i = shapes.Count - 1; i >= 0; i--)
{
if (shapes[i].Type == ShapeType.OleObject)
shapes.Remove(shapes[i]);
}
Dim document As Document = wordProcessor.Document
Dim shapes As ShapeCollection = document.Shapes
For i As Integer = shapes.Count - 1 To 0 Step -1
If shapes(i).Type = ShapeType.OleObject Then
shapes.Remove(shapes(i))
End If
Next i
See Also
Shapes, Pictures, and Other Graphic Objects in Word Documents