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 portable class library, supporting: 20 21- .NET 4.5 22- Windows 8 23- Windows Phone Silverlight 8 24- Windows Phone 8.1 25- .NET Core 26 27You should be able to use Protocol Buffers in Visual Studio 2012 and 28all later versions. This includes all code generated by `protoc`, 29which only uses features from C# 3 and earlier. 30 31Building 32======== 33 34Open the `src/Google.Protobuf.sln` solution in Visual Studio 2017 or 35later. 36 37Although *users* of this project are only expected to have Visual 38Studio 2012 or later, *developers* of the library are required to 39have Visual Studio 2017 or later, as the library uses C# 6 features 40in its implementation, as well as the new Visual Studio 2017 csproj 41format. These features have no impact when using the compiled code - 42they're only relevant when building the `Google.Protobuf` assembly. 43 44In order to run and debug the AddressBook example in the IDE, you must 45install the optional component, ".Net Core 1.0 - 1.1 development tools 46for Web" (as it's labelled in current versions of the VS2017 47installer), above and beyond the main .NET Core cross-platform 48development feature. 49 50Testing 51======= 52 53The unit tests use [NUnit 3](https://github.com/nunit/nunit). Tests can be 54run using the Visual Studio Test Explorer or `dotnet test`. 55 56.NET 3.5 57======== 58 59We don't officially support .NET 3.5. However, there has been some effort 60to make enabling .NET 3.5 support relatively painless in case you require it. 61There's no guarantee that this will continue in the future, so rely on .NET 623.5 support at your peril. 63 64To enable .NET 3.5 support, you must edit the `TargetFrameworks` elements of 65[src/Google.Protobuf/Google.Protobuf.csproj](src/Google.Protobuf/Google.Protobuf.csproj) 66(and [src/Google.Protobuf.Test/Google.Protobuf.Test.csproj](src/Google.Protobuf.Test/Google.Protobuf.Test.csproj) 67if you want to run the unit tests): 68 69Open the .csproj file in a text editor and simply add `net35` to the list of 70target frameworks, noting that the `TargetFrameworks` element appears twice in 71the file (once in the first `PropertyGroup` element, and again in the second 72`PropertyGroup` element, i.e., the one with the conditional). 73 74History of C# protobufs 75======================= 76 77This subtree was originally imported from https://github.com/jskeet/protobuf-csharp-port 78and represents the latest development version of C# protobufs, that will now be developed 79and maintained by Google. All the development will be done in open, under this repository 80(https://github.com/protocolbuffers/protobuf). 81 82The previous project differs from this project in a number of ways: 83 84- The old code only supported proto2; the new code only supports 85proto3 (so no unknown fields, no required/optional distinction, no 86extensions) 87- The old code was based on immutable message types and builders for 88them 89- The old code did not support maps or `oneof` 90- The old code had its own JSON representation, whereas the new code 91uses the standard protobuf JSON representation 92- The old code had no notion of the "well-known types" which have 93special support in the new code 94- The old project supported some older platforms (such as older 95versions of Silverlight) which are not currently supported in the 96new project 97