Skip to content

Latest commit

 

History

History
 
 

csharp

README.md

This directory contains the C# Protocol Buffers runtime library.

Usage

The easiest way how to use C# protobufs is via the Google.Protobuf NuGet package. Just add the NuGet package to your VS project.

You will also want to install the Google.Protobuf.Tools NuGet package, which contains precompiled version of protoc.exe and a copy of well known .proto files under the package's tools directory.

To generate C# files from your .proto files, invoke protoc with the --csharp_out option.

Supported platforms

The runtime library is built as a portable class library, supporting:

  • .NET 4.5
  • Windows 8
  • Windows Phone Silverlight 8
  • Windows Phone 8.1
  • .NET Core

You should be able to use Protocol Buffers in Visual Studio 2012 and all later versions. This includes all code generated by protoc, which only uses features from C# 3 and earlier.

Building

Open the src/Google.Protobuf.sln solution in Visual Studio 2015 or later.

Although users of this project are only expected to have Visual Studio 2012 or later, developers of the library are required to have Visual Studio 2015 or later, as the library uses C# 6 features in its implementation. These features have no impact when using the compiled code - they're only relevant when building the Google.Protobuf assembly.

Testing

The unit tests use NUnit 3. Vanilla NUnit doesn't support .NET Core, so to run the tests you'll need to use dotnet-test-nunit. dotnet-test-nunit can also run tests for .NET 4.5+, so to run the tests for both .NET Core and .NET 4.5, you can simply open the Package Manager Console in Visual Studio and execute:

dotnet test Google.Protobuf.Test

.NET 3.5

We don't officially support .NET 3.5. However, there has been some effort to make enabling .NET 3.5 support relatively painless in case you require it. There's no guarantee that this will continue in the future, so rely on .NET 3.5 support at your peril.

To enable .NET 3.5 support:

  1. Modify src/Google.Protobuf/project.json to add "net35": {} to "frameworks".
  2. Modify src/Google.Protobuf.Test/project.json:
  3. Add "net35": {} to "frameworks".
  4. dotnet-test-nunit doesn't support .NET 3.5, so remove it from the project-wide "dependencies" and add it to the framework-specific dependencies under "net451" and "netcoreapp1.0".

Note that dotnet-test-nunit doesn't support .NET 3.5. You can instead run the tests with NUnit 3 console by running something like:

nunit3-console.exe "Google.Protobuf.Test\bin\Debug\net35\win7-x64\Google.Protobuf.Test.dll" --inprocess

The exact path may differ depending on your environment (e.g., the win7-x64 directory may be called something else). The --inprocess flag seems to be a necessary workaround for a bug in NUnit; otherwise, you'll receive an error "Exception has been thrown by the target of an invocation" (possibly related issue).

If you still want to run the .NET 4.5 and .NET Core tests, you can do so by specifying the framework when using dotnet-test-nunit, i.e. from Package Manager Console in Visual Studio:

dotnet test Google.Protobuf.Test --framework netcoreapp1.0
dotnet test Google.Protobuf.Test --framework net451

History of C# protobufs

This subtree was originally imported from https://github.com/jskeet/protobuf-csharp-port and represents the latest development version of C# protobufs, that will now be developed and maintained by Google. All the development will be done in open, under this repository (https://github.com/google/protobuf).

The previous project differs from this project in a number of ways:

  • The old code only supported proto2; the new code only supports proto3 (so no unknown fields, no required/optional distinction, no extensions)
  • The old code was based on immutable message types and builders for them
  • The old code did not support maps or oneof
  • The old code had its own JSON representation, whereas the new code uses the standard protobuf JSON representation
  • The old code had no notion of the "well-known types" which have special support in the new code
  • The old project supported some older platforms (such as older versions of Silverlight) which are not currently supported in the new project