Protocol Buffers

suggest change

Protocol Buffers (protobuf) is Google's format for serializing structured data. You describe your messages in a .proto file, a code generator turns it into C# classes, and those classes read and write a compact binary format. It's the payload format of gRPC and a common choice for storage and messaging between services written in different languages.

Compared to JSON, protobuf gives you:

The downside is that the binary data isn't human readable and you need the schema to make sense of it.

In .NET the official runtime is the Google.Protobuf NuGet package. Code is generated by protoc, which the Grpc.Tools package runs automatically during the build. Examples use C# 14 / .NET 10, Google.Protobuf 3.36 and Grpc.Tools 2.84.

Setting up a project

Create a console project and add both packages:

dotnet new console -n Contacts
cd Contacts
dotnet add package Google.Protobuf
dotnet add package Grpc.Tools

Then tell MSBuild which .proto files to compile. GrpcServices="None" means "generate only message classes". Use Server, Client or Both if the file also defines gRPC services.

<ItemGroup>
  <PackageReference Include="Google.Protobuf" Version="3.36.2" />
  <PackageReference Include="Grpc.Tools" Version="2.84.0">
    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    <PrivateAssets>all</PrivateAssets>
  </PackageReference>
</ItemGroup>

<ItemGroup>
  <Protobuf Include="Protos\*.proto" GrpcServices="None" />
</ItemGroup>

Grpc.Tools is only needed at build time (hence PrivateAssets="all"). The generated .cs files go to obj/ and are regenerated whenever a .proto file changes, so you never edit or commit them. If you'd rather run the compiler yourself, install protoc and run protoc --csharp_out=Generated Protos/person.proto.

Defining messages

Here is Protos/person.proto, which is used throughout this article:

syntax = "proto3";

package contacts;

option csharp_namespace = "Contacts";

import "google/protobuf/timestamp.proto";

message Person {
  string name = 1;
  int32 id = 2;
  string email = 3;
  repeated PhoneNumber phones = 4;
  map<string, string> labels = 5;
  google.protobuf.Timestamp last_updated = 6;
  optional int32 age = 7;

  oneof contact {
    string preferred_email = 8;
    PhoneNumber preferred_phone = 9;
  }

  enum PhoneType {
    PHONE_TYPE_UNSPECIFIED = 0;
    PHONE_TYPE_MOBILE = 1;
    PHONE_TYPE_HOME = 2;
    PHONE_TYPE_WORK = 3;
  }

  message PhoneNumber {
    string number = 1;
    PhoneType type = 2;
  }
}

message AddressBook {
  repeated Person people = 1;
}

The number after each field (= 1, = 2) is the field number. It's what actually goes on the wire, so once a message is in use you must never change or reuse a field number. Names can be renamed freely.

The generator maps the schema to C# like this:

proto C#
message Person sealed partial class Person : IMessage<Person>
string name string Name (never null, defaults to "")
int32, int64, bool, double int, long, bool, double
bytes ByteString (immutable)
repeated PhoneNumber phones RepeatedField<PhoneNumber> Phones (get-only)
map<string, string> labels MapField<string, string> Labels (get-only)
nested message / enum Person.Types.PhoneNumber, Person.Types.PhoneType
PHONE_TYPE_MOBILE PhoneType.Mobile (the enum-name prefix is stripped)
optional int32 age int Age, plus HasAge and ClearAge()
oneof contact ContactCase property and ClearContact()

csharp_namespace sets the C# namespace. Without it the namespace is derived from package (Contacts here too, after PascalCasing).

Serializing and parsing

using Contacts;
using Google.Protobuf;

var person = new Person
{
    Id = 1234,
    Name = "Alice Smith",
    Email = "alice@example.com",
};
person.Phones.Add(new Person.Types.PhoneNumber
{
    Number = "555-0100",
    Type = Person.Types.PhoneType.Mobile,
});
person.Labels["team"] = "infra";

byte[] bytes = person.ToByteArray();
Console.WriteLine($"size: {bytes.Length} bytes (CalculateSize: {person.CalculateSize()})");

Person copy = Person.Parser.ParseFrom(bytes);
Console.WriteLine(copy.Name);
Console.WriteLine(copy.Phones[0].Type);
Console.WriteLine(copy.Equals(person));
Console.WriteLine(copy);
size: 64 bytes (CalculateSize: 64)
Alice Smith
Mobile
True
{ "name": "Alice Smith", "id": 1234, "email": "alice@example.com", "phones": [ { "number": "555-0100", "type": "PHONE_TYPE_MOBILE" } ], "labels": { "team": "infra" } }

ToByteArray() is an extension method from the Google.Protobuf namespace. Every generated class has a static Parser with ParseFrom overloads for byte[], ReadOnlySpan<byte>, ByteString and Stream. Generated classes implement value equality (Equals and GetHashCode compare all fields) and ToString() returns the JSON form, which is handy for logging and debugging.

What the bytes look like

Knowing the wire format helps when you read hex dumps and explains some of the design choices:

using Contacts;
using Google.Protobuf;

var p = new Person { Name = "Bo", Id = 150 };
Console.WriteLine(Convert.ToHexString(p.ToByteArray()));

var empty = new Person();
Console.WriteLine($"empty: {empty.CalculateSize()} bytes");

var negative = new Person { Id = -1 };
Console.WriteLine($"id=-1: {negative.CalculateSize()} bytes");
0A02426F109601
empty: 0 bytes
id=-1: 11 bytes

Each field is a tag followed by a value. The tag is (field_number << 3) | wire_type:

Fields with default values (0, "", empty lists) aren't written at all, so an empty message is 0 bytes. Negative int32/int64 values always take 10 bytes as a varint. If a field often holds negative numbers, declare it sint32/sint64 (ZigZag encoding: -1 becomes 1 byte). For values that are usually large, such as hashes or IDs, fixed32/fixed64 always use 4/8 bytes. In C# all of these are still plain int, long, uint or ulong.

Default values and field presence

In proto3 a plain scalar field has no "unset" state. You can't tell "not set" from "set to the default value":

using Contacts;

var p = new Person();
Console.WriteLine($"name: '{p.Name}' (null? {p.Name is null})");
Console.WriteLine($"id: {p.Id}");
Console.WriteLine($"phones: {p.Phones.Count}");
Console.WriteLine($"last_updated: {(p.LastUpdated is null ? "null" : "set")}");

Console.WriteLine($"HasAge: {p.HasAge}, Age: {p.Age}");
p.Age = 0;
Console.WriteLine($"HasAge: {p.HasAge}, Age: {p.Age}");
p.ClearAge();
Console.WriteLine($"HasAge: {p.HasAge}");

try
{
    p.Name = null!;
}
catch (ArgumentNullException e)
{
    Console.WriteLine($"{e.GetType().Name}: {e.ParamName}");
}
name: '' (null? False)
id: 0
phones: 0
last_updated: null
HasAge: False, Age: 0
HasAge: True, Age: 0
HasAge: False
ArgumentNullException: value

The rules:

oneof

A oneof holds at most one of its fields. Setting one clears the others, and a generated enum tells you which one is set:

using Contacts;

var p = new Person { Name = "Carol" };
Console.WriteLine(p.ContactCase);

p.PreferredEmail = "carol@example.com";
Console.WriteLine($"{p.ContactCase}: {p.PreferredEmail}");

p.PreferredPhone = new Person.Types.PhoneNumber { Number = "555-0199" };
Console.WriteLine($"{p.ContactCase}: {p.PreferredPhone.Number}");
Console.WriteLine($"email after setting phone: '{p.PreferredEmail}'");

string description = p.ContactCase switch
{
    Person.ContactOneofCase.PreferredEmail => $"email {p.PreferredEmail}",
    Person.ContactOneofCase.PreferredPhone => $"phone {p.PreferredPhone.Number}",
    Person.ContactOneofCase.None => "no preference",
    _ => "unknown",
};
Console.WriteLine(description);

p.ClearContact();
Console.WriteLine(p.ContactCase);
None
PreferredEmail: carol@example.com
PreferredPhone: 555-0199
email after setting phone: ''
phone 555-0199
None

A switch expression on ContactCase is the idiomatic way to handle a oneof.

Repeated fields, maps, cloning and merging

Because repeated and map properties are get-only, you fill them with Add, an indexer, or a collection initializer inside the object initializer:

using Contacts;

var p = new Person
{
    Name = "Dave",
    Phones =
    {
        new Person.Types.PhoneNumber { Number = "555-0001", Type = Person.Types.PhoneType.Home },
        new Person.Types.PhoneNumber { Number = "555-0002", Type = Person.Types.PhoneType.Work },
    },
    Labels = { ["team"] = "web", ["level"] = "senior" },
};

foreach (var phone in p.Phones.Where(ph => ph.Type == Person.Types.PhoneType.Work))
    Console.WriteLine($"work: {phone.Number}");

p.Labels.Remove("level");
Console.WriteLine(string.Join(", ", p.Labels.Select(kv => $"{kv.Key}={kv.Value}")));

// Clone is a deep copy
Person clone = p.Clone();
clone.Phones[0].Number = "000";
Console.WriteLine($"{p.Phones[0].Number} vs {clone.Phones[0].Number}");

// MergeFrom: scalars that are set overwrite, repeated fields append, maps merge
var update = new Person { Email = "dave@example.com", Labels = { ["team"] = "api" } };
update.Phones.Add(new Person.Types.PhoneNumber { Number = "555-0003" });
p.MergeFrom(update);
Console.WriteLine(p);
work: 555-0002
team=web
555-0001 vs 000
{ "name": "Dave", "email": "dave@example.com", "phones": [ { "number": "555-0001", "type": "PHONE_TYPE_HOME" }, { "number": "555-0002", "type": "PHONE_TYPE_WORK" }, { "number": "555-0003" } ], "labels": { "team": "api" } }

RepeatedField<T> implements IList<T> and MapField<K,V> implements IDictionary<K,V>, so LINQ works on both. Note that MergeFrom can't "clear" a field: a default value in update (like Name = "") is indistinguishable from "not set" and is ignored.

Streams and multiple messages

A protobuf message doesn't record its own length. Parsing reads until the end of the input, so you can't write two messages back to back and read them apart. For a file or socket carrying a sequence of messages, use the length-prefixed helpers WriteDelimitedTo and ParseDelimitedFrom:

using Contacts;
using Google.Protobuf;

string path = Path.Combine(Path.GetTempPath(), "people.bin");

using (var output = File.Create(path))
{
    for (int i = 1; i <= 3; i++)
    {
        var p = new Person { Id = i, Name = $"user{i}" };
        p.WriteDelimitedTo(output);
    }
}
Console.WriteLine($"file size: {new FileInfo(path).Length} bytes");

using (var input = File.OpenRead(path))
{
    while (input.Position < input.Length)
    {
        Person p = Person.Parser.ParseDelimitedFrom(input);
        Console.WriteLine($"{p.Id}: {p.Name}");
    }
}

// A single message per file: WriteTo / ParseFrom(stream)
var book = new AddressBook();
book.People.Add(new Person { Id = 10, Name = "Erin" });
using (var output = File.Create(path))
    book.WriteTo(output);
using (var input = File.OpenRead(path))
    Console.WriteLine(AddressBook.Parser.ParseFrom(input).People[0].Name);
file size: 30 bytes
1: user1
2: user2
3: user3
Erin

WriteDelimitedTo writes the size as a varint, then the message. This is the same framing the Java, Go and Python libraries use, so such files are portable. Alternatively wrap everything in a container message with a repeated field, like AddressBook, but then the whole thing must fit in memory.

See Using Streams and Bytes and binary data for working with streams and byte buffers in general.

JSON

Protobuf defines a canonical JSON mapping, and Google.Protobuf implements it with JsonFormatter and JsonParser. This is useful for debugging, config files, or REST endpoints that share a schema with gRPC:

using Contacts;
using Google.Protobuf;
using Google.Protobuf.WellKnownTypes;

var p = new Person
{
    Id = 7,
    Name = "Frank",
    LastUpdated = Timestamp.FromDateTime(new DateTime(2026, 10, 17, 12, 30, 0, DateTimeKind.Utc)),
};
p.Phones.Add(new Person.Types.PhoneNumber { Number = "555-0007", Type = Person.Types.PhoneType.Mobile });

string json = JsonFormatter.Default.Format(p);
Console.WriteLine(json);

var withDefaults = new JsonFormatter(JsonFormatter.Settings.Default
    .WithFormatDefaultValues(true)
    .WithIndentation());
Console.WriteLine(withDefaults.Format(new Person { Name = "Gina" }));

Person parsed = JsonParser.Default.Parse<Person>(json);
Console.WriteLine(parsed.Equals(p));

// both snake_case and lowerCamelCase names are accepted
var p2 = JsonParser.Default.Parse<Person>("""{"name":"Hal","last_updated":"2026-01-01T00:00:00Z"}""");
Console.WriteLine(p2.LastUpdated.ToDateTime().ToString("O"));

string withExtra = """{"name":"Ivy","nickname":"ivy"}""";
try
{
    JsonParser.Default.Parse<Person>(withExtra);
}
catch (InvalidProtocolBufferException e)
{
    Console.WriteLine(e.Message);
}
var lenient = new JsonParser(JsonParser.Settings.Default.WithIgnoreUnknownFields(true));
Console.WriteLine(lenient.Parse<Person>(withExtra).Name);
{ "name": "Frank", "id": 7, "phones": [ { "number": "555-0007", "type": "PHONE_TYPE_MOBILE" } ], "lastUpdated": "2026-10-17T12:30:00Z" }
{
  "name": "Gina",
  "id": 0,
  "email": "",
  "phones": [],
  "labels": {}
}
True
2026-01-01T00:00:00.0000000Z
Unknown field: nickname
Ivy

Things to know about the JSON mapping:

Don't use System.Text.Json on generated classes. It doesn't know about these rules and produces different output. For regular JSON in C#, see JSON handling.

Well-known types

Google ships a set of standard messages in Google.Protobuf.WellKnownTypes. The most useful are Timestamp, Duration and Any:

using Contacts;
using Google.Protobuf;
using Google.Protobuf.WellKnownTypes;

Timestamp ts = Timestamp.FromDateTime(new DateTime(2026, 10, 17, 8, 0, 0, DateTimeKind.Utc));
Console.WriteLine($"{ts.Seconds} s, {ts.Nanos} ns -> {ts}");
Console.WriteLine(ts.ToDateTime().Kind);

var now = Timestamp.FromDateTimeOffset(new DateTimeOffset(2026, 10, 17, 10, 0, 0, TimeSpan.FromHours(2)));
Console.WriteLine(now);

try
{
    Timestamp.FromDateTime(new DateTime(2026, 10, 17, 8, 0, 0, DateTimeKind.Local));
}
catch (ArgumentException e)
{
    Console.WriteLine(e.Message);
}

Duration d = Duration.FromTimeSpan(TimeSpan.FromMinutes(90.5));
Console.WriteLine($"{d} = {d.ToTimeSpan()}");
Console.WriteLine(ts + d);

// Any wraps an arbitrary message together with its type URL
Any any = Any.Pack(new Person { Name = "Jo" });
Console.WriteLine(any.TypeUrl);
Console.WriteLine(any.Is(Person.Descriptor));
if (any.TryUnpack(out Person person))
    Console.WriteLine(person.Name);
Console.WriteLine(any.TryUnpack(out AddressBook _));
1792224000 s, 0 ns -> "2026-10-17T08:00:00Z"
Utc
"2026-10-17T08:00:00Z"
Conversion from DateTime to Timestamp requires the DateTime kind to be Utc (Parameter 'dateTime')
"5430s" = 01:30:30
"2026-10-17T09:30:30Z"
type.googleapis.com/contacts.Person
True
Jo
False

Timestamp stores seconds and nanoseconds since the Unix epoch, always in UTC. FromDateTime refuses a DateTime whose Kind isn't Utc, so either call ToUniversalTime() first or use FromDateTimeOffset, which converts for you. Timestamp.FromDateTime(DateTime.UtcNow) is the usual way to stamp "now".

There are also wrapper types (google.protobuf.Int32Value, StringValue, ...) that map to int? and string in C# and give a scalar field presence, Struct/Value for arbitrary JSON-like data, and Empty for RPCs without input or output. Today optional is usually a simpler choice than the wrappers.

Evolving the schema

The main reason to use protobuf over a home-made binary format is that old and new code can talk to each other. Take two versions of a message (Protos/versions.proto):

syntax = "proto3";

package versions;

option csharp_namespace = "Versions";

message UserV1 {
  string name = 1;
}

message UserV2 {
  string name = 1;
  int32 karma = 2;
  repeated string roles = 3;
}

In practice these would be the same message at two points in time. They're two messages here so both can be used in one program:

using Google.Protobuf;
using Versions;

// a new client writes UserV2
var v2 = new UserV2 { Name = "kim", Karma = 42 };
v2.Roles.Add("admin");
byte[] fromNewClient = v2.ToByteArray();

// an old service only knows UserV1
UserV1 v1 = UserV1.Parser.ParseFrom(fromNewClient);
Console.WriteLine($"v1 sees name={v1.Name}");
v1.Name = "kim2";

// unknown fields 2 and 3 were kept and are written back out
byte[] fromOldService = v1.ToByteArray();
UserV2 roundTrip = UserV2.Parser.ParseFrom(fromOldService);
Console.WriteLine(roundTrip);

// and an old message parsed by the new code just has defaults
var old = UserV2.Parser.ParseFrom(new UserV1 { Name = "lee" }.ToByteArray());
Console.WriteLine($"{old.Name} karma={old.Karma} roles={old.Roles.Count}");

// DiscardUnknownFields drops them instead
var strict = UserV1.Parser.WithDiscardUnknownFields(true).ParseFrom(fromNewClient);
Console.WriteLine(UserV2.Parser.ParseFrom(strict.ToByteArray()));
v1 sees name=kim
{ "name": "kim2", "karma": 42, "roles": [ "admin" ] }
lee karma=0 roles=0
{ "name": "kim" }

Rules for changing a message that's already in use:

Parsing errors

Invalid input throws InvalidProtocolBufferException. But the format has no magic number or type information, so many byte sequences that weren't meant to be a Person still parse fine:

using Contacts;
using Google.Protobuf;

byte[] garbage = [0x0A, 0x10, 0x41, 0x42];
try
{
    Person.Parser.ParseFrom(garbage);
}
catch (InvalidProtocolBufferException e)
{
    Console.WriteLine(e.Message);
}

// bytes that happen to be valid protobuf parse "successfully"
byte[] wrongType = new Versions.UserV1 { Name = "not a person" }.ToByteArray();
Person p = Person.Parser.ParseFrom(wrongType);
Console.WriteLine($"name='{p.Name}'");

byte[] utf8 = System.Text.Encoding.UTF8.GetBytes("hello, world");
try
{
    Person.Parser.ParseFrom(utf8);
}
catch (InvalidProtocolBufferException e)
{
    Console.WriteLine(e.Message);
}
While parsing a protocol message, the input ended unexpectedly in the middle of a field.  This could mean either that the input has been truncated or that an embedded message misreported its own length.
name='not a person'
Completed reading a message while more data was available in the stream.

The first input claims a 16-byte string but has only 2 bytes. The second is a different message type that happens to share field 1. The third is text, which got past several "fields" before failing with a confusing message. Successful parsing doesn't prove you have the right type, so make sure both sides agree on the message (for example with gRPC, a container message, or Any) and validate the values you get. When parsing untrusted input, the parser protects you against deep nesting (recursion limit of 100) and you can set a size limit with CodedInputStream.CreateWithLimits.

Reflection with descriptors

Every generated class exposes a Descriptor describing its schema. You can use it to write generic code, such as a logger that masks certain fields or a tool that dumps any message:

using Contacts;
using Google.Protobuf.Reflection;

MessageDescriptor desc = Person.Descriptor;
Console.WriteLine($"{desc.FullName} from {desc.File.Name}");
foreach (FieldDescriptor f in desc.Fields.InFieldNumberOrder())
{
    string kind = f.IsMap ? "map" : f.IsRepeated ? "repeated" : f.FieldType.ToString().ToLowerInvariant();
    Console.WriteLine($"  {f.FieldNumber,2} {f.Name,-16} {kind}");
}

var p = new Person { Name = "Lou", Id = 3 };
FieldDescriptor nameField = desc.FindFieldByName("name");
Console.WriteLine(nameField.Accessor.GetValue(p));
nameField.Accessor.SetValue(p, "Lou Reed");
Console.WriteLine(p.Name);
contacts.Person from Protos/person.proto
   1 name             string
   2 id               int32
   3 email            string
   4 phones           repeated
   5 labels           map
   6 last_updated     message
   7 age              int32
   8 preferred_email  string
   9 preferred_phone  message
Lou
Lou Reed

Code-first alternative: protobuf-net

If you only talk to other .NET code and don't want .proto files, the protobuf-net library serializes ordinary C# classes annotated with attributes into the same wire format:

#:package protobuf-net@3.4.30
#:property PublishAot=false
using ProtoBuf;

var order = new Order { Id = 150, Customer = "Bo", Items = ["apple", "pear"] };

using var ms = new MemoryStream();
Serializer.Serialize(ms, order);
Console.WriteLine(Convert.ToHexString(ms.ToArray()));

ms.Position = 0;
Order copy = Serializer.Deserialize<Order>(ms);
Console.WriteLine($"{copy.Id} {copy.Customer} [{string.Join(", ", copy.Items)}]");

Console.WriteLine(Serializer.GetProto<Order>());

[ProtoContract]
public class Order
{
    [ProtoMember(1)] public int Id { get; set; }
    [ProtoMember(2)] public string Customer { get; set; } = "";
    [ProtoMember(3)] public List<string> Items { get; set; } = [];
}
0896011202426F1A056170706C651A0470656172
150 Bo [apple, pear]
syntax = "proto3";

message Order {
   int32 Id = 1;
   string Customer = 2;
   repeated string Items = 3;
}

This is a file-based program (dotnet run app.cs). File-based programs enable Native AOT by default, and protobuf-net warns that its reflection-based serializers won't survive AOT, hence PublishAot=false. ProtoMember(n) plays the role of the field number, and GetProto<T>() produces a .proto file you can give to teams using other languages. For new cross-language work, prefer the official .proto-first approach, so the schema is the source of truth.

Protobuf (either library) is also the modern replacement for BinaryFormatter, whose implementation was removed in .NET 9 (it now always throws) because it's insecure. See Binary Serialization for the history.

Summary

Feedback about page:

Feedback:
Optional: your email if you want me to get back to you:



Table Of Contents