Zum Hauptinhalt springen

Onboarding für die Garnet-Entwicklung

Willkommen bei Garnet! Auf dieser Seite finden Sie die wichtigsten Schritte zur Einrichtung Ihrer Arbeitsumgebung für die Entwicklung in Garnet.

Schnellstart & nützliche Ressourcen​

Für eine Einführung in Garnet und seine Funktionen können Sie mit der Seite Willkommen bei Garnet beginnen.

Zusätzlich könnten die folgenden Seiten und Dokumentationen hilfreich sein

Werkzeuge​

  • Visual Studio 2022 (Vorschauversion empfohlen)
  • .NET 8.x
  • Git
  • Azure Windows VM
  • Azure Linux VM
  • Ein interaktiver RESP-Client, wie z.B.
    • Unter Linux: redis-cli, interaktiver RESP-Client unter Linux
    • Unter Windows: Memurai (für die Verwendung des Memurai-CLI-Clients) oder redis-cli über WSL
    • RedisInsight zum Experimentieren mit den Inhalten des Speichers
    • telnet

Beginnen Sie mit dem Hacken​

  1. Klonen Sie das Repository
git clone https://github.com/microsoft/garnet.git

Nach dem Klonen des Repositories können Sie entweder die Unit-Tests ausführen oder den Server starten und einen der unter Windows oder Linux vorgeschlagenen RESP-Clients verwenden.

  1. Führen Sie die Testsuite aus
    dotnet test -c Release -l "console;verbosity=detailed"
  1. Führen Sie den Server aus

Verwendung einer Speichergröße von 4 GB und einer Indexgröße von 64 MB

cd <root>/main/GarnetServer/
dotnet run -c Debug -f net8.0 -- --logger-level Trace -m 4g -i 64m

  1. Verwenden Sie den Memurai-Client unter Windows, um Befehle an Garnet zu senden. Eine Anleitung zur Installation von Memurai unter Windows finden Sie hier.

  2. Wenn Sie Linux verwenden, können Sie das redis-cli-Tool verwenden. Unsere offiziell unterstützte Linux-Distribution ist Ubuntu.

  3. Eine dritte Option ist die Installation von Redis-Insight unter Windows. Befolgen Sie die offizielle Anleitung hier.

Fehlerbehebung​

  1. Wenn Sie TLS unter Linux verwenden müssen, folgen Sie der Anleitung unter

    <root>/Garnet/test/testcerts/README.md

  2. Wenn Sie die lokale Gerätebibliothek ausführen müssen, stellen Sie sicher, dass Sie diese Abhängigkeiten haben

    sudo apt install -y g++ libaio-dev uuid-dev libtbb-dev

Garnet API-Entwicklung​

Code-Muster​

Alle Anfragen an den Server sind entweder einfache RESP-Befehle oder RESP-Array-Befehle. Das Folgende zeigt ein Beispiel für jeden von ihnen

Einfacher Befehl: PING RESP-Darstellung

$4\r\nPING\r\n

Array-Befehl: SET mykey abc

RESP-Darstellung

*3\r\n$3\r\nSET\r\n$5\r\nmykey\r\n$7\r\nabcdefg\r\n

Entwicklungskonzepte​

  • Verständnis der Speichertypen in C#: Managed Heap, Stack-Speicher, Unmanaged Memory usw.

  • Verwendung von Span und SpanByte

    Tsavorite und Garnet verlassen sich stark auf diese beiden Typen für die Zuweisung von Daten im Speicher und deren anschließende Übertragung über die Netzwerkschicht. Verständnis und Vertrautheit mit beiden werden sehr hilfreich für ein besseres Verständnis des Codes im Allgemeinen sein.

Pull-Request-Protokoll​

Jede neue Funktion, jede Änderung bestehender Funktionalität oder jeder Fehlerbehebungsbedarf muss nach folgendem Prozess durchgeführt werden

  1. Erstellen Sie ein Issue-Element im Garnet-Projekt, verwenden Sie die folgenden Kriterien: Enhancement für neue Funktionen, Bug für Korrekturen, Task für kleine Verbesserungen oder Änderungen.

  2. Es ist eine gute Praxis, Ihren eigenen lokalen Branch mit der folgenden Namenskonvention zu erstellen

    <username>/branch-name

  3. Fügen Sie Unit-Tests hinzu, um die neuen Befehle oder Funktionen zu testen.

  4. Sobald es zur Überprüfung bereit ist, erstellen Sie einen Pull Request. Stellen Sie sicher, dass Sie ihn mit Ihrem Issue-Element im Entwicklungsbereich verknüpfen.

Formatierungsstil-Leitfaden​

  • Kommentare sind ein wichtiger Bestandteil der Dokumentation. Stellen Sie sicher, dass Ihr Code diese enthält.

  • Das offizielle Format für Kommentare ist

    //<ein Leerzeichen> Kommentar, der mit einem Großbuchstaben beginnt

    Beispiel

    // Dieser Kommentar hat eine gute Formatierung

  • Methoden sollten ihren Summary-Blockkommentar und eine Beschreibung für jeden Parameter haben.

    Beispiel


/// <summary>
/// Iterates the set of keys in the main store.
/// </summary>
/// <param name="patternB">The pattern to apply for filtering</param>
/// <param name="allKeys">When true the filter is omitted</param>
/// <param name="cursor">The value of the cursor in the command request</param>
/// <param name="storeCursor">Value of the cursor returned</param>
/// <param name="Keys">The list of keys from the stores</param>
/// <param name="count">The size of the batch of keys</param>
/// <param name="type">Type of key to filter out</param>
/// <returns></returns>
public bool DbScan(ArgSlice patternB, bool allKeys, long cursor, out long storeCursor, out List<byte[]> Keys,  long count = 10, Span<byte> type = default);
  • Als gute Praxis folgen Sie der Camel-Case-Namenskonvention von C#.

Struktur der Visual Studio Solution-Datei Garnet.sln​

  • Details finden Sie auf der Seite Code Structure hier.

Ausführen der Benchmark-Anwendung​

  • Details finden Sie auf der Seite Resp Benchmark hier.

Build​

Test​

Als sanity check können Sie die Garnet-Testsuite ausführen. Der Befehl zum Ausführen von Tests im Release-Modus für .NET 8 ist unten gezeigt (stellen Sie sicher, dass Sie sich im Stammordner des Repos befinden).

    dotnet test -c Release -f net8.0 -l "console;verbosity=detailed"

Beachten Sie, dass Tsavorite seine eigene Solution-Datei und Testsuite im Ordner <root>/Garnet/libs/storage/Tsavorite hat.

Tipp: Standardmäßig lauscht Garnet auf TCP-Port 6379. Sie können diese Information verwenden, um Ihre Firewall-Einstellungen anzupassen, wenn Sie von Remote-Maschinen auf Garnet zugreifen müssen.