We’re excited to announce the API simplification for Office Scripts in public preview. The API design is packed with features intended to make the script development experience delightful. It carries forward all the functionalities provided by the previous model and makes the learning and development process much simpler.  

Easy to understand API features

The following are the highlights of the simplified Office Scripts API:  

• Office Scripts APIs can be invoked in a synchronous manner without having to worry about programming concepts such as promises or callbacks. ​ 
• Easier API design that includes simple object collections, getter and setter methods for property access, better error handling options, and more. 
• Improved APIs to interact with Excel objects such as range cell, table rows, and columns. 
• Development time static type checks offered by TypeScript language based IntelliSense. 

How do I get the simplified API features?

Users will automatically create scripts with the new APIs when the feature is fully available in public preview. This includes the newly recorded actions and new scripts created using the Code Editor. You can identify the simplified API design by inspecting the main function, which contains the top-level workbook object as its first argument, as shown.  

function main(workbook: ExcelScript.Workbook) { 
  // Your code goes here 
}

What does the simplified API look like?

Every script is provided a top-level workbook object of type ExcelScript.Workbook as an argument by the main function. Using the workbook object, your script interacts with the Excel workbook. As an example, the following script gets the active worksheet from the workbook and logs its name. 

function main(workbook: ExcelScript.Workbook) { 
  // Get active worksheet 
  let sheet = workbook.getActiveWorksheet(); 
  // Log the current worksheet's name. 
  console.log(sheet.getName()) 
}

Similarly, methods can be invoked on the objects directly and properties such as cell values can be set using the corresponding set method. Following example gets the active cell, clears its value and formatting, and then sets a new value.  

function main(workbook: ExcelScript.Workbook) { 
  // Get active cell  
  let cell = workbook.getActiveCell(); 
  // Clear the cell value and format  
  cell.clear(); 
  // Set the cell value 
  cell.setValue("Sample data"); 
}

Excel object collection handling is as simple as managing regular object arrays. As an example, the following example reads and prints worksheet names along with the number of worksheets in the workbook. 

function main(workbook: ExcelScript.Workbook) { 
  // Get all sheets as a collection.  
  const sheets = workbook.getWorksheets(); 
  // Collect names of the worksheets 
  const names = sheets.map ((sheet) => sheet.getName()); 
  // Log the names of worksheets and the total worksheets within the workbook 
  console.log(names); 
  console.log(`Total worksheets inside of this workbook: ${sheets.length}`); 
}

What happens to the older scripts?

If you have recorded or created Office Scripts using the older model, rest assured that such scripts will continue to work. You can continue to edit and run such scripts. However, all newly recorded and created scripts will use the simplified Office Scripts API.  

If you want to use the simplified APIs in the older scripts or convert to the new simplified API, you must start with a new script.  

Note that if your main function looks like the following, your script is using the older asynchronous model.  

async function main(context: Excel.RequestContext) { 
  // Your code here 
}

To learn more about the simplified Office Scripts API, see Office Scripts documentation.  

Next Steps

We look forward to hearing from you. If you have any feedback or suggestions for the new Office Scripts feature, please let us know via User Voice. If you have any API usage related questions, ask your question on Stack Overflow and tag with [office-scripts]. If you have a problem with the Action Recorder or API, send feedback through the Help > Feedback button in Excel for the web.  

Happy Office Scripting!