clean up docs\spreadsheet\how-to-insert-a-new-worksheet-into-a-spreadsheet.md

Author: mikeebowen

docs/includes/spreadsheet/open-spreadsheet.md

@@ -0,0 +1,17 @@
+## Getting a SpreadsheetDocument Object
+
+In the Open XML SDK, the <xref:DocumentFormat.OpenXml.Packaging.SpreadsheetDocument> class represents an
+Excel document package. To open and work with an Excel document, you
+create an instance of the `SpreadsheetDocument` class from the document.
+After you create the instance from the document, you can then obtain
+access to the main workbook part that contains the worksheets. The text
+in the document is represented in the package as XML using `SpreadsheetML` markup.
+
+To create the class instance from the document that you call one of the
+<xref:DocumentFormat.OpenXml.Packaging.SpreadsheetDocument.Open*> methods. Several are provided, each
+with a different signature. The sample code in this topic uses the [Open(String, Boolean)](/dotnet/api/documentformat.openxml.packaging.spreadsheetdocument.open?view=openxml-3.0.1#documentformat-openxml-packaging-spreadsheetdocument-open(system-string-system-boolean)) method with a
+signature that requires two parameters. The first parameter takes a full
+path string that represents the document that you want to open. The
+second parameter is either `true` or `false` and represents whether you want the file to
+be opened for editing. Any changes that you make to the document will
+not be saved if this parameter is `false`.

docs/spreadsheet/how-to-insert-a-new-worksheet-into-a-spreadsheet.md

@@ -20,23 +20,8 @@ This topic shows how to use the classes in the Open XML SDK for
 Office to insert a new worksheet into a spreadsheet document
 programmatically.
 
-## Getting a SpreadsheetDocument Object
-
-In the Open XML SDK, the <xref:DocumentFormat.OpenXml.Packaging.SpreadsheetDocument> class represents an
-Excel document package. To open and work with an Excel document, you
-create an instance of the `SpreadsheetDocument` class from the document.
-After you create the instance from the document, you can then obtain
-access to the main workbook part that contains the worksheets. The text
-in the document is represented in the package as XML using `SpreadsheetML` markup.
-
-To create the class instance from the document that you call one of the
-<xref:DocumentFormat.OpenXml.Packaging.SpreadsheetDocument.Open*> methods. Several are provided, each
-with a different signature. The sample code in this topic uses the [Open(String, Boolean)](/dotnet/api/documentformat.openxml.packaging.spreadsheetdocument.open?view=openxml-3.0.1#documentformat-openxml-packaging-spreadsheetdocument-open(system-string-system-boolean)) method with a
-signature that requires two parameters. The first parameter takes a full
-path string that represents the document that you want to open. The
-second parameter is either `true` or `false` and represents whether you want the file to
-be opened for editing. Any changes that you make to the document will
-not be saved if this parameter is `false`.
+[!include[Open Spreadsheet](../includes/spreadsheet/open-spreadsheet.md)]
+
 
 The code that calls the `Open` method is
 shown in the following `using` statement.

docs/spreadsheet/how-to-merge-two-adjacent-cells-in-a-spreadsheet.md

@@ -11,7 +11,7 @@ ms.suite: office
 ms.author: o365devx
 author: o365devx
 ms.topic: conceptual
-ms.date: 12/12/2023
+ms.date: 01/10/2025
 ms.localizationpriority: high
 ---
 # Merge two adjacent cells in a spreadsheet document
@@ -22,11 +22,52 @@ programmatically.
 
 --------------------------------------------------------------------------------
 
+[!include[Open Spreadsheet](../includes/spreadsheet/open-spreadsheet.md)]
+
+------------------------------------------------------
+
 [!include[Structure](../includes/spreadsheet/structure.md)]
 
 
 --------------------------------------------------------------------------------
-## Sample Code 
+
+## How the Sample Code Works
+
+After you have opened the spreadsheet file for editing, the code
+verifies that the specified cells exist, and if they do not exist, it
+creates them by calling the `CreateSpreadsheetCellIfNotExist` method and append
+it to the appropriate <xref:DocumentFormat.OpenXml.Spreadsheet.Row> object.
+
+### [C#](#tab/cs-1)
+[!code-csharp[](../../samples/spreadsheet/merge_two_adjacent_cells/cs/Program.cs#snippet1)]
+
+### [Visual Basic](#tab/vb-1)
+[!code-vb[](../../samples/spreadsheet/merge_two_adjacent_cells/vb/Program.vb#snippet1)]
+***
+
+In order to get a column name, the code creates a new regular expression
+to match the column name portion of the cell name. This regular
+expression matches any combination of uppercase or lowercase letters.
+For more information about regular expressions, see [Regular Expression Language Elements](/dotnet/standard/base-types/regular-expressions). The
+code gets the column name by calling the [Regex.Match](/dotnet/api/system.text.regularexpressions.regex.match#overloads).
+
+### [C#](#tab/cs-2)
+[!code-csharp[](../../samples/spreadsheet/merge_two_adjacent_cells/cs/Program.cs#snippet2)]
+
+### [Visual Basic](#tab/vb-2)
+[!code-vb[](../../samples/spreadsheet/merge_two_adjacent_cells/vb/Program.vb#snippet2)]
+***
+
+To get the row index, the code creates a new regular expression to match the row index portion of the cell name. This regular expression matches any combination of decimal digits. The following code creates a regular expression to match the row index portion of the cell name, comprised of decimal digits.
+
+### [C#](#tab/cs-3)
+[!code-csharp[](../../samples/spreadsheet/merge_two_adjacent_cells/cs/Program.cs#snippet3)]
+
+### [Visual Basic](#tab/vb-3)
+[!code-vb[](../../samples/spreadsheet/merge_two_adjacent_cells/vb/Program.vb#snippet3)]
+***
+
+## Sample Code
 
 The following code merges two adjacent cells in a <xref:DocumentFormat.OpenXml.Spreadsheet.Row> document package. When
 merging two cells, only the content from one of the cells is preserved.
@@ -41,8 +82,9 @@ The following is the complete sample code in both C\# and Visual Basic.
 
 ### [Visual Basic](#tab/vb)
 [!code-vb[](../../samples/spreadsheet/merge_two_adjacent_cells/vb/Program.vb#snippet0)]
+***
 
 --------------------------------------------------------------------------------
-## See also 
+## See also
 
 - [Open XML SDK class library reference](/office/open-xml/open-xml-sdk)

samples/spreadsheet/merge_two_adjacent_cells/cs/Program.cs

@@ -1,4 +1,3 @@
-// <Snippet0>
 using DocumentFormat.OpenXml;
 using DocumentFormat.OpenXml.Packaging;
 using DocumentFormat.OpenXml.Spreadsheet;
@@ -7,10 +6,12 @@
 using System.Linq;
 using System.Text.RegularExpressions;
 
+MergeTwoCells(args[0], args[1], args[2], args[3]);
 
 // Given a document name, a worksheet name, and the names of two adjacent cells, merges the two cells.
 // When two cells are merged, only the content from one cell is preserved:
 // the upper-left cell for left-to-right languages or the upper-right cell for right-to-left languages.
+// <Snippet0>
 static void MergeTwoCells(string docName, string sheetName, string cell1Name, string cell2Name)
 {
     // Open the document for editing.
@@ -77,10 +78,10 @@ static void MergeTwoCells(string docName, string sheetName, string cell1Name, st
         // Create the merged cell and append it to the MergeCells collection.
         MergeCell mergeCell = new MergeCell() { Reference = new StringValue(cell1Name + ":" + cell2Name) };
         mergeCells.Append(mergeCell);
-
-        worksheet.Save();
     }
 }
+
+// <Snippet1>
 // Given a Worksheet and a cell name, verifies that the specified cell exists.
 // If it does not exist, creates a new cell. 
 static void CreateSpreadsheetCellIfNotExist(Worksheet worksheet, string cellName)
@@ -98,8 +99,6 @@ static void CreateSpreadsheetCellIfNotExist(Worksheet worksheet, string cellName
         Cell cell = new Cell() { CellReference = new StringValue(cellName) };
         row.Append(cell);
         worksheet.Descendants<SheetData>().First().Append(row);
-
-        worksheet.Save();
     }
     else
     {
@@ -112,11 +111,10 @@ static void CreateSpreadsheetCellIfNotExist(Worksheet worksheet, string cellName
         {
             Cell cell = new Cell() { CellReference = new StringValue(cellName) };
             row.Append(cell);
-
-            worksheet.Save();
         }
     }
 }
+// </Snippet1>
 
 // Given a SpreadsheetDocument and a worksheet name, get the specified worksheet.
 static Worksheet? GetWorksheet(SpreadsheetDocument document, string worksheetName)
@@ -130,6 +128,7 @@ static void CreateSpreadsheetCellIfNotExist(Worksheet worksheet, string cellName
     return worksheetPart?.Worksheet;
 }
 
+// <Snippet2>
 // Given a cell name, parses the specified cell to get the column name.
 static string GetColumnName(string cellName)
 {
@@ -139,6 +138,9 @@ static string GetColumnName(string cellName)
 
     return match.Value;
 }
+// </Snippet2>
+
+// <Snippet3>
 // Given a cell name, parses the specified cell to get the row index.
 static uint GetRowIndex(string cellName)
 {
@@ -148,6 +150,5 @@ static uint GetRowIndex(string cellName)
 
     return uint.Parse(match.Value);
 }
+// </Snippet3>
 // </Snippet0>
-
-MergeTwoCells(args[0], args[1], args[2], args[3]);

samples/spreadsheet/merge_two_adjacent_cells/vb/Program.vb

@@ -1,4 +1,3 @@
-' <Snippet0>
 Imports System.Text.RegularExpressions
 Imports DocumentFormat.OpenXml
 Imports DocumentFormat.OpenXml.Packaging
@@ -12,13 +11,12 @@ Module Program
     ' Given a document name, a worksheet name, and the names of two adjacent cells, merges the two cells.
     ' When two cells are merged, only the content from one cell is preserved:
     ' the upper-left cell for left-to-right languages or the upper-right cell for right-to-left languages.
-    Private Sub MergeTwoCells(ByVal docName As String, ByVal sheetName As String, ByVal cell1Name As String, ByVal cell2Name As String)
+    ' <Snippet0>
+    Sub MergeTwoCells(docName As String, sheetName As String, cell1Name As String, cell2Name As String)
         ' Open the document for editing.
-        Dim document As SpreadsheetDocument = SpreadsheetDocument.Open(docName, True)
-
-        Using (document)
+        Using document As SpreadsheetDocument = SpreadsheetDocument.Open(docName, True)
             Dim worksheet As Worksheet = GetWorksheet(document, sheetName)
-            If ((worksheet Is Nothing) OrElse (String.IsNullOrEmpty(cell1Name) OrElse String.IsNullOrEmpty(cell2Name))) Then
+            If worksheet Is Nothing OrElse String.IsNullOrEmpty(cell1Name) OrElse String.IsNullOrEmpty(cell2Name) Then
                 Return
             End If
 
@@ -27,103 +25,108 @@ Module Program
             CreateSpreadsheetCellIfNotExist(worksheet, cell2Name)
 
             Dim mergeCells As MergeCells
-            If (worksheet.Elements(Of MergeCells)().Count() > 0) Then
-                mergeCells = worksheet.Elements(Of MergeCells).First()
+            If worksheet.Elements(Of MergeCells)().Count() > 0 Then
+                mergeCells = worksheet.Elements(Of MergeCells)().First()
             Else
                 mergeCells = New MergeCells()
 
                 ' Insert a MergeCells object into the specified position.
-                If (worksheet.Elements(Of CustomSheetView)().Count() > 0) Then
+                If worksheet.Elements(Of CustomSheetView)().Count() > 0 Then
                     worksheet.InsertAfter(mergeCells, worksheet.Elements(Of CustomSheetView)().First())
-                ElseIf (worksheet.Elements(Of DataConsolidate)().Count() > 0) Then
+                ElseIf worksheet.Elements(Of DataConsolidate)().Count() > 0 Then
                     worksheet.InsertAfter(mergeCells, worksheet.Elements(Of DataConsolidate)().First())
-                ElseIf (worksheet.Elements(Of SortState)().Count() > 0) Then
+                ElseIf worksheet.Elements(Of SortState)().Count() > 0 Then
                     worksheet.InsertAfter(mergeCells, worksheet.Elements(Of SortState)().First())
-                ElseIf (worksheet.Elements(Of AutoFilter)().Count() > 0) Then
+                ElseIf worksheet.Elements(Of AutoFilter)().Count() > 0 Then
                     worksheet.InsertAfter(mergeCells, worksheet.Elements(Of AutoFilter)().First())
-                ElseIf (worksheet.Elements(Of Scenarios)().Count() > 0) Then
+                ElseIf worksheet.Elements(Of Scenarios)().Count() > 0 Then
                     worksheet.InsertAfter(mergeCells, worksheet.Elements(Of Scenarios)().First())
-                ElseIf (worksheet.Elements(Of ProtectedRanges)().Count() > 0) Then
+                ElseIf worksheet.Elements(Of ProtectedRanges)().Count() > 0 Then
                     worksheet.InsertAfter(mergeCells, worksheet.Elements(Of ProtectedRanges)().First())
-                ElseIf (worksheet.Elements(Of SheetProtection)().Count() > 0) Then
+                ElseIf worksheet.Elements(Of SheetProtection)().Count() > 0 Then
                     worksheet.InsertAfter(mergeCells, worksheet.Elements(Of SheetProtection)().First())
-                ElseIf (worksheet.Elements(Of SheetCalculationProperties)().Count() > 0) Then
+                ElseIf worksheet.Elements(Of SheetCalculationProperties)().Count() > 0 Then
                     worksheet.InsertAfter(mergeCells, worksheet.Elements(Of SheetCalculationProperties)().First())
                 Else
                     worksheet.InsertAfter(mergeCells, worksheet.Elements(Of SheetData)().First())
                 End If
             End If
 
             ' Create the merged cell and append it to the MergeCells collection.
-            Dim mergeCell As MergeCell = New MergeCell()
-            mergeCell.Reference = New StringValue((cell1Name + (":" + cell2Name)))
+            Dim mergeCell As New MergeCell() With {
+                .Reference = New StringValue(cell1Name & ":" & cell2Name)
+            }
             mergeCells.Append(mergeCell)
-
-            worksheet.Save()
         End Using
     End Sub
 
-    ' Given a SpreadsheetDocument and a worksheet name, get the specified worksheet.
-    Private Function GetWorksheet(ByVal document As SpreadsheetDocument, ByVal worksheetName As String) As Worksheet
-        Dim sheets As IEnumerable(Of Sheet) = document.WorkbookPart.Workbook.Descendants(Of Sheet)().Where(Function(s) s.Name = worksheetName)
-        If (sheets.Count = 0) Then
-            ' The specified worksheet does not exist.
-            Return Nothing
-        End If
-        Dim worksheetPart As WorksheetPart = CType(document.WorkbookPart.GetPartById(sheets.First.Id), WorksheetPart)
-
-        Return worksheetPart.Worksheet
-    End Function
-
+    ' <Snippet1>
     ' Given a Worksheet and a cell name, verifies that the specified cell exists.
-    ' If it does not exist, creates a new cell.
-    Private Sub CreateSpreadsheetCellIfNotExist(ByVal worksheet As Worksheet, ByVal cellName As String)
+    ' If it does not exist, creates a new cell. 
+    Sub CreateSpreadsheetCellIfNotExist(worksheet As Worksheet, cellName As String)
         Dim columnName As String = GetColumnName(cellName)
         Dim rowIndex As UInteger = GetRowIndex(cellName)
 
-        Dim rows As IEnumerable(Of Row) = worksheet.Descendants(Of Row)().Where(Function(r) r.RowIndex.Value = rowIndex.ToString())
-
-        ' If the worksheet does not contain the specified row, create the specified row.
-        ' Create the specified cell in that row, and insert the row into the worksheet.
-        If (rows.Count = 0) Then
-            Dim row As Row = New Row()
-            row.RowIndex = New UInt32Value(rowIndex)
-
-            Dim cell As Cell = New Cell()
-            cell.CellReference = New StringValue(cellName)
-
+        Dim rows As IEnumerable(Of Row) = worksheet.Descendants(Of Row)().Where(Function(r) r.RowIndex?.Value = rowIndex)
+
+        ' If the Worksheet does not contain the specified row, create the specified row.
+        ' Create the specified cell in that row, and insert the row into the Worksheet.
+        If rows.Count() = 0 Then
+            Dim row As New Row() With {
+                .RowIndex = New UInt32Value(rowIndex)
+            }
+            Dim cell As New Cell() With {
+                .CellReference = New StringValue(cellName)
+            }
             row.Append(cell)
             worksheet.Descendants(Of SheetData)().First().Append(row)
-            worksheet.Save()
         Else
             Dim row As Row = rows.First()
-            Dim cells As IEnumerable(Of Cell) = row.Elements(Of Cell)().Where(Function(c) c.CellReference.Value = cellName)
 
-            ' If the row does not contain the specified cell, create the specified cell.
-            If (cells.Count = 0) Then
-                Dim cell As Cell = New Cell
-                cell.CellReference = New StringValue(cellName)
+            Dim cells As IEnumerable(Of Cell) = row.Elements(Of Cell)().Where(Function(c) c.CellReference?.Value = cellName)
 
+            ' If the row does not contain the specified cell, create the specified cell.
+            If cells.Count() = 0 Then
+                Dim cell As New Cell() With {
+                    .CellReference = New StringValue(cellName)
+                }
                 row.Append(cell)
-                worksheet.Save()
             End If
         End If
     End Sub
+    ' </Snippet1>
+
+    ' Given a SpreadsheetDocument and a worksheet name, get the specified worksheet.
+    Function GetWorksheet(document As SpreadsheetDocument, worksheetName As String) As Worksheet
+        Dim workbookPart As WorkbookPart = If(document.WorkbookPart, document.AddWorkbookPart())
+        Dim sheets As IEnumerable(Of Sheet) = workbookPart.Workbook.Descendants(Of Sheet)().Where(Function(s) s.Name = worksheetName)
+
+        Dim id As String = sheets.First().Id
+        Dim worksheetPart As WorksheetPart = If(id IsNot Nothing, CType(workbookPart.GetPartById(id), WorksheetPart), Nothing)
 
+        Return If(worksheetPart IsNot Nothing, worksheetPart.Worksheet, Nothing)
+    End Function
+
+    ' <Snippet2>
     ' Given a cell name, parses the specified cell to get the column name.
-    Private Function GetColumnName(ByVal cellName As String) As String
+    Function GetColumnName(cellName As String) As String
         ' Create a regular expression to match the column name portion of the cell name.
-        Dim regex As Regex = New Regex("[A-Za-z]+")
+        Dim regex As New Regex("[A-Za-z]+")
         Dim match As Match = regex.Match(cellName)
+
         Return match.Value
     End Function
+    ' </Snippet2>
 
+    ' <Snippet3>
     ' Given a cell name, parses the specified cell to get the row index.
-    Private Function GetRowIndex(ByVal cellName As String) As UInteger
+    Function GetRowIndex(cellName As String) As UInteger
         ' Create a regular expression to match the row index portion the cell name.
-        Dim regex As Regex = New Regex("\d+")
+        Dim regex As New Regex("\d+")
         Dim match As Match = regex.Match(cellName)
+
         Return UInteger.Parse(match.Value)
     End Function
+    ' </Snippet3>
+    ' </Snippet0>
 End Module
-' </Snippet0>