Skip to main content
The C# Protocol Buffers runtime (version 3.35-dev) targets .NET 4.5+, .NET Standard 1.1/2.0, and .NET 5+. The Google.Protobuf NuGet package is the easiest way to get started.

​
Installation

1

Add the NuGet package

In your project directory, run:
dotnet add package Google.Protobuf
Or add it via the NuGet Package Manager in Visual Studio by searching for Google.Protobuf.
2

Install the protoc tools package

The Google.Protobuf.Tools package includes a precompiled protoc.exe and the well-known .proto files:
dotnet add package Google.Protobuf.Tools
3

Generate C# code from your .proto files

Invoke protoc with --csharp_out:
protoc --csharp_out=. addressbook.proto
This generates Addressbook.cs (or multiple files if using option csharp_namespace).
4

Add generated files to your project

Include the generated .cs files in your project. They depend only on Google.Protobuf, which you already added in step 1.

​
Generating code

The --csharp_out flag tells protoc to emit C# code. The csharp_namespace file option controls the namespace for generated types: 
// addressbook.proto
syntax = "proto3";
package tutorial;

option csharp_namespace = "Google.Protobuf.Examples.AddressBook";

protoc --csharp_out=Generated addressbook.proto

​
Working with messages

​
Creating and mutating messages

C# generated message classes are mutable objects. Set properties directly: 
using Google.Protobuf.Examples.AddressBook;

var person = new Person
{
    Id = 1234,
    Name = "Jane Doe",
    Email = "[email protected]",
    Phones =
    {
        new Person.Types.PhoneNumber
        {
            Number = "+1-555-0100",
            Type = Person.Types.PhoneType.Mobile
        }
    }
};

​
Serializing and parsing

byte[] bytes = person.ToByteArray();

​
JSON support

The C# runtime includes full support for the canonical protobuf JSON format: 
using Google.Protobuf;

// Serialize to JSON
string json = JsonFormatter.Default.Format(person);

// Parse from JSON
var parser = new JsonParser(JsonParser.Settings.Default);
Person fromJson = parser.Parse<Person>(json);
The JSON format uses proto field names by default. Pass JsonFormatter.Settings options to use camelCase names or to include fields with default values.

​
Supported platforms

TargetFramework
Desktop / server.NET 4.5+, .NET 5+
Cross-platform.NET Standard 1.1, .NET Standard 2.0
Visual Studio2012 and later
When compiling generated code with C# compilers older than version 7.2, define the GOOGLE_PROTOBUF_REFSTRUCT_COMPATIBILITY_MODE symbol in your project. This prevents the generated classes from implementing IBufferMessage, which uses ref struct types unavailable in older compilers.

​
Key API reference

IMessage

All generated classes implement Google.Protobuf.IMessage<T>. Provides WriteTo(CodedOutputStream), MergeFrom(CodedInputStream), CalculateSize(), and Clone().

MessageParser

Each generated class exposes a static Parser property of type MessageParser<T>. Use Person.Parser.ParseFrom(bytes) or Person.Parser.ParseFrom(stream).

JSON

JsonFormatter.Default.Format(message) for serialization. JsonParser.Default.Parse<T>(json) for parsing. Part of the Google.Protobuf package — no extra dependency needed.

Well-known types

Google.Protobuf.WellKnownTypes namespace contains C# representations of Timestamp, Duration, Struct, Any, and other well-known types with special serialization behavior.

Build docs developers (and LLMs) love

Get started for freeTalk to us