Category

1 Einleitung

gRPC bedeutet Google Remote Procedure Call, wurde entwickelt durch Google in 2015 und freigegeben in August 2016. gRPC läuft ausschliesslich HTTP/2 und verwendet Protocol Buffers als Schnittstellebeschreibungssprache.

Quelle: Pluragsight ‘Using gRPC in ASP.NET Core’ von Shawn Wildermuth.

gRPC ist kein Ersatz für REST weil gRPC nicht geeignet ist für Webseiten:

• gRPC funktioniert nur mit HTTP/2, nicht alle Browser supporten HTTP/2
• Das Format ist binär und schwierig zu Parsen durch JavaScript
• gRPC verlangt Verträge und WEB Apps sind nicht optimiert dafür

REST ist optimal für CRUD Operationen und pure WEB Apps.
SignalR is gut für Multicasting und ‘Soft’ Echtzeit-Kommunikation.
GraphQL ist optimal für das offene Durchsuchen von grossen Datenmengen.
gRPC ist ideal zur Kommunikation zwischen Services auf den Servern.

gRPC:

• Ist optimiert für Geschwindigkeit und Grösse.
• Läuft immer über eine gesicherte Verbindung (HTTPS TLS).
• Unterstützt uni- und bidirektionales Streaming.
• Ist ideal für low Resource Clients (IoT), Microservices.
• Ist gut in Queueing und Messaging.
• Unterstützt kein Multicasting (=> SignalR).
• Nicht einfach lesbar durch Menschen.

Es ist sehr aufwändig gRPC in Blazor-WebAssembly Anwendungen zu nutzen (mit Blazor-Serverside geht das ohne Probleme). Browser geben im Moment keinen Zugang auf HTTP/2 Framing oder http Response Headers.

1.1 gRPC vs.REST

Parameter	gRPC	REST
Serialisierung	protobuf	JSON/XML
Protocol	HTTP/2.0	HTTP/1.1
Browser Support	No	Yes
Data Exchange	Messages	Resources and Verbs
Request-Response Model	Supports all Types of Streaming as based on Http/2	Only supports Request Response as based on Http/1.1
Payload Exchange Format	Strong Typing	Serialization JSON/XML

Quelle: https://www.c-sharpcorner.com/article/grpc-using-c-sharp-and-net-core-day-one/

1.2 gRPC vs. WCF

gRPC	WCF
Service in ProtoFile	ServiceContract
RPC Method in ProtoFile	OperationContract
Message in ProtoFile	DataContract
Richer error Model	FaultContract
Unary Streaming	Request-Reply
Bidirectional Streaming	Duplex
Protobuf IDL	WSDL

Quelle: https://www.c-sharpcorner.com/article/grpc-using-c-sharp-and-net-core-day-one/

1.3 Und was ist mit gRPC-Web?

Die Lösung für gRPC und Web scheint gRPC-Web zu sein welches in 2018 zum ersten Mal erschien (vom gRPC-Team). gRPC-Web besteht aus zwei Teilen: einem JavaScript-Client, der alle modernen Browser unterstützt und einem gRPC-Web-Proxy auf dem Server. Der gRPC-Web-Client ruft den Proxy auf und der Proxy leitet die gRPC-Anforderungen an den gRPC-Server weiter.
Nicht alle Funktionen von gRPC werden von gRPC-Web unterstützt. Client- und bidirektionales Streaming werden nicht und das Server-Streaming nur eingeschränkt unterstützt.

2  Vertragsdefinition in gRPC

Die Verträge werden mit Protocol Buffers definiert. Eine Methode hat keinen Parameter (google.protobuf.Empty) oder einen Parameter vom Typ ‘message’ und keinen oder einen Rückgabewert (ebenfalls Typ ‘message’). Die Definition vom Service ‘AddressBookService’ in einer proto-Datei könnte so aussehen:

syntax = "proto3";
import "enums.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";
option csharp_namespace = "Addressbook.Services";

service AddressBookService {
    rpc AddPersons (AddressBookMessage) returns (TransferStatusMessage);
    rpc GetAddressBook (google.protobuf.Empty) returns (AddressBookMessage);
    rpc UploadPersonImage (stream PersonImageMessage) returns (TransferStatusMessage);
    rpc DownloadPersonImage (PersonMessage) returns (stream PersonImageMessage);
}

message TransferStatusMessage {
    string message = 1;
    TransferStatus status = 2;
}
…

2.1  Die vier Wege von gRPC

Es gibt vier Typen von Serveraufrufen in RPC:

1. Unary RPC
2. Server Streaming RPC
3. Client Streaming RPC
4. Bidirectional Streaming RPC

 

2.1.1        Unary RPC

Einfache Serveraufrufe mit keinem oder einem message-Parameter und keiner oder einer Rückgabe-message.

rpc GetMovie(QueryParams) returns (Movie){};

2.1.2  Server Streaming RPC

Der Client macht einen Serveraufruf mit keinem oder einem message-Parameter und der Server gibt einen offenen Stream zurück. Der Stream kann jetzt verwendet werden für:

• Echtzeit-Transfer (einzelne kleine Objekte ‘abfeuern’).
• Server-zu-Client Benachrichtigungen (Stream offenhalten)
• Chunking, das bedeutet eine grosse Datei zerhacken und in Stücken zu versenden. gRPC garantiert Integrität und Reihenfolge der Daten.

rpc GetMovie(QueryParams) returns (stream Data){};

2.1.3  Client Streaming RPC

Wird verwendet zum Upload grosser Dateien zum Server.

rpc Upload(Stream Data) returns (Status){};

Der Client sendet einen Stream zum Server und wartet, bis der Server antwortet.

2.1.4  Bidirectional Streaming RPC

Streaming bedeutet nicht immer grosse Dateien. Das bidirektionale Streaming kann z.B. verwendet werden, um IsAlive Signale zwischen Client und Server auszutauschen, um zu kontrollieren, ob beide noch ‘gesund’ sind.

rpc CheckConnection(Stream Ping) returns (Pong){};

3  gRPC und ASP.NET Core

gRPC ist Teil vom ASP.NET Core 3.1 Framework. Im folgenden wird eine Beispielanwendung erstellt. Den Quellcode kann man hier herunterladen.

3.1 PC Einrichten

Es braucht Visual Studio 2019. Visual Studio Community, Professional und Enterprise funktionieren alle. Einfach .NET Core 3.1 herunterladen (nicht .NET Framework 4.8).

3.2 Server Projekt erstellen

• Erstelle ein neues Projekt «ASP.NET Core Web Application»
• Nenne es ‘Addressbook’
• Wähle API aus mit ‘Configure for HTTPS’ aber ohne ‘Authentication’

3.3  Integrieren von Protocol Buffers (Protobuf)

3.3.1  Verträge erstellen

• Erstelle ein Unterverzeichnis \Protos
• New item -> Protocol Buffer File -> enums.proto
• Füge die Option “csharp_namespace to “Addressbook.Services” hinzu (dadurch wird der Tag ‘Package’ in C# nicht generiert)

Beispiel von enums.proto

syntax = "proto3";
option csharp_namespace = "Addressbook.Services";

enum PhoneType {
  PHONETYPE_UNSPECIFIED = 0;
  PHONETYPE_MOBILE = 1;
  PHONETYPE_HOME = 2;
  PHONETYPE_WORK = 3;
}

enum Gender {
  GENDER_UNSPECIFIED = 0;
  GENDER_MALE = 1;
  GENDER_FEMALE = 2;
}

enum ReadingStatus{
  READINGSTATUS_UNSPECIFIED = 0;
  READINGSTATUS_SUCCESS = 1;
  READINGSTATUS_FAILURE = 2;
  READINGSTATUS_INVALID = 3;
}

• New item -> Protocol Buffer File -> addressbook.proto

Beispiel von addressbook.proto

syntax = "proto3";
import "Protos/enums.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";
option csharp_namespace = "Addressbook.Services";

service AddressBookService {
    rpc AddPersons (AddressBookMessage) returns (StatusMessage);
    rpc GetAddressBook (google.protobuf.Empty) returns (AddressBookMessage);
}

message StatusMessage {
    string message = 1;
    ReadingStatus status = 2;
}

message Person {
  string name = 1;
  int32 age = 2;
  string email = 3;
  Gender gender = 4;
  message PhoneNumber {
    string number = 1;
    PhoneType phoneType = 2;
  }
  repeated PhoneNumber phone_numbers = 5;
  google.protobuf.Timestamp last_updated = 6;
}

message AddressBook {
  repeated Person people = 1;
}

message AddressBookMessage {
  AddressBook addressBook = 1;
  StatusMessage statusMessage = 2;
}

• Hinzufügen NuGet Paket Grpc.AspNetCore (v2.25.0)
• Jetzt kann man die Build Action von beiden proto-Dateien auf ‘Protobuf compiler’ setzen.

Wenn man jetzt kompiliert werden zwei *.cs-Dateien generiert, die sich in ‘obj\Debug\netcoreapp3.1‘ befinden. Die Dateien sind im Solution Explorer nur sichtbar, wenn man ‘Show all files’ aktiviert.

3.3.2  Service implementieren

• Unterverzeichnis ‘Services’ erstellen
• Neue Klasse ‘AddressbookService’ erstellen, welche von AddressbookService.AddressbookServiceBase ableitet. Diese Klasse ist generiert aus den proto-Dateien.
• Implementiere jetzt die generierten Methoden durch ‘override’  (siehe unten).
• Interessant ist, dass parameterlose Methoden den Parameter ‘Empty’ haben.

namespace Addressbook.Services
{
    public class AddressbookService : AddressBookService.AddressBookServiceBase
    {
        private readonly ILogger<AddressbookService> _logger;

        public AddressbookService(ILogger<AddressbookService> logger)
        {
            _logger = logger;
        }

        public override Task<StatusMessage> AddPersons(AddressBookMessage request, ServerCallContext context)
        {
            StatusMessage result = new StatusMessage { Status = ReadingStatus.Failure };
            try
            {
                foreach (var p in request.AddressBook.Persons)
                {
                    // Todo: create person EF and add to repo
                }
                // Todo: save all changes to repo
                result.Status = ReadingStatus.Success;
            }
            catch (Exception ex)
            {
                result.Message = "Message thrown during processing.";
                _logger.LogError($"Message thrown during processing ({ex}).");
            }
            return Task.FromResult(result);
        }

        public override Task<AddressBookMessage> GetAddressBook(Empty request, ServerCallContext context)
        {
            AddressBookMessage result = new AddressBookMessage();
            result.StatusMessage = new StatusMessage() { Status = ReadingStatus.Success };
            result.AddressBook = new AddressBook();
            // Todo: read from repo
            result.AddressBook.Persons.Add(new Person()
            {
                Name = "Erik Stroeken", 
                Gender = Gender.Male, 
                Age = 50, 
                Email = "erik@stroeken.ch",
                PhoneNumbers =
                {
                    new Person.Types.PhoneNumber {Number = "00 41 76 444 00 87", PhoneType = PhoneType.Mobile},
                    new Person.Types.PhoneNumber {Number = "00 41 44 444 83 16", PhoneType = PhoneType.Home},
                    new Person.Types.PhoneNumber {Number = "00 41 41 444 66 45", PhoneType = PhoneType.Work}
                },
                LastUpdated = Timestamp.FromDateTime(DateTime.UtcNow)
            });
            return Task.FromResult(result);
        }
    }
}

 

3.3.3        Den Service verdrahten

• In Startup.cs unter ConfigureService() AddGrpc(opt => { opt.EnableDetailedErrors = true; }); hinzufügen
• In der Methode Configure() MapGrpcService<AddressBookService>(); in app.UseEndpoints() hinzufügen.

Startup.cs

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddGrpc(opt => { opt.EnableDetailedErrors = true; });
}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseHttpsRedirection();
    app.UseRouting();
    app.UseAuthorization();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapGrpcService<AddressBookService>();
        endpoints.MapControllers();
    });
}

• Man muss im Moment noch den Kestrel Server verwenden, weil IIS Express kein HTTP/2 unterstützt.

Hier ist die Log-Information wenn der Server gestartet wird:

3.4  Erstellen des gRPC Clients

• Ein weiteres Projekt vom Type «.NET Core Worker Service» hinzufügen.

• Dem Client Projekt eine Service Referenz hinzufügen:

• Wähle jetzt die addressbook.proto-Datei aus und setze den Type auf Client.

• Selektiere die enums.proto-Datei aber setzte den Typ zu «Messages only».

Der Client importiert die proto-Dateien als Referenzen in das Projekt. Die import-Anweisung in der Protodatei ist relativ und bezieht sich jetzt auf das Client-Projekt, in dem die Datei enums.proto nicht vorhanden ist.

Hack

• Entferne “Protos/” from import Tag

syntax = "proto3";
import "enums.proto";

• Öffne die Projektdatei vom Server und füge die Attribute ProtoRoot mit «Protos\» hinzu:

<ItemGroup>
    <Protobuf Include="Protos\addressBook.proto" ProtoRoot="Protos\" />
    <Protobuf Include="Protos\enums.proto" ProtoRoot="Protos\" />
</ItemGroup>

3.5  Implementiere den Client

Füge die folgende Sektion zu der appsettings.json-Datei hinzu:

{
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    },
    "Service": {
        "CustomerId": 1,
        "DelayInterval": 3000,
        "ServiceUrl" :  "https://localhost:5001"
    }
}

Hier ist der Code vom Worker:

public class Worker : BackgroundService
{
    private readonly ILogger<Worker> _logger;
    private readonly IConfiguration _config;
    private AddressBookService.AddressBookServiceClient _client = null;

    public Worker(ILogger<Worker> logger, IConfiguration config)
    {
        _logger = logger;
        _config = config;
    }

    protected AddressBookService.AddressBookServiceClient Client
    {
        get
        {
            if (_client == null)
            {
                ChannelBase channel = GrpcChannel.ForAddress(_config["Service:ServiceUrl"]);
                _client = new AddressBookService.AddressBookServiceClient(channel);
            }
            return _client;
        }
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
       AddressBook addressBook = new AddressBook();
       addressBook.Persons.Add(
           new Person()
           {
               Name = "Jan Muster",
               Gender = Gender.Male,
               Age = 50,
               Email = "jan.muster@firma.ch",
               PhoneNumbers =
               {
                   new Person.Types.PhoneNumber {Number = "00 41 76 444 00 87", 
                                                 PhoneType = PhoneType.Mobile},
                   new Person.Types.PhoneNumber {Number = "00 41 44 555 83 16", 
                                                 PhoneType = PhoneType.Home},
                   new Person.Types.PhoneNumber {Number = "00 41 41 666 66 45", 
                                                 PhoneType = PhoneType.Work}
               },
               LastUpdated = Timestamp.FromDateTime(DateTime.UtcNow)
           });
       AddressBookMessage msg = new AddressBookMessage
       {
           AddressBook = addressBook
       };
       var status = Client.AddPersons(msg);
       while (!stoppingToken.IsCancellationRequested)
       {
                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                var result = await Client.GetAddressBookAsync(new Empty());
                await Task.Delay(_config.GetValue("Service:DelayInterval"), stoppingToken);
            }    
      }
}

 

Starte erst den Server und dann den Client. Die Log-Traces sehen ungefähr so aus (rechts ist Client):

4.  Fazit

Dieser Blogbeitrag gibt eine Übersicht über die Vor- und Nachteile von gRPC und eine Einführung mit einer einfachen Implementierung. In der nächsten Folge wird Server und Client Streaming erklärt mit einem einfachem Beispiel, in welchem ein Bild hoch- und runtergeladen wird.

Nächster Post →

1.  Einleitung

Protocol Buffers (Protobuf) ist eine Methode zur Serialisierung strukturierter Daten. Protobuf umfasst eine Schnittstellenbeschreibungssprache, um die Strukturen der Daten zu definieren und Compiler zur Generierung der Strukturen und (De-)Serialisierung. Es gibt mittlerweile Protobuf Compiler für C#, C, C++, Go, Objective-C, Java, Python, Swift und Ruby.

Google hat Protobuf ursprünglich für die interne Verwendung entwickelt und im Juli 2008 veröffentlicht. Es gibt mittlerweile drei Versionen, die nicht miteinander kompatible sind: Google intern (<2008), proto2 und proto3.

Die Entwurfsziele für Protobuf sind Einfachheit und Leistung. Protobuf wurde so konzipiert, dass es kleiner und schneller ist als XML und JSON. XML und JSON sind nicht für den Datenaustausch zwischen zwei verschiedenen Plattformen optimiert.

Protocol Buffers bietet viele Vorteile:

• Sprach- und plattformneutral
• Einfachheit
• Effizient: optimiert für Bandbreite (bis zu 10-mal kleiner)
• Schnell: optimiert für schnelle (De-) Serialisierung (20- bis 100-mal schneller)
• Eindeutige Versionierung der Strukturen
• Erzeugt Stubs die aus einfachen Klassen bestehen (POCO)

Protobuf wird in gRPC verwendet.

2.  Wie es funktioniert…

Warum ist Protobuf so schnell und kompakt?

1. Kontext ist getrennt von den Daten
2. Binäres Transportformat (statt Text wie bei XML und JSON)

 

2.1  Kontext getrennt von den Daten

In XML und JSON enthält jeder Eintrag den Kontext und die Daten.
Beispiel XML:

<Person>
  <FirstName>Peter</FirstName>
  <LastName>Muster</LastName>
</Person>

Beispiel JSON:

{
  “firstName”: “Peter”,
  “lastName”: “Muster”
}

Bei Protobuf werden die Datenstrukturen (‘message’) in einer Konfigurationsdatei definiert (*.proto). Der Kontext ist in den Datenstrukturen definiert:

Message Person{ 
  String first_name = 1; 
  String last_name = 2; 
}

Aus dieser Datei werden durch den Compiler die dazugehörigen Klassen generiert und die Methoden zur Serialisierung und Deserialisierung.

2.2  Binäres Transportformat

Eine detaillierte Beschreibung der binären Kodierung würde den Ramen dieses Blogs sprengen, dazu wird zur originalen Quelle verwiesen: https://developers.google.com/protocol-buffers/docs/encoding.

Jedes Feld hat folgendes Format:

{field_number << 3 | field_type} + {length of data} + {data}

Nehmen wir als Beispiel die minimale Struktur Person:

message Person{
  string name = 1; 
}

Es gibt eine Instanz mit folgendem Inhalt:

person.name = “Erik Stroeken”

Die binäre Darstellung für ‘name’ sieht dann so aus:

0a 0d 45 72 69 6b 20 53 74 72 6f 65 65 6e => {10} + {13} + {Erik Stroeken}

Die Felder werden wie folgt interpretiert:

3.  Protobuf Messages

Die Strukturen der Protobuf Messages werden in einer separaten Textdatei (*.proto) definiert und dann in die Sprache kompiliert, in der die Nachrichten verwendet werden.
Die Namen der Messages sollten CamelCase sein (z.B. ‘message SongServerRequest’).
Jede Nachricht hat vier Felder:

1. Rule
2. Type
3. Name
4. Tag

In der ‘proto2’ Version von Protobuf war es noch möglich Standardwerte für jedes Feld zu definieren. Das geht nicht mehr in ‘proto3’: der default Wert ist der Standardwert vom Typ (0 oder string.Empty).

3.1  Message Feld ‘Rule’

message Customer {
int32 id = 1;
string username = 2;
repeated google.protobuf.Any details = 3;
}

Für Rule gibt es nur zwei Möglichkeiten:

• {keine} – wird als optional interpretiert.
• repeated – Array von Elementen mit dem gleichen Typ

Bei wiederholten Feldern (z.B.’repeated string keys = 1′) werden am besten pluralisierte Namen verwenden.
‘repeated’ Felder sind read-only. Man kann Elemente hinzufügen oder löschen, aber nicht die ganze Kollektion ersetzen.
Der Protobuf-Compiler für C# übersetzt ‘repeated’ in den Typ RepeatedField<T>. Dieser Typ ist wie List<T> mit ein paar extra Methoden wie Add() ausgestattet, welche eine Sammlung entgegennimmt zur Verwendung in Collection-Initialisatoren.

3.2  Message Feld ‘Type’

message Customer {
int32 id = 1;
string username = 2;
repeated google.protobuf.Any details = 3;
}

Es gibt folgende Typen in Protobuf:

1. Scalar Typ
2. Enumeration
3. Message Typ
4. Typ ‘one of’
5. Typ ‘map’
6. Typ ‘Any’

 

3.2.1  Scalar Typ

Mögliche Werte:

• string
• bool
• bytes
• float
• double
• int32, int64, uint32, uint64, (sint32, sint64, fixed32, fixed64, sfixed32, sfixed64)

Die Typen mit den Präfixen ‘s’ oder ‘sfixed’ sind nur Varianten zur Optimierung.

3.2.2  Enumerator

Enumeratortypnamen sind alle CamelCase, Enumeratorwertnamen sind alle UPPER_CASE. Der nach 0 benannte Enumeratorwert sollte mit nnn_UNDEFINED = 0; enden. Ein Enumerator kann innerhalb einer anderen Message definiert werden. Der Scope ist dann nur die Message.

message Customer {
  enum CustomerType{
    UNDEFINED = 0;
    REGULAR = 1;
    MEMBER = 2;
    SPONSOR =3;
  }
  CustomerType customer_type = 1
}

Google-Richtlinien bevorzugen globale Aufzählungstypen mit dem Typ Namen als Präfix in jedem Wertefeld.

enum PhoneType {
  PHONETYPE_UNDEFINED = 0;
  PHONETYPE_MOBILE = 1;
  PHONETYPE_HOME = 2;
  PHONETYPE_WORK = 3;
}

enum Gender {
  GENDER_UNDEFINED = 0;
  GENDER_MALE = 1;
  GENDER_FEMALE = 2;
}

Der Protobuf-Compiler für C # generiert die folgenden C # enum Typen:

public enum PhoneType {
  [pbr::OriginalName("PHONETYPE_UNDEFINED")] Undefined = 0,
  [pbr::OriginalName("PHONETYPE_MOBILE")] Mobile = 1,
  [pbr::OriginalName("PHONETYPE_HOME")] Home = 2,
  [pbr::OriginalName("PHONETYPE_WORK")] Work = 3,
}

public enum Gender {
  [pbr::OriginalName("GENDER_UNDEFINED")] Undefined = 0,
  [pbr::OriginalName("GENDER_MALE")] Male = 1,
  [pbr::OriginalName("GENDER_FEMALE")] Female = 2,
}

3.3.3  Message Typ

Diese Felder definieren verschachtelte Messages mit dem Scope des Eltern Message.

message Customer {
 message Address {
    …
 }
 Repeated Address addresses = 1
}

3.3.4  Type ‘one of’

‘one of’ ist wie ‘union’ in Sprachen wie Pascal, in denen nur ein Feld einen Wert haben kann. ‘one of’ wird aus Gründen der Effizienz eingesetzt:

• Nur ein Feld kann einen Wert enthalten
• Wenn Sie ein Feld festlegen, werden alle anderen Felder gelöscht
• Effizientere Speichernutzung (wenn möglich)

message Customer {
  one of access_type  {
    string email = 1;
    string username = 2;
  }
}

3.3.5  Type ‘map’

‘map’ ist ein einfaches Dictionary mit int oder string Typen.

message Customer {
 map<string, string> email_addresses = 1;
}

3.3.6  Type ‘Any’

‘Any’ verhält sich wie Variant in Basic oder var in C#.

message Customer {
  int32 id = 1;
  string username = 2;
  repeated google.protobuf.Any details = 3;
}

3.4  Feld ‘Name’

message Customer {
int32 id = 1;
string username = 2;
google.protobuf.Any repeated details = 3;
}

Es gelten folgende Namenskonventionen:

• Alles Kleinbuchstaben (z. B. “access_type”)
• Verwende einen Unterstrich als Trennzeichen

Feldnamen werden für jede Sprache im richtigen Stil kompiliert.

3.5  Feld ‘Tag’

message Customer {
int32 id = 1;
string username = 2;
google.protobuf.Any repeated details = 3;
}

Numerische Platzhalter des Feldes:

• • Muss innerhalb einer Nachricht eindeutig sein.
  • Muss eine Ganzzahl sein
  • Anfangen mit 1
  • Muss ein Integer sein
  • Reservierte Nummer 19000 .. 19999 (internen Gebrauch) nicht verwenden

• Die Nummer sollten so klein wie möglich sein.
• Keine Nummer verwenden von zuvor gelöschten Feldern (siehe Versionsverwaltung).

3.6  GUID ist nicht unterstützt

Implementieren als string oder wie beschrieben in https://github.com/protocolbuffers/protobuf/issues/2224.

3.7  Grosse Inhalte (z.B. Bilder, Dateien)

Grosse Inhalte bis 1 kB kann man als byte Array definieren. Grössere Inhalte sollten gestreamed werden (‘chuncking’). Streaming wird in gRPC in beide Richtungen unterstützt. In der unteren Message wird ‘imageChunk’ gestreamed.

message PersonImageMessage
{
  int32 personId = 1;
  ImageType imageType = 2;
  bytes imageChunk = 3;
}

4.  Die ‘proto’-Datei

Proto-Dateien werden am Besten in einem Verzeichnis ‘Protos’ gespeichert. Enumeratoren werden gemäss Richtlinien von Google global definiert und sind im Beispiel unten ausgelagert in der Datei ‘enums.proto’.

Die Datei ‘enums.proto’:

syntax = "proto3";
option csharp_namespace = "Addressbook.Services";

enum Gender {
  GENDER_UNDEFINED = 0;
  GENDER_MALE = 1;
  GENDER_FEMALE = 2;
}

enum PhoneType {
	PHONETYPE_UNDEFINED = 0;
	PHONETYPE_MOBILE = 1;
	PHONETYPE_HOME = 2;
	PHONETYPE_WORK = 3;
}

Die ‘option csharp_namespace’ definiert den Namensraum für die generierten Klassen. Es ersetzt das mehr generische ‘package package_name’.

Hier ist der Inhalt für ‘addressBook.proto’:

syntax = "proto3";
import "enums.proto";
import "google/protobuf/timestamp.proto";
option csharp_namespace = "Addressbook.Services";

message Person {
  int32 id = 1;
  string name = 2;
  int32 age = 3;
  string email = 4;
  Gender gender = 5;
  message PhoneNumber {
    string number = 1;
    PhoneType phoneType = 2;
  }
  repeated PhoneNumber phone_numbers = 6;
  google.protobuf.Timestamp last_updated = 7;
}

message AddressBook {
  repeated Person persons = 1;
}

message AddressBookMessage {
  AddressBook addressBook = 1;
}

Mit ‘import’ werden andere Proto-Dateien importiert.

4.  Versionierung

4.1  Reservierte Tags

Im unteren Beispiel wird das Feld ‘name’ aufgeteilt in ‘first_name’ und ‘last_name’. Danach wird ein neues Feld ‘email’ hinzugefügt mit dem Tag 2. Wenn sich jetzt ein neuer Client mit einem alten Server verbindet, wird das Feld ‘email’ mit dem Inhalt vom Feld ‘name’ abgefüllt.

Nach der Revision soll das Schlüsselwort ‘reserved’ verwendet werden, um dem Entwickler und Compiler mitzuteilen, dass 2 nicht mehr verwendet werden darf.

Gültige Definitionen:

• reserved 1;
• reserved 1,2 ,3;
• reserved 5 to 10;
• reserved 1,2,3,5 to 10;

4.2  Reservierte Felder

Gleicher UseCase wie oben, aber jetzt wird der Namen wiederverwendet.

Aus der Protobuf-Sicht gibt es kein Problem, aber wenn der Inhalt zu JSON serialisiert wird, wird ein Konflikt entstehen wenn ein neuer Client sich mit einem alten Server verbindet.

Gültige Definitionen:

• reserved «field_name»;
• reserved «field_name», «other_name»

5. Kompilieren

Es gibt zwei Wege um die proto-Datei zu kompilieren:

1. Über Visual Studio 2019
2. Manuell mit dem Tool von Google

 

5.1 Visual Studio 2019

Ab .NET Core 3.0 ist gRPC und Protobuf integriert. Die Kompilierung der proto-Dateien geschieht daher automatisch bei jeder Build-Aktion.

1. Installiere Visual Studio 2019 Community, Professional oder Ultimate.
2. Installiere .NET Core 3.1 (nicht .NET Framework 4.8).
3. Kreiere die proto-Dateien im Projekt wie oben beschrieben.
4. Installiere NuGet Package ‘Grpc.AspNetCore (v2.25.0)’.
5. Selektiere die proto-Dateien und setzt die Build Aktion auf ‘Protobuf compiler’.

Nach dem Kompilieren befinden sich die cs-Dateien in ‘object\Debug\netcoreapp3.0\’:

5.2 Manuell Kompilieren (nicht empfohlen)

Installiere NuGet Paketen ‘Google.Protobuf’ und ‘Google.Protobuf.Tools’.

Die NuGet-Pakete warden hier installiert:

C:\Users\[User]\.nuget\packages\google.protobuf\3.10.1
C:\Users\[User]\.nuget\packages\google.protobuf.tools\3.10.1

Entweder setzte die Path Variable zu:

C:\Users\[User]\.nuget\packages\google.protobuf.tools\3.10.1\tools\windows_x64

Oder kopiere ‘protoc.exe’ und das Unterverzeichnis ‘google’ in die Solution:

C:\Users\[User]\.nuget\packages\google.protobuf.tools\3.10.1\tools\windows_x64\protoc.exe
C:\Users\[User]\.nuget\packages\google.protobuf.tools\3.10.1\tools\windows_x64\google

Führe dann folgender Befehl aus (achtung: –csharp hat zwei ‘-‘ Zeichen):

protoc –csharp_out=ProtocolBuffers ProtocolBuffers\addressbook.proto

6.  (De-)Serialisierung

Die generierte Klasse ‘Person’ kann jetzt instanziiert und abgefüllt werden.

Person person = new Person
{
    Name = "Jan Muster",
    Age = 50,
    Gender = Gender.Male,
    Email = "jan.muster@noser.com",
    PhoneNumbers =
    {
        new PhoneNumber {Number = "00 41 76 417 12 87", PhoneType = PhoneType.Mobile},
        new PhoneNumber {Number = "00 41 44 741 22 16", PhoneType = PhoneType.Home},
        new PhoneNumber {Number = "00 41 41 455 45 45", PhoneType = PhoneType.Work}
    }
};

Zur Serialisierung und Deserialisierung gib es statische und extension Methoden.

6.1  (De-)Serialization von\zu byte array

// Serializing person to byte array and back.
byte[] personByteArray = person.ToByteArray();
Person personFromByteArray = Person.Parser.ParseFrom(personByteArray);

6.2  (De-)Serialization von\zu file

// Writing person to disk and reading it again.
using (FileStream output = File.Create("person.dat"))
{
    person.WriteTo(output);
}
using (FileStream input = File.OpenRead("person.dat"))
{
    Person personToDisk = Person.Parser.ParseFrom(input);
}

6.3  (De-)Serialization von\zu JSON

// Serializing person to JSON and back.
string jsonMessage = Google.Protobuf.JsonFormatter.Default.Format((IMessage)person);
IMessage message = (IMessage)Activator.CreateInstance(typeof(Person));
Person personFromJSON = (Person)Google.Protobuf.JsonParser.Default.Parse(jsonMessage,
 message.Descriptor);

6.4  (De-)Serialization von\zu XML

Macht keinen Sinn und gibt es auch nicht.

Fazit

Protobuf ist schnell zu lernen und dank der Integration in Visual Studio 2019 einfach anzuwenden. Protocol Buffer ist die Technologie, die verwendet wird für die Serialisierung und Deserialisierung von DTOs in gRPC. In den nächsten Blogs wird gRPC und ASP.NET Core ausführlich erklärt.