{"id":4955,"date":"2020-07-01T11:09:06","date_gmt":"2020-07-01T18:09:06","guid":{"rendered":"https:\/\/officedevblogs.wpengine.com\/?p=4955"},"modified":"2022-05-31T09:11:21","modified_gmt":"2022-05-31T16:11:21","slug":"announcing-a-simplified-api-for-office-scripts","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/announcing-a-simplified-api-for-office-scripts\/","title":{"rendered":"Announcing a simplified API for Office Scripts"},"content":{"rendered":"<p><span class=\"TextRun SCXW57425408 BCX0\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW57425408 BCX0\">We&#8217;re excited to announce the API simplification for <\/span><\/span><a class=\"Hyperlink SCXW57425408 BCX0\" href=\"https:\/\/docs.microsoft.com\/en-us\/office\/dev\/scripts\/\" target=\"_blank\" rel=\"noreferrer noopener\"><span class=\"TextRun Underlined SCXW57425408 BCX0\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"none\"><span class=\"NormalTextRun SCXW57425408 BCX0\" data-ccp-charstyle=\"Hyperlink\">Office Scripts<\/span><\/span><\/a><span class=\"TextRun SCXW57425408 BCX0\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW57425408 BCX0\">\u00a0<\/span><\/span><span class=\"TextRun SCXW57425408 BCX0\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun CommentStart SCXW57425408 BCX0\">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.\u00a0<\/span><\/span><span class=\"EOP SCXW57425408 BCX0\" data-ccp-props=\"{&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/p>\n<h3>Easy to\u00a0understand API features<\/h3>\n<p><span data-contrast=\"auto\">The following are the <\/span><span data-contrast=\"auto\">highlights\u00a0<\/span><span data-contrast=\"auto\">of the simplified Office Scripts API:\u00a0<\/span><span data-ccp-props=\"{&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/p>\n<ul>\n<li data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"2\" data-aria-posinset=\"1\" data-aria-level=\"1\"><span data-contrast=\"auto\">Office Scripts APIs can be invoked in a synchronous manner without having to worry about programming concepts such as promises or callbacks. \u200b<\/span><span data-ccp-props=\"{&quot;134233279&quot;:true,&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/li>\n<li data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"2\" data-aria-posinset=\"2\" data-aria-level=\"1\"><span data-contrast=\"auto\">Easier<\/span><span data-contrast=\"auto\">\u00a0API design that includes\u00a0<\/span><span data-contrast=\"auto\">simple\u00a0<\/span><span data-contrast=\"auto\">object\u00a0<\/span><span data-contrast=\"auto\">collectio<\/span><span data-contrast=\"auto\">n<\/span><span data-contrast=\"auto\">s<\/span><span data-contrast=\"auto\">, getter and setter\u00a0<\/span><span data-contrast=\"auto\">methods\u00a0<\/span><span data-contrast=\"auto\">for property access,\u00a0<\/span><span data-contrast=\"auto\">b<\/span><span data-contrast=\"auto\">etter\u00a0<\/span><span data-contrast=\"auto\">error handling<\/span><span data-contrast=\"auto\">\u00a0options<\/span><span data-contrast=\"auto\">, and more.<\/span><span data-ccp-props=\"{&quot;134233279&quot;:true,&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/li>\n<li data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"2\" data-aria-posinset=\"3\" data-aria-level=\"1\"><span data-contrast=\"auto\">Improved\u00a0<\/span><span data-contrast=\"auto\">APIs to interact with\u00a0<\/span><span data-contrast=\"auto\">Excel objects such as\u00a0<\/span><span data-contrast=\"auto\">range\u00a0<\/span><span data-contrast=\"auto\">cell, table rows,<\/span><span data-contrast=\"auto\">\u00a0and columns<\/span><span data-contrast=\"auto\">.<\/span><span data-ccp-props=\"{&quot;134233279&quot;:true,&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/li>\n<li data-leveltext=\"\uf0b7\" data-font=\"Symbol\" data-listid=\"1\" data-aria-posinset=\"4\" data-aria-level=\"1\"><span data-contrast=\"auto\">Development time\u00a0<\/span><span data-contrast=\"auto\">static type chec<\/span><span data-contrast=\"auto\">ks\u00a0<\/span><span data-contrast=\"auto\">offered by<\/span><span data-contrast=\"auto\">\u00a0<\/span><span data-contrast=\"auto\">TypeScript language based <\/span><span data-contrast=\"auto\">Intelli<\/span><span data-contrast=\"auto\">S<\/span><span data-contrast=\"auto\">ens<\/span><span data-contrast=\"auto\">e<\/span><span data-contrast=\"auto\">.<\/span><span data-ccp-props=\"{&quot;134233279&quot;:true,&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/li>\n<\/ul>\n<h3>How do I get the\u00a0simplified API features?<\/h3>\n<p><span data-contrast=\"auto\">Users will automatically\u00a0<\/span><span data-contrast=\"auto\">create scripts with the new APIs when th<\/span><span data-contrast=\"auto\">e feature is fully available in public preview.\u00a0<\/span><span data-contrast=\"auto\">This includes the n<\/span><span data-contrast=\"auto\">ewly\u00a0<\/span><span data-contrast=\"auto\">r<\/span><span data-contrast=\"auto\">ecord<\/span><span data-contrast=\"auto\">ed<\/span><span data-contrast=\"auto\">\u00a0<\/span><span data-contrast=\"auto\">a<\/span><span data-contrast=\"auto\">ctions<\/span><span data-contrast=\"auto\">\u00a0<\/span><span data-contrast=\"auto\">and<\/span><span data-contrast=\"auto\">\u00a0new script<\/span><span data-contrast=\"auto\">s<\/span><span data-contrast=\"auto\">\u00a0<\/span><span data-contrast=\"auto\">created\u00a0<\/span><span data-contrast=\"auto\">using the Code Editor.\u00a0<\/span><span data-contrast=\"auto\">You can identify the simplified API design by inspecting the <\/span><i><span data-contrast=\"auto\">main<\/span><\/i><span data-contrast=\"auto\">\u00a0function, which contains the\u00a0<\/span><span data-contrast=\"auto\">top-level<\/span><span data-contrast=\"auto\">\u00a0<\/span><i><span data-contrast=\"auto\">workbook<\/span><\/i><span data-contrast=\"auto\"> object as its first argument, as shown. <\/span><span data-ccp-props=\"{&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/p>\n<pre class=\"bottom-set:false lang:null decode:true lang: \">function\u202fmain(workbook:\u202fExcelScript.Workbook)\u202f{ \n\u202f\u202f\/\/\u202fYour\u202fcode\u202fgoes\u202fhere \n}<\/pre>\n<h3>What does the simplified API look like?<\/h3>\n<p><span data-contrast=\"auto\">Every script is provided a\u00a0<\/span><span data-contrast=\"auto\">top-level<\/span><span data-contrast=\"auto\">\u00a0<\/span><strong>workbook<\/strong><span data-contrast=\"auto\"><strong>\u00a0<\/strong>object of type\u00a0<\/span><strong>ExcelScript.Workbook<\/strong><span data-contrast=\"auto\">\u00a0<\/span><span data-contrast=\"auto\">as an argument\u00a0<\/span><span data-contrast=\"auto\">by the\u00a0<\/span><strong>main<\/strong><span data-contrast=\"auto\">\u00a0function.\u00a0<\/span><span data-contrast=\"auto\">Using the\u00a0<\/span><strong>workbook<\/strong><span data-contrast=\"auto\"><strong>\u00a0<\/strong>object, your script interacts with the Excel workbook<\/span><span data-contrast=\"auto\">. As an example, t<\/span><span data-contrast=\"auto\">he following script gets the active worksheet from the workbook and logs its name.<\/span><span data-ccp-props=\"{&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/p>\n<pre class=\"lang: decode:true\">function\u202fmain(workbook:\u202fExcelScript.Workbook)\u202f{ \n\u202f\u202f\/\/\u202fGet\u202factive\u202fworksheet \n\u202f\u202flet\u202fsheet\u202f=\u202fworkbook.getActiveWorksheet(); \n\u202f\u202f\/\/\u202fLog\u202fthe\u202fcurrent\u202fworksheet's\u202fname. \n\u202f\u202fconsole.log(sheet.getName()) \n}<\/pre>\n<p><span data-contrast=\"auto\">Similarly, methods can be invoked on the objects directly and properties such as cell values can be set using the corresponding\u00a0<\/span><strong>set<\/strong><span data-contrast=\"auto\"><strong>\u00a0<\/strong>method. Following example gets the active cell, clears its value and formatting, and then sets a new value.\u00a0<\/span><span data-ccp-props=\"{&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/p>\n<pre class=\"lang: decode:true lang:\">function\u202fmain(workbook:\u202fExcelScript.Workbook)\u202f{ \n\u202f\u202f\/\/\u202fGet\u202factive\u202fcell\u202f \n\u202f\u202flet\u202fcell\u202f=\u202fworkbook.getActiveCell(); \n\u202f\u202f\/\/\u202fClear\u202fthe\u202fcell\u202fvalue\u202fand\u202fformat\u202f \n\u202f\u202fcell.clear(); \n\u202f\u202f\/\/\u202fSet\u202fthe\u202fcell\u202fvalue \n\u202f\u202fcell.setValue(\"Sample\u202fdata\"); \n}<\/pre>\n<p><span class=\"TextRun SCXW209575765 BCX0\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW209575765 BCX0\">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.<\/span><\/span><span class=\"EOP SCXW209575765 BCX0\" data-ccp-props=\"{&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/p>\n<pre class=\"lang: decode:true \">function\u202fmain(workbook:\u202fExcelScript.Workbook)\u202f{ \n\u202f\u202f\/\/\u202fGet\u202fall\u202fsheets\u202fas\u202fa\u202fcollection.\u202f \n\u202f\u202fconst\u202fsheets\u202f=\u202fworkbook.getWorksheets(); \n\u202f\u202f\/\/\u202fCollect\u202fnames\u202fof\u202fthe\u202fworksheets \n\u202f\u202fconst\u202fnames\u202f=\u202fsheets.map\u202f((sheet)\u202f=&gt;\u202fsheet.getName()); \n\u202f\u202f\/\/\u202fLog\u202fthe\u202fnames\u202fof\u202fworksheets\u202fand\u202fthe\u202ftotal\u202fworksheets\u202fwithin\u202fthe\u202fworkbook \n\u202f\u202fconsole.log(names); \n\u202f\u202fconsole.log(`Total\u202fworksheets\u202finside\u202fof\u202fthis\u202fworkbook:\u202f${sheets.length}`); \n}<\/pre>\n<h3>What happens to the older scripts?<\/h3>\n<p><span data-contrast=\"auto\">If you have recorded or created Office Scripts using the older\u00a0<\/span><span data-contrast=\"auto\">model<\/span><span data-contrast=\"auto\">, rest assured that such script<\/span><span data-contrast=\"auto\">s<\/span><span data-contrast=\"auto\"> will continue to work. You can continue to edit and run such scripts. However, all newly <\/span><span data-contrast=\"auto\">r<\/span><span data-contrast=\"auto\">ecorded<\/span><span data-contrast=\"auto\">\u00a0<\/span><span data-contrast=\"auto\">and\u00a0<\/span><span data-contrast=\"auto\">created<\/span><span data-contrast=\"auto\">\u00a0scripts will use the simplified\u00a0<\/span><span data-contrast=\"auto\">Office Scripts API<\/span><span data-contrast=\"auto\">.\u00a0<\/span><span data-ccp-props=\"{&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/p>\n<p><span data-contrast=\"auto\">I<\/span><span data-contrast=\"auto\">f you want <\/span><span data-contrast=\"auto\">to\u00a0<\/span><span data-contrast=\"auto\">use the simplified APIs\u00a0<\/span><span data-contrast=\"auto\">in the\u00a0<\/span><span data-contrast=\"auto\">older\u00a0<\/span><span data-contrast=\"auto\">scripts<\/span><span data-contrast=\"auto\">\u00a0<\/span><span data-contrast=\"auto\">or\u00a0<\/span><span data-contrast=\"auto\">convert to the new\u00a0<\/span><span data-contrast=\"auto\">simplified API<\/span><span data-contrast=\"auto\">,\u00a0<\/span><span data-contrast=\"auto\">you must\u00a0<\/span><span data-contrast=\"auto\">start with a <\/span><span data-contrast=\"auto\">new script.\u00a0<\/span><span data-ccp-props=\"{&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/p>\n<p><span data-contrast=\"auto\">Note that\u00a0<\/span><span data-contrast=\"auto\">if your\u00a0<\/span><strong>main<\/strong><span data-contrast=\"auto\"><strong>\u00a0<\/strong>function looks like\u00a0<\/span><span data-contrast=\"auto\">the following, your script is using the older asynchronous model. <\/span><span data-ccp-props=\"{&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/p>\n<pre class=\"lang: decode:true \">async\u202ffunction\u202fmain(context:\u202fExcel.RequestContext)\u202f{ \n\u202f\u202f\/\/\u202fYour\u202fcode\u202fhere \n}<\/pre>\n<p><span data-ccp-props=\"{&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\"><span class=\"TextRun SCXW82643521 BCX0\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW82643521 BCX0\">To lea<\/span><\/span><span class=\"TextRun SCXW82643521 BCX0\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW82643521 BCX0\">rn more<\/span><\/span><span class=\"TextRun SCXW82643521 BCX0\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW82643521 BCX0\">\u00a0about the simplified Office Scripts API<\/span><\/span><span class=\"TextRun SCXW82643521 BCX0\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW82643521 BCX0\">, see <a href=\"https:\/\/docs.microsoft.com\/office\/dev\/scripts\/\">Office Scripts documentation<\/a><\/span><\/span><span class=\"FieldRange SCXW82643521 BCX0\"><span class=\"TextRun Underlined SCXW82643521 BCX0\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"none\"><span class=\"NormalTextRun CommentStart SCXW82643521 BCX0\" data-ccp-charstyle=\"Hyperlink\">.<\/span><\/span><\/span><span class=\"TextRun SCXW82643521 BCX0\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"auto\"><span class=\"NormalTextRun SCXW82643521 BCX0\">\u00a0<\/span><\/span><span class=\"EOP SCXW82643521 BCX0\" data-ccp-props=\"{&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/span><\/p>\n<h3>Next Steps<\/h3>\n<p><span data-contrast=\"auto\">We look forward to hearing from you.\u00a0<\/span><span data-contrast=\"auto\">If you have any feedback or suggestions for the new Office Scripts feature, please let us know via\u00a0<\/span><a href=\"https:\/\/excel.uservoice.com\/\"><span data-contrast=\"none\">User Voice<\/span><\/a><span data-contrast=\"auto\">.<\/span><span data-contrast=\"auto\">\u00a0<\/span><span data-contrast=\"auto\">If you have any API usage related questions<\/span><span data-contrast=\"auto\">,<\/span><span data-contrast=\"auto\">\u00a0<\/span><span data-contrast=\"auto\">a<\/span><span data-contrast=\"auto\">sk your question\u00a0<\/span><span data-contrast=\"auto\">on <\/span><a href=\"https:\/\/stackoverflow.com\/questions\/tagged\/office-scripts\"><span data-contrast=\"none\">Stack Overflow<\/span><\/a><span data-contrast=\"auto\"> and tag with <\/span>[office-scripts]<span data-contrast=\"auto\">.\u00a0<\/span><span data-contrast=\"auto\">If you have a problem with the Action Recorder or <\/span><span data-contrast=\"auto\">API<\/span><span data-contrast=\"auto\">, send feedback through the\u00a0<\/span><strong>Help &gt; Feedback<\/strong><span data-contrast=\"auto\">\u00a0button in\u00a0<\/span><span data-contrast=\"auto\">Excel<\/span><span data-contrast=\"auto\">\u00a0<\/span><span data-contrast=\"auto\">for the web<\/span><span data-contrast=\"auto\">.<\/span><span data-contrast=\"auto\">\u00a0<\/span><span data-ccp-props=\"{&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/p>\n<p><span data-contrast=\"auto\">Happy\u00a0<\/span><span data-contrast=\"auto\">Office S<\/span><span data-contrast=\"auto\">cripting<\/span><span data-contrast=\"auto\">!<\/span><span data-ccp-props=\"{&quot;201341983&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"<p>We&#8217;re excited to announce the API simplification for Office Scripts\u00a0in 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.\u00a0\u00a0<\/p>\n","protected":false},"author":69080,"featured_media":25159,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[11],"tags":[18,177],"class_list":["post-4955","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-office-add-ins","tag-excel","tag-office-scripts"],"acf":[],"blog_post_summary":"<p>We&#8217;re excited to announce the API simplification for Office Scripts\u00a0in 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.\u00a0\u00a0<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/4955","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69080"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=4955"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/4955\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/25159"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=4955"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=4955"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=4955"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}