Skip to content

[admin] merge to live #66

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 28, 2021
Merged

[admin] merge to live #66

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6e1f5c1
Update how-to-add-tables-to-word-processing-documents.md
lindalu-MSFT Jun 28, 2021
1df73e9
Merge pull request #65 from OfficeDev/lindalu-fix-broken-download-url
lindalu-MSFT Jun 28, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 25 additions & 64 deletions docs/how-to-add-tables-to-word-processing-documents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,15 @@ ms.technology: open-xml
ms.author: o365devx
author: o365devx
ms.topic: conceptual
ms.date: 11/01/2017
ms.date: 06/28/2021
localization_priority: Priority
---

# Add tables to word processing documents (Open XML SDK)

This topic shows how to use the classes in the Open XML SDK 2.5 for
Office to programmatically add a table to a word processing document. It
contains an example **AddTable** method to illustrate this task.
This topic shows how to use the classes in the Open XML SDK 2.5 for Office to programmatically add a table to a word processing document. It contains an example **AddTable** method to illustrate this task.

To use the sample code in this topic, you must install the [Open XML SDK 2.5](https://www.microsoft.com/download/details.aspx?id=30425). You
To use the sample code in this topic, you must install the [Open XML SDK 2.5](https://www.nuget.org/packages/Open-XML-SDK/2.5.0). You
must explicitly reference the following assemblies in your project:

- WindowsBase
Expand All @@ -47,9 +45,7 @@ the code in this topic.
-----------------------------------------------------------------------------
## AddTable Method

You can use the **AddTable** method to add a
simple table to a word processing document. The **AddTable** method accepts two parameters,
indicating the following:
You can use the **AddTable** method to add a simple table to a word processing document. The **AddTable** method accepts two parameters, indicating the following:

- The name of the document to modify (string).

Expand All @@ -68,10 +64,7 @@ indicating the following:
-----------------------------------------------------------------------------
## Calling the AddTable Method

The **AddTable** method modifies the document
you specify, adding a table that contains the information in the
two-dimensional array that you provide. To call the method, pass both of
the parameter values, as shown in the following code.
The **AddTable** method modifies the document you specify, adding a table that contains the information in the two-dimensional array that you provide. To call the method, pass both of the parameter values, as shown in the following code.

```csharp
const string fileName = @"C:\Users\Public\Documents\AddTable.docx";
Expand All @@ -95,11 +88,8 @@ the parameter values, as shown in the following code.
--------------------------------------------------------------------------------
## How the Code Works

The following code starts by opening the document, using the [WordprocessingDocument.Open](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.open.aspx) method and
indicating that the document should be open for read/write access (the
final **true** parameter value). Next the code
retrieves a reference to the root element of the main document part,
using the [Document](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.maindocumentpart.document.aspx) property of the [MainDocumentPart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.maindocumentpart.aspx) of the word processing
The following code starts by opening the document, using the [WordprocessingDocument.Open](https://docs.microsoft.com/dotnet/api/documentformat.openxml.packaging.wordprocessingdocument.open?view=openxml-2.8.1) method and
indicating that the document should be open for read/write access (the final **true** parameter value). Next the code retrieves a reference to the root element of the main document part, using the [Document](https://docs.microsoft.com/dotnet/api/documentformat.openxml.packaging.maindocumentpart.document?view=openxml-2.8.1) property of the [MainDocumentPart](https://docs.microsoft.com/dotnet/api/documentformat.openxml.packaging.wordprocessingdocument.maindocumentpart?view=openxml-2.8.1) of the word processing
document.

```csharp
Expand All @@ -120,10 +110,7 @@ document.
-----------------------------------------------------------------------------
## Creating the Table Object and Setting Its Properties

Before you can insert a table into a document, you must create the [Table](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.table.aspx) object and set its properties. To set
a table's properties, you create and supply values for a [TableProperties](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.tableproperties.aspx) object. The **TableProperties** class provides many
table-oriented properties, like [Shading](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.tableproperties.shading.aspx), [TableBorders](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.tableproperties.tableborders.aspx), [TableCaption](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.tableproperties.tablecaption.aspx), [TableCellSpacing](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.tableproperties.tablecellspacing.aspx), [TableJustification](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.tableproperties.tablejustification.aspx), and more. The sample
method includes the following code.
Before you can insert a table into a document, you must create the [Table](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.table?view=openxml-2.8.1) object and set its properties. To set a table's properties, you create and supply values for a [TableProperties](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.tableproperties?view=openxml-2.8.1) object. The **TableProperties** class provides many table-oriented properties, like [Shading](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.tableproperties.shading?view=openxml-2.8.1), [TableBorders](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.tableproperties.tableborders?view=openxml-2.8.1), [TableCaption](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.tableproperties.tablecaption?view=openxml-2.8.1), [TableCellSpacing](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.tableproperties.tablecellspacing?view=openxml-2.8.1), [TableJustification](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.tableproperties.tablejustification?view=openxml-2.8.1), and more. The sample method includes the following code.

```csharp
Table table = new Table();
Expand Down Expand Up @@ -190,33 +177,16 @@ method includes the following code.
table.AppendChild(Of TableProperties)(props)
```

The constructor for the **TableProperties**
class allows you to specify as many child elements as you like (much
like the <span sdata="cer"
target="M:System.Xml.Linq.XElement.#ctor(System.Xml.Linq.XName,System.Object[])">[XElement](https://msdn2.microsoft.com/library/bb358354)
constructor). In this case, the code creates [TopBorder](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.topborder.aspx), [BottomBorder](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.bottomborder.aspx), [LeftBorder](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.leftborder.aspx), [RightBorder](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.rightborder.aspx), [InsideHorizontalBorder](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.insidehorizontalborder.aspx), and [InsideVerticalBorder](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.insideverticalborder.aspx) child elements, each
describing one of the border elements for the table. For each element,
the code sets the **Val** and **Size** properties as part of calling the
constructor. Setting the size is simple, but setting the **Val** property requires a bit more effort: this
property, for this particular object, represents the border style, and
you must set it to an enumerated value. To do that, you create an
instance of the [EnumValue\<T\>](https://msdn.microsoft.com/library/office/cc801792.aspx) generic type, passing the
specific border type ([Single](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.bordervalues.aspx)) as a parameter to the constructor.
Once the code has set all the table border value it needs to set, it
calls the [AppendChild\<T\>](https://msdn.microsoft.com/library/office/cc846487.aspx) method of the table,
indicating that the generic type is [TableProperties](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.tableproperties.aspx)—that is, it is appending an
instance of the **TableProperties** class,
using the variable **props** as the value.

The constructor for the **TableProperties** class allows you to specify as many child elements as you like (much like the <span sdata="cer"
target="M:System.Xml.Linq.XElement.#ctor(System.Xml.Linq.XName,System.Object[])">[XElement](https://docs.microsoft.com/dotnet/api/system.xml.linq.xelement?view=net-5.0)
constructor). In this case, the code creates [TopBorder](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.topborder?view=openxml-2.8.1), [BottomBorder](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.bottomborder?view=openxml-2.8.1), [LeftBorder](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.leftborder?view=openxml-2.8.1), [RightBorder](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.rightborder?view=openxml-2.8.1), [InsideHorizontalBorder](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.insidehorizontalborder?view=openxml-2.8.1), and [InsideVerticalBorder](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.insideverticalborder?view=openxml-2.8.1) child elements, each
describing one of the border elements for the table. For each element, the code sets the **Val** and **Size** properties as part of calling the constructor. Setting the size is simple, but setting the **Val** property requires a bit more effort: this property, for this particular object, represents the border style, and you must set it to an enumerated value. To do that, you create an instance of the [EnumValue\<T\>](https://docs.microsoft.com/dotnet/api/documentformat.openxml.enumvalue-1?view=openxml-2.8.1) generic type, passing the specific border type ([Single](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.bordervalues?view=openxml-2.8.1) as a parameter to the constructor.
Once the code has set all the table border value it needs to set, it calls the [AppendChild\<T\>](https://docs.microsoft.com/dotnet/api/documentformat.openxml.openxmlelement.appendchild) method of the table, indicating that the generic type is [TableProperties](https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.wordprocessing.tableproperties?view=openxml-2.8.1)—that is, it is appending an instance of the **TableProperties** class, using the variable **props** as the value.

-----------------------------------------------------------------------------
## Filling the Table with Data

Given that table and its properties, now it is time to fill the table
with data. The sample procedure iterates first through all the rows of
data in the array of strings that you specified, creating a new [TableRow](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.tablerow.aspx) instance for each row of data. The
following code leaves out the details of filling in the row with data,
but it shows how you create and append the row to the table:
Given that table and its properties, now it is time to fill the table with data. The sample procedure iterates first through all the rows of data in the array of strings that you specified, creating a new [TableRow](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.tablerow?view=openxml-2.8.1) instance for each row of data. The following code leaves out the details of filling in the row with data, but it shows how you create and append the row to the table:

```csharp
for (var i = 0; i <= data.GetUpperBound(0); i++)
Expand All @@ -235,11 +205,7 @@ but it shows how you create and append the row to the table:
Next
```

For each row, the code iterates through all the columns in the array of
strings you specified. For each column, the code creates a new [TableCell](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.tablecell.aspx) object, fills it with data, and
appends it to the row. The following code leaves out the details of
filling each cell with data, but it shows how you create and append the
column to the table:
For each row, the code iterates through all the columns in the array of strings you specified. For each column, the code creates a new [TableCell](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.tablecell?view=openxml-2.8.1) object, fills it with data, and appends it to the row. The following code leaves out the details of filling each cell with data, but it shows how you create and append the column to the table:

```csharp
for (var j = 0; j <= data.GetUpperBound(1); j++)
Expand All @@ -260,16 +226,16 @@ column to the table:

Next, the code does the following:

- Creates a new [Text](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.text.aspx) object that contains a value from
- Creates a new [Text](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.text?view=openxml-2.8.1) object that contains a value from
the array of strings.

- Passes the [Text](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.text.aspx) object to the constructor for a
new [Run](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.run.aspx) object.
- Passes the [Text](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.text?view=openxml-2.8.1) object to the constructor for a
new [Run](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.run?redirectedfrom=MSDN&view=openxml-2.8.1) object.

- Passes the [Run](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.run.aspx) object to the constructor for a new
[Paragraph](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.paragraph.aspx) object.
- Passes the [Run](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.run?view=openxml-2.8.1) object to the constructor for a new
[Paragraph](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.paragraph?view=openxml-2.8.1) object.

- Passes the [Paragraph](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.paragraph.aspx) object to the [Append](https://msdn.microsoft.com/library/office/documentformat.openxml.openxmlelement.append.aspx)method of the cell.
- Passes the [Paragraph](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.paragraph?view=openxml-2.8.1) object to the [Append](https://msdn.microsoft.com/library/office/documentformat.openxml.openxmlelement.append.aspx)method of the cell.

In other words, the following code appends the text to the new **TableCell** object.

Expand All @@ -281,11 +247,8 @@ In other words, the following code appends the text to the new **TableCell** obj
tc.Append(New Paragraph(New Run(New Text(data(i, j)))))
```

The code then appends a new [TableCellProperties](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.tablecellproperties.aspx) object to the cell.
This **TableCellProperties** object, like the
**TableProperties** object you already saw, can
accept as many objects in its constructor as you care to supply. In this
case, the code passes only a new [TableCellWidth](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.tablecellwidth.aspx) object, with its [Type](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.tablewidthtype.type.aspx) property set to [Auto](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.tablewidthunitvalues.aspx) (so that the table automatically sizes
The code then appends a new [TableCellProperties](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.tablecellproperties?view=openxml-2.8.1) object to the cell. This **TableCellProperties** object, like the **TableProperties** object you already saw, can accept as many objects in its constructor as you care to supply. In this
case, the code passes only a new [TableCellWidth](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.tablecellwidth?view=openxml-2.8.1) object, with its [Type](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.tablewidthtype.type?view=openxml-2.8.1) property set to [Auto](https://docs.microsoft.com/dotnet/api/documentformat.openxml.wordprocessing.tablewidthunitvalues?view=openxml-2.8.1) (so that the table automatically sizes
the width of each column).

```csharp
Expand All @@ -303,8 +266,7 @@ the width of each column).
-----------------------------------------------------------------------------
## Finishing Up

The following code concludes by appending the table to the body of the
document, and then saving the document.
The following code concludes by appending the table to the body of the document, and then saving the document.

```csharp
doc.Body.Append(table);
Expand All @@ -319,8 +281,7 @@ document, and then saving the document.
-----------------------------------------------------------------------------
## Sample Code

The following is the complete **AddTable** code
sample in C\# and Visual Basic.
The following is the complete **AddTable** code sample in C\# and Visual Basic.

```csharp
// Take the data from a two-dimensional array and build a table at the
Expand Down