officedev / excel-custom-functions Goto Github PK

Learn about custom functions in Excel.

License: Other

HTML 15.55% JavaScript 39.58% TypeScript 41.24% CSS 3.62%

excel-custom-functions's Introduction

Custom functions in Excel

Custom functions enable you to add new functions to Excel by defining those functions in JavaScript as part of an add-in. Users within Excel can access custom functions just as they would any native function in Excel, such as SUM().

This repository contains the source code used by the Yo Office generator when you create a new custom functions project. You can also use this repository as a sample to base your own custom functions project from if you choose not to use the generator. For more detailed information about custom functions in Excel, see the Custom functions overview article in the Office Add-ins documentation or see the additional resources section of this repository.

Debugging custom functions

This template supports debugging custom functions from Visual Studio Code. For more information see Custom functions debugging. For general information on debugging task panes and other Office Add-in parts, see Test and debug Office Add-ins.

Questions and comments

We'd love to get your feedback about this sample. You can send your feedback to us in the Issues section of this repository.

Questions about Office Add-ins development in general should be posted to Microsoft Q&A. If your question is about the Office JavaScript APIs, make sure it's tagged with [office-js-dev].

Join the Microsoft 365 Developer Program

Join the Microsoft 365 Developer Program to get resources and information to help you build solutions for the Microsoft 365 platform, including recommendations tailored to your areas of interest.

You might also qualify for a free developer subscription that's renewable for 90 days and comes configured with sample data; for details, see the FAQ.

Additional resources

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Copyright

excel-custom-functions's People

Contributors

Stargazers

Watchers

excel-custom-functions's Issues

Excel Online: Functions getting stuck on #GETTING_DATA

Certain times, we have seen custom functions evaluate it and then after a bit, start returning #GETTING_DATA.

WebService

I working on this and want to pull data from a remote server, but I can't get it working.

In the documentation, XHR is talked about but there is no example. Have tried to use XMLHttpRequest, but get an N/A.

Would like some example code so I can then start building out my project

Can user use the custom function in normal version?

In the latest of insider version, it works. but my users are not in the insider version. I worried about that it dont works.

If there are some plan in the progress , please let know. Thank you.

Difference between On-Line and Local Copy for Custom Functions - Not Workings

Currently my Custom Functions loads for the On-Line version for Mac and PC and works with no problems but errors for Mac and PC local versions of Excel. I'm running the Fast Insider Version. Mac is 16.19 (181018) and PC is 1811(11010.20003).

<?xml version="1.0" encoding="utf-8"?> <OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0" xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="TaskPaneApp"> <Id>bad3ab85-f960-4e5d-b38e-1181bda51733</Id> <Version>1.0.0</Version> <ProviderName>NOW Functions</ProviderName> <DefaultLocale>en-US</DefaultLocale> <DisplayName DefaultValue="Excel to Xero Functions V1.0.0a" /> <Description DefaultValue="Connect Excel Functions to Xero" /> <Hosts> <Host Name="Workbook" /> </Hosts> <DefaultSettings> <SourceLocation DefaultValue="https://xeronowfunctions.appspot.com/storage/excel/fxindex.html"/> </DefaultSettings> <Permissions>ReadWriteDocument</Permissions> <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0"> <Hosts> <Host xsi:type="Workbook"> <AllFormFactors> <ExtensionPoint xsi:type="CustomFunctions"> <Script> <SourceLocation resid="JS-URL" /> </Script> <Page> <SourceLocation resid="HTML-URL"/> </Page> <Metadata> <SourceLocation resid="JSON-URL" /> </Metadata> <Namespace resid="namespace" /> </ExtensionPoint> </AllFormFactors> </Host> </Hosts> <Resources> <bt:Urls> <bt:Url id="JSON-URL" DefaultValue="https://xeronowfunctions.appspot.com/storage/excel/customfunctions.json" /> <bt:Url id="JS-URL" DefaultValue="https://xeronowfunctions.appspot.com/storage/excel/bundlefx.js" /> <bt:Url id="HTML-URL" DefaultValue="https://xeronowfunctions.appspot.com/storage/excel/fxindex.html" /> </bt:Urls> <bt:ShortStrings> <bt:String id="namespace" DefaultValue="NOWX" /> </bt:ShortStrings> </Resources> </VersionOverrides> </OfficeApp>

#NAME? Error In Spreadsheet

Hello, I've followed the instructions to the best of my knowledge so please bare with me.
I tried running = CONTOSO.ADD42(A1) where cell A1 is the number 1, and get a #NAME? error in Excel. So far I've

1)Am an office insider member and have a build version of 16.13.1
2)Cloned the repo, set up a server on port 3000 to serve the static files using Express
3)Changed localhost:8000 to localhost:3000 in the manifest file.
4)Sideloaded the add-in to the wef folder. I'm able to load the add-in in Excel (I get the iframe), but get the name error whenever I try to use any of the functions.

Thanks

Custom functions with latest release build

Will the sample (and to that extend, custom functions) work with the latest builds of office-js, 1.1.8 or 1.1.9?
As far as I can see neither Excel.CustomFunctions or Office.Preview.StartCustomFunctions exist anymore.

Can you provide us with a sample working against the latest versions of office-js?

EDIT: Just noticed that a '1.1.9-custom-functions-preview.5' tag exists. Still, what are the plans for merging this into the release tags? And where can we find detailed release notes for each release?

[x-post /office-js] #NAME Error Despite Following Instructions

Expected Behavior

To be able to activate a defined function using a name.

Current Behavior

I get a name error

Steps to Reproduce, or Live Example

https://github.com/haboutnnah/excel-anime-addin

npm run build and npm start work perfectly.

When opening Excel, I get a message stating that the addons loaded properly.

The task pane functions. (How do you disable this feature entirely?)

However, when attempting to call any of the defined functions, using either CONTOSO or my defined ANIME as the prefix, nothing occurs, no Intellisense, etc.

~~Note, this works (sans cors funkiness) on web excel - it appears to be an issue with macOS excel~~

Nevermind, this doesn't work either. I tried on Windows as well - "one or more add-ins failed to install or load custom functions".

Context

I'm trying to write an add-in to learn Office JS.

The Add-in simply has a few functions, that should all translate to excel functions.

Your Environment

Original:

Platform [PC desktop, Mac, iOS, Office Online]: Mac
Host [Excel, Word, PowerPoint, etc.]: Excel
Office version number: Excel 16.25
Operating System: Mac OS 10.13.6

Second:

Platform [PC desktop, Mac, iOS, Office Online]: Windows Desktop
Host [Excel, Word, PowerPoint, etc.]: Excel
Office version number: 1904 Build 11601.20042 Click-to-Run Office Insider
Operating System: Windows 10 1809

Useful logs

excel-js.log - The terminal dump in macos
debugadapter.txt - Windows real debug log

[Tracking item] Support for cookie based authentication between Custom Functions and Taskpane/Dialog

Currently we have support in the custom functions runtime to pass tokens between the taskpane and dialog to the custom function via Async Storage.

This doesn't work for cookie based authentication as the httpOnly cookie is not exposed to Javascript by the browser.

Team needs to evaluate this ask and prioritize accordingly based on what we can do.

Repeating Parameters [tracking item]

We will plan to have repeating parameters after Custom Functions will become GA. This is a tracking issue for that.

General idea would be to declare: {"repeating": true} for your parameter

OfficeRuntime.AsyncStorage API name change to "OfficeRuntime.Storage"

Hey folks,

OfficeRuntime.AsyncStorage to OfficeRuntime.Storage. Your existing add-ins will continue to work for a short period of time as this is one of the last items we want before we announce general availability! It will be available along with custom functions in our production CDN in a few weeks time.

Better error messages in runtime logging

This will come a bit after release but this issue tracks our plan for more meaningful runtime logging error messages.

Streaming Custom Functions will not re-calculate using Office JS Calculate API

Excel custom functions currently won't recalculate when performing the calculate event.

broken due to command start is not listed as dependency

Currently, users aren't able to execute npm start. Internally an executable is used called start also after installing start it doesnt work because the npm script name has higher priority.

Problem with using OfficeRuntime.storage in existing Excel Add-in

I'm trying to share some data between my existing Excel Add-in taskpane and newly added custom-functions. When I'm trying to set/get value I get "NotImplemented: Not implemented." error.

I'm referencing this package in my taskpane page:

<script src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script>

And I use storage in my taskpane this way:

OfficeRuntime.storage.setItem('someData', someData)
    .then((result) =>
    {
      console.log(result);
    }, (error) =>
    {
      console.log('Store error: ');
      console.log(error);
    });

I also use Typescript in my add-in, so I've added

"@types/office-runtime": "^1.0.7"

package for types.
I've seen in some examples OfficeRuntime.AsyncStorage used, but I can't use it, as it isn't available in the IntelliSense.

Also I want to add that I have Excel version 1904 (Build 11601.20204) and Windows 10 version 10.0.17763 Build 17763

Centralized Deployment Deployment Tracking: Custom Functions

This is tracking rollout of centralized deployment for Custom Functions, which will be a few weeks after we announce GA.

If your custom function add-in is in the store, then it can successfully be centrally deployed without waiting for this deployment.

Volatile Function

We need to be able to mark certain custom function as "volatile". I was not able to find this and I was wondering if you currently support this or will support this in near future. Thanks!

Question: How to pass configuration parameters to custom function's JavaScript context

Hello there, this is more a question than an issue ; I hope this is the right place to ask ...

How can I pass general server configuration values to the custom functions context?
e.g. I have no problem within the taskpane context because I have access to a DOM where I can generate things like

<script>
window.myparameters = { napoleonsWhiteHorseColor:"Probably black" };
</script>
<script src="myaddin.js"/>

but I have difficulties understanding how to do that for the CustomFunctions context since there is no HTML file nor DOM...
I mean, without access to window.location.href, I'm not even sure how to get the current server's URL (without hard-coding it which I am definitively not going to do) ; I could use that to make some request to/someoptionalvirtualpath/myparameters.json.

I thought about polling the AsyncStorage regularily and wait for the taskpane to post them there, but that really doesn't seem right ...

Subsidiary question: is there a way to use more than 1 JavaScript file for the CustomFunctions context? I haven't seen any way in the manifest.xml.
e.g. { file_1: "http://server/parameters_generated.js", file_2: "http://server/myaddin.js" }

Thank you!

function stockPrice(ticker) doesn't work in 1901 build

Hi! in the previous version the custom function works fine, and now the error #VALUE! is returned.

Following the instructions in: Excel custom functions tutorial (preview) - Office Add-ins

What do you mean

Publish the code files (HTML, JS, and JSON) to localhost. I may be a shrub, but i don't know how to do this.

Refresh custom functions output

I deployed some custom functions that fetch data and I wonder if there is any way to recall them ir order to refresh the output?

Example functions return #N/A

Prebuilt custom function does not seem to work on Excel Desktop.

Article URL

https://docs.microsoft.com/en-us/office/dev/add-ins/tutorials/excel-tutorial-create-custom-functions?tabs=excel-windows

Issue

Following the steps until Try out a prebuilt custom function went successful. However, after entering =CONTOSO.ADD(10;200) the result went from "#GETTING DATA" to "#N/A" instead of 210 in Excel Desktop. On Excel Online all seems fine.

Integrate custom functions in an existing excel add-in

I have an existing excel add-in developed with the js API that inserts a task pane and I wonder if it is possible to add custom functions to it? It seems that the manifest doens't support this kind of integration.

Custom Functions not working on macOS

I've created a sample Add-in to try custom functions in Excel on macOS.

The Add-in loads correctly but none of the custom functions can be executed from within Excel. Excel just prints #NAME?.

macOS: 10.13.6
Excel for Mac: 16.19 Build 181024

Office Insider program is joined by setting insider builds to Office Insider Fast in Microsoft AutoUpdate

Excel: ScriptLab will show an Invalid Metadata alert when re-registering a custom function

In an upcoming build, there is a bug where scriptlab may show the following error on registration:

Workaround: Reboot Excel or open ScriptLab on Excel Online.

Fix: will be in March release

Excel Custom Functions Return #N/A on build 11328.2008

Build 113298.2008 has an issue that prevents Excel Custom Functions from running. This issue has been fixed that will be rolling out as another update to Insiders in a couple of days.

If you haven't updated your build, wait for a few days (we'll close this issue when fixed). Otherwise, you can continue to build your solution on Excel Online. Sorry for the inconvenience!

Accessing Sheet Properties fro Custom Functions

When I do this call, it returns nothing when using "Custom Functions". The same code works with the Addin model. I actually want to share data between two Add-ins.

I expect the problem is loading the context.

Sample Code that is used in both.

var setProperty("MasterKey", "xxx");
var reply = getProperty("MasterKey");

function getProperty(name) {
    
    var setting = Office.context.document.settings.get(name);
    console.log("ReadSettings: "+ name+", "+setting);
    if (setting == ""){
        return null;
    } else {
        return setting;
    }
}


function setProperty(name, data) {
    console.log("setSetting: "+name+":"+data);
    Office.context.document.settings.set(name, data);
    Office.context.document.settings.saveAsync(function (asyncResult) {
        console.log('set settings saved with status: ' + name + " - "+ data + ", " + asyncResult.status);
    });
}

XHR/Fetch requests return #VALUE! on Windows build 16.011406.20002

Custom Functions on Windows that use XML or Fetch will see #VALUE! as the XHR call may fail.

To workaround, please use: Use Mac or Excel Online

Can i use optional parameters in custom functions？

Like get all user input from arguments

Calc not working on custom function created via Replace

Workflow:

In Excel PC, I have a UDF implemented via XLL, "=FDS()", throughout an existing workbook.
Still in Excel PC, perform a Replace to change all instances of "FDS(" function to "CUSTOMJS.NEWFDS(", which is the name of a custom function that will be implemented by an Office JS add-in. That add-in is NOT currently installed on the PC version of Excel.
Save the "translated" workbook.
Open the translated workbook in Excel online where the "CUSTOMJS.NEWFDS()" function is available.

The functions do not calculate upon opening the workbook. Pressing the "Calculate" button on the ribbon or using the Office JS Calculate API will not cause the functions to calculate.

The only way I found to get them to caclulate was to either select the cell, edit the formula and press Enter, or to perform the equivalent via the Office JS API (reassigning the cell.Formula property to itself).

Excel Online is returning #VALUE! for custom functions

Questions on future plans

Hey Guys,
This is more of a question than an issue:
How is this going to be implemented in future builds?
I'm guessing side-loading add-ins won't happen with day-to-day users so, is there a plan to embed JavaScript code within Excel files OR will JavaScript in Excel will always be through add-ins?

I am eager to hear your response.
Thanks,
Amit.

Calculation speed on Mac

I'm evaluating the feasibility of migrating our .NET Excel add-in and custom functions library to the new JavaScript custom functions. The performance on Mac for the simple functions seems really poor; is that a known issue? Here's a sample using the CONTOSO.ADD function: http://recordit.co/madOVzAHAH. What kind of performance can we reasonably expect once this becomes generally available?

Sample not working on Mac

I was trying the sample from https://github.com/OfficeDev/Excel-Custom-Functions on my mac, all the functions returns #GETTING_DATA other than the log function. It is probably probably because Excel has a log function already. I am using version 16.24(190306).

Question: What is the timeline for not requiring Insider Level status?

Ie. is there a future where this project supported for use in production environments?

[FYI] #GETTING_DATA will be changing to "#BUSY!"

We are changing the status that custom functions show while calculation.

Why?

#GETTING_DATA wasn't accurate in all cases.
#GETTING_DATA caused users columns to resize (so trying to decrease width for most locales).

Build you will start seeing this: Any build > 16.0.11505.10000.

Excel: Error Installing add-ins if your function name already exists

Bug: If you have an add-in with the same namespace and same function name already registered, an existing add-in will no longer work.

Upcoming fix: We will provide a better error message here. We did not want to have the same VBA behavior as showing up 2 functions with the same name but you could only call one. We will plan to make this expereince better with the ability to disambiguate the functions.

Tip: if you have multiple versions of the manifest, change the namespace to indicate environment, for testing purposes.

Custom Function caller

It is extremely important for us that the custom functions can receive the location of the cell, that is calling them. (For example, if the same custom function is called from A3, and C5, we need to know inside the function, if we are getting called from A3 or C5)

Can this be incorporated?

Custom functions not showing up

Here's my excel version, on Windows:

I ran npm start and it does load the add-in but not the custom functions part. I see the pane but that's it. I must have reinstalled office 5 times today... I used the office deploy tool and changed the xml file to make sure I was on InsiderFast, but it's still not working. What am I doing wrong?

I appreciate your help, I'm excited to write my first add-in!

Debug formula in Excel cell

We can debug a formula in Excel cell by using F9 key. For example we can select the range in a formula - A1:B3 below-, and hit F9 to see the values in the given range in array form to evaluate the values:

=SUM(A1:B3) returns to =SUM({1,4;2,5;3,6})

In Excel Custom Functions, this feature doesn't work. It simply converts to #VALUE! as soon as you hit F9.

=CUSTOM.SUM(A1:B3) returns to =CUSTOM.SUM(#VALUE!)

manifest file validation failed while loading sample add-in on Excel online

I tried to load the manifest file on Excel online.
The error I get is :

I used the validator tool you have to validate my manifest.xml file. I get the following errors :

Calling validation service. This might take a moment...
-------------------------------------
Validation: Failed

Error #1:
XML Schema Violation: Your manifest does not adhere to the current set of XML schema definitions for Office Add-in manifests. (link: https://aka.ms/add-in-manifest-schema-violation)
  - Details: The element 'ExtensionPoint' in namespace 'http://schemas.microsoft.com/office/taskpaneappversionoverrides' has incomplete content. List of possible elements expected: 'Metadata, Namespace' in namespace 'http://schemas.microsoft.com/office/taskpaneappversionoverrides'.
  - Line: 28
  - Column: 13
-------------------------------------

Issue: Multiple Functions with the same namespace causes runtime issues (stop gap fix)

If multiple functions are registered under the same namespace, it causes an ambiguous runtime error. A possible workaround could be to not include the namespace, or generate a unique namespace based off the name of the function.

The Add-In loaded correctly, but there is no CONTOSO function

The Add-In did show on the sidebar for me, but when I try out the CONTOSO function in step 5, excel did not have such a function. I'm using 64-bit Excel with Insider program, and already configured the Trusted root certification in step 3.

(Issue encountered when trying to complete the Excel Custom Functions tutorial: https://docs.microsoft.com/en-us/office/dev/add-ins/tutorials/excel-tutorial-create-custom-functions?tabs=excel-windows.)

[Tracking Item] Returning built in errors from a custom function

Currently, when you throw an error it returns #VALUE!. This work item captures the plan to allow for a custom function to return a built in error, with a custom error message (which will be shown in a popup menu in Office 365).

Feature request: Caller.address should also provide the workbook name

I'm working on a set of Custom Functions which needs to store data tied with an individual document. There currently is the AsyncStorage feature to interlink with the Taskpane, and the Taskpane can grab the settings data off of the document. However, the AsyncStorage is shared across all documents. Having a document identifier would allow data in AsyncStorage to be tied to specific documents.

Could you add a document ID or similar mechanism which uniquely identifies the document that the custom function is running on?

Debugging

I'm having great difficulty debugging the custom functions I am writing. I have attempted to follow the instructions to enable the debugger through IE settings, while running the F12Chooser.exe application (it appears to inconsistently find the relevant excel window).

I have have created a httpRequest function, but have received the #GETTING_DATA placeholder and no error is being presented.

Is there a better or more reliable way to review errors? I am sorely missing chrome/node debugging.

Can force return when resolve the result？

My customer function link to my company's database and which i get can be string or number, they want number can be formatted, but in json, i can only design 1 type.

function BASIC(Ticker) {
    // 请求数据配置
    var url = ""
    url = url + Ticker);

    return new OfficeExtension.Promise(function (resolve) {
        axios.get(url)
            .then(function (response) {
                return response.data
            })
            .then(function (json) {
                // result can be 'can not find ticker' or a number like 9.99
                var result = json["data"]
                resolve(result)
            })
            .catch(function (e) {
                resolve(e.message)
            })
    });
}

sample not working?

That's a cool demo for Excel UDF, but in my case, Excel doesn't accept the formula. I deployed the web with the adapted web URLs, tried to upload the manifext.xmls in Excel Online and desktop with a shared folder, but it does not work. Excel Desktop (Build 9001.2138) shows the "Custom functions sample" taskpane (not visible in Excel online), but that's it. Am I missing something? Thx!

I hosted only above mentioned files.
I created a folder in c drive, copied manifest with updated URL
shared folder and copy network path.
I added network path in excel Trusted Add-in catalog and checked show
in menu. closed excel and open it back.
I can see my addin under shared addin.
I selected and add in excel too.
i can see my addin under shared addin. i selected and add in excel too.

unfortunately i don't see Contoso.ADD42() function. i re did it. still no luck.
did i miss any step, did i do something wrong.
looking forward to hear back ASAP.

Thank you.