Garnet Custom Commands

Übersicht

Garnet unterstützt die Registrierung benutzerdefinierter Befehle und Transaktionen, die in C# implementiert sind, sowohl programmatisch auf der Serverseite als auch durch Ausführung des speziellen Befehls REGISTERCS auf der Clientseite.

Unterstützte benutzerdefinierte Befehlstypen

1. Benutzerdefinierte Rohzeichenbefehle (Custom Raw String Commands): Um einen benutzerdefinierten Rohzeichenbefehl zu implementieren, implementieren Sie eine Klasse, die von der Basisklasse CustomRawStringFunctions erbt (Siehe Beispiel: main\GarnetServer\Extensions\DeleteIfMatch.cs)
2. Benutzerdefinierte Objektbefehle (Custom Object Commands): Um einen benutzerdefinierten Objektbefehl zu implementieren, implementieren Sie Ihre benutzerdefinierte Objektklasse, die von der Basisklasse GarnetObjectBase erbt, sowie eine Factory, die Ihren Objekttyp erstellt und von der Basisklasse CustomObjectFactory erbt (Siehe Beispiel: main\GarnetServer\Extensions\MyDictObject.cs)
3. Benutzerdefinierte Transaktion (Custom Transaction): Um eine benutzerdefinierte Transaktion zu implementieren, implementieren Sie eine Klasse, die von der Basisklasse CustomTransactionProcedure erbt (Siehe Beispiel: main\GarnetServer\Extensions\ReadWriteTxn.cs)
4. Benutzerdefiniertes Verfahren (Custom Procedure): Um ein nicht-transaktionales Verfahren zu implementieren, implementieren Sie eine Klasse, die von der Basisklasse CustomProcedure erbt (Siehe Beispiel: main\GarnetServer\Extensions\Sum.cs)

Registrierung von Befehlen auf Serverseite

Um einen neuen benutzerdefinierten Befehl von der Serverseite zu registrieren, verwenden Sie die RegisterApi der GarnetServer-Instanz und rufen Sie entweder NewCommand oder NewTransactionProc auf, je nachdem, welchen benutzerdefinierten Befehlstyp Sie registrieren möchten.

1. Benutzerdefinierte Rohzeichenbefehle: Um einen neuen Befehl mit einer konkreten Klasse zu registrieren, die CustomRawStringFunctions implementiert, rufen Sie RegisterApi.NewCommand(string name, int numParams, CommandType type, CustomRawStringFunctions customFunctions, RespCommandsInfo commandInfo = null, long expirationTicks = 0) auf, wobei customFunctions eine Instanz der neuen konkreten Klasse ist.
2. Benutzerdefinierte Objektbefehle: Um einen neuen Befehl mit einer konkreten Klasse zu registrieren, die CustomObjectFactory implementiert, rufen Sie RegisterApi.NewCommand(string name, int numParams, CommandType commandType, CustomObjectFactory factory, RespCommandsInfo commandInfo = null) auf, wobei factory eine Instanz der neuen konkreten Klasse ist.
3. Benutzerdefinierte Transaktion: Um eine neue Transaktion mit einer konkreten Klasse zu registrieren, die CustomTransactionProcedure implementiert, rufen Sie NewTransactionProc(string name, int numParams, Func<CustomTransactionProcedure> proc, RespCommandsInfo commandInfo = null) auf, wobei proc ein Func ist, das eine Instanz der neuen konkreten Klasse zurückgibt.
4. Benutzerdefiniertes Verfahren: Um ein neues Verfahren mit einer konkreten Klasse zu registrieren, die CustomProcedure implementiert, rufen Sie RegisterApi.NewProcedure(string name, CustomProcedure customProcedure, RespCommandsInfo commandInfo = null, RespCommandDocs commandDocs = null) auf, wobei customProcedure eine Instanz der konkreten Verfahrensklasse ist.

Beachten Sie, dass jeder Aufruf von RegisterApi einen optionalen Parameter RespCommandsInfo commandInfo hat. Dieser Parameter ermöglicht es Ihnen, Garnet Metadaten bezüglich des benutzerdefinierten Befehls bereitzustellen, die für den Client beim Ausführen der Befehle COMMAND oder COMMAND INFO sichtbar sind.

Registrierung von Befehlen auf Clientseite

Um einen neuen benutzerdefinierten Befehl von der Clientseite zu registrieren, verwenden Sie den dedizierten Befehl REGISTERCS in der Client-Anwendung (Hinweis: Dies ist ein Admin-Befehl).
Der Befehl REGISTERCS nimmt Assemblies entgegen, die auf dem Server vorhanden sind und Implementierungen für eine der unterstützten benutzerdefinierten Befehlsklassen enthalten, und registriert die benutzerdefinierten Befehle auf dem Server gemäß den vom Client bereitgestellten Parametern.
Der Befehl REGISTERCS unterstützt die Registrierung mehrerer Befehle und/oder Transaktionen aus mehreren Dateien und/oder Verzeichnissen, die C#-Binärdateien (*.dll / *.exe) enthalten.

Aktivierung der Registrierung von Befehlen auf Clientseite

Um die Registrierung benutzerdefinierter Befehle auf Clientseite zu aktivieren, müssen Sie eine Liste zulässiger Pfade angeben, von denen Assemblies potenziell geladen werden können, und Modulbefehle aktivieren. Dies geschieht durch Setzen der Konfigurationsparameter EnableModuleCommand und ExtensionBinPaths. Beispiel (in garnet.config)

"EnableModuleCommand": "local",
"ExtensionBinPaths": ".\first\path\,..\..\second\path\"

Hinweis #1: Assemblies können aus jeder Verzeichnistiefe unter diesen angegebenen Pfaden geladen werden
Hinweis #2: Standardmäßig erlaubt Garnet nur das Laden digital signierter Assemblies. Um diese Anforderung zu entfernen (nicht empfohlen), setzen Sie den Konfigurationsparameter ExtensionAllowOnlySignedAssemblies auf false.

REGISTERCS-Befehl

Um den Befehl REGISTERCS auszuführen, geben Sie das Schlüsselwort REGISTERCS gefolgt von einem oder mehreren neuen Befehls-Subbefehlen ein, gefolgt vom optionalen Schlüsselwort INFO, dem ein Pfad zu einer JSON-Datei folgt, die ein serialisiertes Array von RespCommandsInfo-Objekten mit Metadaten zum Befehl enthält (*.json), gefolgt vom Schlüsselwort SRC, dem ein oder mehrere Pfade zu C#-Binärdateien oder Verzeichnissen, die C#-Binärdateien enthalten (*.dll / *.exe), folgen.

Vollständige Befehlssyntax:

REGISTERCS cmdType name numParams className [expTicks] [cmdType name numParams className [expTicks] ...] [INFO path] SRC path [path ...]

Jeder neue Befehl, den Sie registrieren möchten, wird durch eines der Befehlstyp-Schlüsselwörter gefolgt von seinen Parametern angegeben.

Syntax für neue Befehls-Subbefehle:

cmdType name numParams cmdType className [expTicks]

Befehlstyp
Die folgenden Schlüsselwörter sind gültige Werte für cmdType

• READ (Neuer Lese-Befehl)
• READMODIFYWRITE oder RMW (Neuer Lese-Änderungs-Schreib-Befehl)
• TRANSACTION oder TXN (Neue Transaktion)

Parameter

• name: Name des neuen Befehls
• numParams: Anzahl der Parameter, die der neue Befehl entgegennimmt
• className: Klassenname der konkreten Klasse, die CustomRawStringFunctions oder CustomObjectFactory für neue READ / RMW-Befehle implementiert, oder CustomTransactionProcedure für neue TXN-Befehle (muss in den Assemblies vorhanden sein, auf die in der Pfadliste verwiesen wird)
  
• expTicks: Ablaufzeit des Befehls in Ticks (nur relevant für benutzerdefinierte Rohzeichenbefehle, andernfalls ignoriert)
  • -1: vorhandene Ablaufmetadaten entfernen;
  • 0: behalte, was aktuell ist (oder kein Ablauf, wenn dies ein neuer Eintrag ist) - dies ist der Standard;
  • >0: => Ablauf auf den angegebenen Wert setzen.

Hinweis: Wenn der Server einen oder mehrere der angegebenen Befehle / Transaktionen nicht registrieren konnte oder wenn er eine oder mehrere der im Befehl REGISTERCS angegebenen Dateien oder Verzeichnisse nicht laden oder aufzählen konnte, werden keine Maßnahmen ergriffen (d.h. kein Befehl wird registriert) und die Ausführung des Befehls schlägt mit einer entsprechenden Fehlermeldung fehl.

RESP-Antwort

Gibt +OK bei Erfolg zurück, andernfalls --ERR Nachricht, falls vorhanden

REGISTERCS-Fehler

• ERR malformierter REGISTERCS-Befehl - Fehler bei der Analyse des REGISTERCS-Befehls
• ERR kann Befehlinformationsdatei nicht zugreifen. - Fehler beim Zugriff auf die Befehlinformationsdatei, die nach dem INFO-Schlüsselwort angegeben wurde
• ERR Befehlinformationsdatei ist nicht in zulässigen Pfaden enthalten. - Die Befehlinformationsdatei ist gemäß der Serverkonfiguration (ExtensionBinPaths in garnet.config) nicht im zulässigen Pfad enthalten.
• ERR malformierter Befehlinformationen JSON. - Fehler beim Deserialisieren der Befehlinformations-JSON-Datei
• ERR kann eine oder mehrere Binärdateien nicht zugreifen - Fehler beim Zugriff auf oder Aufzählen von ein oder mehreren Dateien oder Ordnern, die im Pfad angegeben sind
• ERR eine oder mehrere Binärdateien sind nicht in zulässigen Pfaden enthalten - Eine oder mehrere der angegebenen Binärpfade sind gemäß der Serverkonfiguration (ExtensionBinPaths in garnet.config) nicht im zulässigen Pfad enthalten.
• ERR kann eine oder mehrere Assemblies nicht laden - Fehler beim Laden einer oder mehrerer Assemblies aus Binärdateien, die aus dem Pfad abgerufen wurden (der Assembly-Ladevorgang wird für alle *.dll / *.exe-Dateien versucht, die angegeben oder in den angegebenen Verzeichnissen gefunden wurden)
• ERR eine oder mehrere geladene Assemblies sind nicht digital signiert - Eine oder mehrere der geladenen Assemblies sind nicht digital signiert. Dieser Fehler tritt auf, wenn versucht wird, unsignierte Assemblies zu laden, wenn die Serverkonfiguration so eingestellt ist, dass nur digital signierte Assemblies geladen werden dürfen (ExtensionAllowOnlySignedAssemblies in garnet.conf)
• ERR kann eine oder mehrere Klassen aus den angegebenen Assemblies nicht instanziieren - Fehler beim Erstellen einer Instanz einer oder mehrerer Klassen, die mit den geladenen Assemblies angegeben wurden (beachten Sie, dass jede Klasse einen leeren Konstruktor haben sollte)
• ERR kann eine oder mehrere nicht unterstützte Klassen nicht registrieren - Fehler beim Registrieren einer oder mehrerer nicht unterstützter Klassen, d.h. eine oder mehrere der Klassen haben keine der erwarteten Basisklassen implementiert