Skip to main content

How to: Update External References in the Loaded Workbook

  • 3 minutes to read

When the SpreadsheetControl loads a workbook containing external references, they are added to the IWorkbook.ExternalWorkbooks collection. However, the external references created in this manner are not “live”. The references contain cached data and the SpreadsheetControl cannot update them.

To make a reference updateable, it should be replaced with a reference to a workbook instance.

To create a workbook instance, a workbook file should be loaded to an instance of the Workbook class or to another SpreadsheetControl instance. Subsequently, the ExternalWorkbookCollection.Replace method is used to replace the cached reference with a live external reference.


Use of the Workbook class instance in production code requires a license to the Office File API or the DevExpress Universal Subscription.

A workbook name in the external reference should be identical to the WorkbookSaveOptions.CurrentFileName property of the referenced workbook instance when the workbook is added to the ExternalWorkbookCollection. That is, if the workbook instance is created by loading a file using a full path, the reference should contain the full path, e.g., ‘C:\Temp[Book1.xlsx]Sheet1’!B3. The string with a reference created in this manner might be long and inconvenient. The Workbook.Options.Save.CurrentFileName property of a referenced workbook enables you to specify a name that is easier to read, for example, “MyExternalWorkBook”. Replace the corresponding item of the ExternalWorkbookCollection with an instance of the workbook with a custom CurrentFileName, and use it in external references instead of the file name, e.g., [MyExternalWorkBook]Sheet1!B3.


You can also use the ExternalWorkbookCollection.Add or ExternalWorkbookCollection.Replace method with the alias parameter to specify a custom workbook name that can be used in external references instead of the original file name or when the external workbook is not saved to a file.

View Example

switch (radioGroup1.EditValue.ToString())
    case "full":
    // Option 1. To reference an external workbook, use the full path.
        myWorkbook = new Workbook();
    case "filename":
    // Option 2. To reference an external workbook, use the file name only.
        myWorkbook = new Workbook();
    case "custom":
    // Option 3. To reference an external workbook, use a custom "MyExtBook" name.
        myWorkbook = new Workbook();
        myWorkbook.Options.Save.CurrentFileName = "MyExtBook";

spreadsheetControl1.Document.DocumentSettings.Calculation.Mode = CalculationMode.Automatic;

// Adjust the external reference which already exists in the loaded workbook.
spreadsheetControl1.Document.ExternalWorkbooks.Replace(0, myWorkbook);

// Insert a formula with an external reference that uses the full path.
spreadsheetControl1.Document.Worksheets[0].Cells["B1"].Formula = String.Format("SUM('{0}\\{1}'!test)", Environment.CurrentDirectory, shortName);