Beheben von Problemen in benutzerdefinierten Funktionen

2025-05-23

Wenn Sie benutzerdefinierte Funktionen entwickeln, können beim Erstellen und Testen Ihrer Funktionen Fehler im Produkt auftreten.

Wichtig

Beachten Sie, dass benutzerdefinierte Excel-Funktionen auf den folgenden Plattformen verfügbar sind.

Office im Web
Office unter Windows
- Microsoft 365-Abonnement
- retail unbefristete Office 2016 und höher
- volumenlizenzierte unbefristete Office 2021 und höher
Office für Mac

Benutzerdefinierte Excel-Funktionen werden derzeit in den folgenden Artikeln nicht unterstützt:

Office auf dem iPad
Volumenlizenzierte unbefristete Versionen von Office 2019 oder früher unter Windows

Hinweis

Das einheitliche Manifest für Microsoft 365 unterstützt derzeit keine Projekte für benutzerdefinierte Funktionen. Sie müssen das Add-In-Manifest nur für projekte mit benutzerdefinierten Funktionen verwenden. Weitere Informationen finden Sie unter Office-Add-Ins-Manifest.

Um Probleme zu beheben, können Sie die Laufzeitprotokollierung aktivieren, um Fehler zu erfassen und auf die nativen Fehlermeldungen von Excel zu verweisen. Überprüfen Sie auch auf häufige Fehler, beispielsweise ob Zusagen eingehalten wurden.

Debuggen von benutzerdefinierten Funktionen

Informationen zum Debuggen von Add-Ins für benutzerdefinierte Funktionen, die eine freigegebene Runtime verwenden, finden Sie unter Übersicht über das Debuggen von Office-Add-Ins.

Informationen zum Debuggen von Add-Ins für benutzerdefinierte Funktionen, die keine freigegebene Runtime verwenden, finden Sie unter Debuggen von benutzerdefinierten Funktionen.

Aktivieren der Protokollierung zur Laufzeit

Wenn Sie Ihr Add-In in Office unter Windows testen, sollten Sie die Laufzeitprotokollierung aktivieren. Die Laufzeitprotokollierung liefert console.log-Anweisungen an eine separate Protokolldatei, die erstellt wird, um Ihnen bei der Ermittlung von Problemen zu helfen. Die Anweisungen decken eine Vielzahl von Fehlern ab, einschließlich Fehlern in Bezug auf die Manifestdatei Ihres Add-Ins, Laufzeitbedingungen oder die Installation Ihrer benutzerdefinierten Funktionen. Weitere Informationen zur Laufzeitprotokollierung finden Sie unter Debuggen des Add-Ins mit Laufzeitprotokollierung.

Überprüfen auf Excel-Fehlermeldungen

Excel stellt eine Reihe von eingebauten Fehlermeldungen zur Verfügung, die bei einem Berechnungsfehler an eine Zelle zurückgegeben werden. Benutzerdefinierte Funktionen verwenden nur die folgenden Fehlermeldungen: #NULL!, #DIV/0!, #VALUE!, #REF!, #NAME?, #NUM!, #N/A und #BUSY!.

Im Allgemeinen entsprechen diese Fehler den Fehlern, mit denen Sie möglicherweise bereits in Excel vertraut sind. Es gibt nur wenige Ausnahmen für benutzerdefinierte Funktionen, die hier aufgeführt sind:

Ein #NAME-Fehler bedeutet im Allgemeinen, dass ein Problem bei der Registrierung Ihrer Funktionen aufgetreten ist.
Ein #N/A-Fehler ist vielleicht auch ein Zeichen dafür, dass diese Funktion trotz Registrierung nicht ausgeführt werden konnte. Dies liegt in der Regel an einem fehlenden CustomFunctions.associate-Befehl.
Ein #VALUE-Fehler zeigt in der Regel einen Fehler in der Skriptdatei der Funktionen an.
Ein #REF!-Fehler zeigt möglicherweise an, dass der Funktionsname mit einem Funktionsnamen in einem bereits vorhandenen Add-In übereinstimmt.

Löschen des Office-Caches

Informationen zu benutzerdefinierten Funktionen werden von Office zwischengespeichert. Manchmal werden beim Erstellen und wiederholten Neuladen eines Add-Ins mit benutzerdefinierten Funktionen Ihre Änderungen möglicherweise nicht angezeigt. Sie können dies beheben, indem Sie den Office-Cache löschen. Weitere Informationen finden Sie unter Löschen des Office-Caches.

Löschen des Caches für benutzerdefinierte Funktionen, wenn das Add-In ausgeführt wird

Es kann vorkommen, dass Sie den Cache für benutzerdefinierte Funktionen für ein Add-In löschen müssen, das für Ihre Endbenutzer bereitgestellt wurde, damit Add-In-Updates und änderungen an benutzerdefinierten Funktioneneinstellungen gleichzeitig integriert werden. Ohne das Löschen eines benutzerdefinierten Funktionscaches kann es bis zu 24 Stunden dauern, bis Änderungen am functions.json und functions.js Dateien Ihre Endbenutzer erreichen, während Änderungen an taskpane.html Endbenutzer schneller erreichen.

Hinweis

Sobald diese Einstellung für ein Dokument aktiviert ist, wird sie wirksam, wenn das Dokument das nächste Mal mit dem Add-In geöffnet wird. Sie wird nicht sofort nach dem Aufruf der Funktion angewendet.

Um sicherzustellen, dass der Cache für benutzerdefinierte Funktionen vom Add-In gelöscht wird, fügen Sie der functions.js-Datei den folgenden Code hinzu, und rufen Sie dann die setForceRefreshOn -Methode in Ihrem Office.onReady Aufruf oder in einer anderen Add-In-Initialisierungslogik auf.

Wichtig

Dieser Vorgang zum Löschen des Caches für benutzerdefinierte Funktionen wird nur für add-ins mit benutzerdefinierten Funktionen unterstützt, die eine freigegebene Runtime verwenden.

// To enable custom functions cache clearing, add this method to your functions.js 
// file, and then call the `setForceRefreshOn` method in your `Office.onReady` call.
function setForceRefreshOn() {  
    Office.context.document.settings.set(  
        'Office.ForceRefreshCustomFunctionsCache',
        true  
    );  
    Office.context.document.settings.saveAsync();  
}

Tipp

Das häufige Aktualisieren des Caches für benutzerdefinierte Funktionen kann sich auf die Leistung auswirken. Daher sollte das Löschen des Caches für benutzerdefinierte Funktionen mit setForceRefreshOn nur während der Add-In-Entwicklung oder zum Beheben von Fehlern verwendet werden. Sobald ein Add-In für benutzerdefinierte Funktionen stabilisiert wurde, beenden Sie das Erzwingen von Cacheaktualisierungen.

Um den cache clear für benutzerdefinierte Funktionen in Ihrem Add-In zu deaktivieren, legen Sie auf false festOffice.ForceRefreshCustomFunctionsCache, und rufen Sie die -Methode in Ihrem Office.onReady Aufruf auf. Das folgende Codebeispiel zeigt ein Beispiel mit einer setForceRefreshOff -Methode.

// To disable custom functions cache clearing, add this method to your functions.js 
// file, and then call the `setForceRefreshOff` method in your `Office.onReady` call.
function setForceRefreshOff() {  
    Office.context.document.settings.set(  
        'Office.ForceRefreshCustomFunctionsCache',
        false  
    );  
    Office.context.document.settings.saveAsync();  
}

Häufige Probleme und Lösungen

Add-In kann nicht über localhost geöffnet werden: Verwenden einer lokalen Loopbackausnahme

Wenn der Fehler "Wir können dieses Add-In nicht über localhost öffnen" angezeigt wird, müssen Sie eine lokale Loopbackausnahme aktivieren. Ausführliche Informationen dazu finden Sie in diesem Microsoft Support-Artikel.

Protokollierung zur Laufzeit meldet "TypeError: Netzwerkanforderung fehlgeschlagen" in Excel für Windows

Wenn bei Aufrufen an Ihren localhost-Server die Fehlermeldung "TypeError: Netzwerkanforderung fehlgeschlagen" in Ihrem Laufzeitprotokoll angezeigt wird, müssen Sie eine lokale Loopback-Ausnahme aktivieren. Ausführliche Informationen dazu finden Sie unter Option 2 in diesem Microsoft Support-Artikel.

Sicherstellen, dass Versprechen eingelöst werden

Wenn Excel darauf wartet, dass eine benutzerdefinierte Funktion abgeschlossen wird, wird #BUSY in der Zelle angezeigt. Wenn Ihr benutzerdefinierter Funktionscode eine Zusage zurückgibt, die Zusage aber kein Ergebnis liefert, zeigt Excel weiter #BUSY! an. Überprüfen Sie Ihre Funktionen, um sicherzustellen, dass alle Versprechungen ein Ergebnis in eine Zelle zurückgeben.

Fehler: Der Entwicklungsserver wird bereits an Port 3000 ausgeführt

Manchmal sehen Sie beim Ausführen von npm start möglicherweise einen Fehler, der besagt, dass der Entwicklungsserver bereits an Port 3000 (oder dem vom Add-In verwendeten Port) ausgeführt wird. Sie können den Entwicklungsserver anhalten, indem Sie npm stop ausführen oder das Fenster „Node.js“ schließen. In einigen Fällen kann es einige Minuten dauern, bis der Entwicklungsserver nicht mehr ausgeführt wird.

Funktionen werden nicht geladen: Funktionen zuordnen

In Fällen, in denen Ihre JSON-Datei nicht registriert wurde und Sie Ihre eigenen JSON-Metadaten verfasst haben, wird möglicherweise ein #VALUE!-Fehler angezeigt, oder Sie erhalten die Benachrichtigung, dass das Add-In nicht geladen werden kann. Dies bedeutet normalerweise, dass Sie jeder benutzerdefinierten Funktion die zugehörige, in der JSON-Metadatendatei festgelegte id-Eigenschaft zuordnen müssen. Dies erfolgt mithilfe der CustomFunctions.associate() -Funktion. In der Regel erfolgt dieser Funktionsaufruf nach jeder Funktion oder am Ende der Skriptdatei. Wenn eine benutzerdefinierte Funktion nicht zugeordnet wurde, funktioniert sie nicht.

Das folgende Beispiel zeigt eine add-Funktion, gefolgt vom Namen der Funktion (add), der der entsprechenden JSON-ID ADD zugeordnet ist.

/**
 * Add two numbers.
 * @customfunction
 * @param {number} first First number.
 * @param {number} second Second number.
 * @returns {number} The sum of the two numbers.
 */
function add(first, second) {
  return first + second;
}

CustomFunctions.associate("ADD", add);

Weitere Informationen zu diesem Prozess finden Sie unter Zuordnen von Funktionsnamen zu JSON-Metadaten.

Bekannte Probleme

Bekannte Probleme werden im GitHub-Repository für benutzerdefinierte Excel-Funktionen nachverfolgt und gemeldet.

Feedback geben

Wenn Sie auf Probleme stoßen, die hier nicht dokumentiert sind, lassen Sie es uns wissen. Sie können Probleme auf zwei Arten melden:

In Excel unter Windows oder Mac

Wenn Sie Excel unter Windows oder macos verwenden, können Sie Feedback direkt aus Excel an das Office-Erweiterbarkeitsteam senden. Wählen Sie dazu Datei>Feedback>Stirnrunzeln senden aus. Das Senden eines Stirnrunzelns stellt die erforderlichen Protokolle bereit, um das Problem zu verstehen, auf das Sie gestoßen sind.

In Github

Sie können ein Problem, auf das Sie stoßen, entweder über die Funktion "Content Feedback" (Feedback zum Inhalt) am Ende jeder Seite der Dokumentation oder durch Melden eines neuen Problems direkt an das Repository für benutzerdefinierte Funktionen übermitteln.

Nächste Schritte

Erfahren Sie, wie Sie dafür sorgen, dass Ihre benutzerdefinierten Funktionen mit benutzerdefinierten XLL-Funktionen kompatibel sind.

Freigeben über