1This directory contains the C# Protocol Buffers runtime library. 2 3Usage 4===== 5 6The easiest way how to use C# protobufs is via the `Google.Protobuf` 7NuGet package. Just add the NuGet package to your VS project. 8 9You will also want to install the `Google.Protobuf.Tools` NuGet package, which 10contains precompiled version of `protoc.exe` and a copy of well known `.proto` 11files under the package's `tools` directory. 12 13To generate C# files from your `.proto` files, invoke `protoc` with the 14`--csharp_out` option. 15 16Supported platforms 17=================== 18 19The runtime library is built as a class library, supporting targets of: 20 21- .NET 4.5+ (`net45`) 22- .NET Standard 1.1 and 2.0 (`netstandard1.1` and `netstandard2.0`) 23- .NET 5+ (`net50`) 24 25You should be able to use Protocol Buffers in Visual Studio 2012 and 26all later versions. This includes all code generated by `protoc`, 27which only uses features from C# 3 and earlier. When compiling generated 28code with old compilers (before C# 7.2) you need to define the 29`GOOGLE_PROTOBUF_REFSTRUCT_COMPATIBILITY_MODE` symbol in your project 30so that the generated classes don't implement `IBufferMessage`, which uses 31`ref struct` types. 32 33Building 34======== 35 36Open the `src/Google.Protobuf.sln` solution in Visual Studio 2022 or 37later. 38 39Although *users* of this project are only expected to have Visual 40Studio 2012 or later, *developers* of the library are required to 41have Visual Studio 2022 or later, as the library uses C# 10 features 42in its implementation and runs tests under .NET 6. These features 43have no impact when using the compiled code - they're only relevant 44when building the `Google.Protobuf` assembly. 45 46Testing 47======= 48 49The unit tests use [NUnit 3](https://github.com/nunit/nunit). Tests can be 50run using the Visual Studio Test Explorer or `dotnet test`. 51 52.NET 3.5 53======== 54 55We don't support .NET 3.5. It *used* to be feasible to build this library 56targeting .NET 3.5, but a number of changes requiring newer runtime/framework 57features have been added over time. While it would no doubt be *possible* to 58rework the current implementation to allow most of the functionality to be built 59in .NET 3.5, this would create an undue maintenance burden. 60 61History of C# protobufs 62======================= 63 64This subtree was originally imported from https://github.com/jskeet/protobuf-csharp-port 65and represents the latest development version of C# protobufs, that will now be developed 66and maintained by Google. All the development will be done in open, under this repository 67(https://github.com/protocolbuffers/protobuf). 68 69The previous project differs from this project in a number of ways: 70 71- The old code only supported proto2; the new code initially only supported 72proto3 (so no unknown fields, no required/optional distinction, no 73extensions); since then proto2 support has been added 74- The old code was based on immutable message types and builders for 75them 76- The old code did not support maps or `oneof` 77- The old code had its own JSON representation, whereas the new code 78uses the standard protobuf JSON representation 79- The old code had no notion of the "well-known types" which have 80special support in the new code 81- The old project supported some older platforms (such as older 82versions of Silverlight) which are not currently supported in the 83new project 84