diff options
Diffstat (limited to 'csharp/README.md')
| -rw-r--r-- | csharp/README.md | 44 |
1 files changed, 28 insertions, 16 deletions
diff --git a/csharp/README.md b/csharp/README.md index d6948280..a798ee62 100644 --- a/csharp/README.md +++ b/csharp/README.md @@ -1,33 +1,45 @@ - This directory contains the C# Protocol Buffers runtime library. +Warning: experimental! +====================== + +This code is still under significant churn. Unlike the original port, +it only supports proto3 (but not *all* of proto3 yet) - there are no +unknown fields or extensions, for example. protoc will (eventually) +deliberately fail if it is asked to generate C# code for proto2 +messages other than descriptor.proto, which is still required for +reflection. (It's currently exposed publicly, but won't be +eventually.) + +Also unlike the original port, the new version embraces mutability - +there are no builder types. We plan to add "freezing" operations as +well as cloning, however. + Usage ===== -The easiest way to use C# protocol buffers in your project is to use the [Google.ProtocolBuffers NuGet package](http://www.nuget.org/packages/Google.ProtocolBuffers/). This package is the legacy package for C# protocol buffers, but it will work fine with C# code generated by `protoc` if you use proto2 syntax (The API of the runtime library haven't changed so far). +Use `protoc` with the `--csharp_out` option to generate C# files in the specified directory. +Include these in your C# project, and add a reference to the `Google.Protobuf` project. Currently +there is no NuGet package for this, but we will be building one as soon as the API is stable. + +Supported platforms +=================== -*WARNING: If you specify `syntax = "proto3";` in your .proto files, the generated code won't necessarily work with the legacy NuGet package. So before we officially add proto3 support, always use `syntax = "proto2";` (the default) in your protos.* +The runtime library is built as a portable class library, supporting: -We will definitely release a new NuGet package for the runtime library in the future. The new runtime library WILL contain significant semantic, backwardly-incompatible changes in proto handling (mostly because we will be adding proto3 support and we will be using that oportunity to make some design changes). So keep in mind that you will need to regenerate your proto files and switch to a new NuGet package once the new version of runtime library becomes available. +- .NET 4.5 +- Windows 8 +- Windows Phone Silverlight 8 +- Windows Phone 8.1 +- .NET Core (dnxcore) Building ======== -Open the `src/ProtocolBuffers.sln` solution in Visual Studio. Click "Build solution" to build the solution. You should be able to run the NUnit test from Test Explorer (you might need to install NUnit Visual Studio add-in). +Open the `src/Google.Protobuf.sln` solution in Visual Studio. Click "Build solution" to build the solution. You should be able to run the NUnit test from Test Explorer (you might need to install NUnit Visual Studio add-in). Supported Visual Studio versions are VS2013 (update 4) and VS2015. On Linux, you can also use Monodevelop 5.9 (older versions might work fine). -Proto2 & Proto3 -=============== - -*WARNING: Only proto2 is supported for now, proto3 is under construction.* - -C# protocol buffers are currently under development and you should expect semantic, backward-incompatible changes in the future. - -Also, as of now, only proto2 is supported. Proto3 support for C# is currently in progress -(both design & implementation) and you should not expect any of the proto3 features to work. -In fact, always use `syntax = "proto2";` in your .proto files for now, unless you are feeling like experimenting. - History of C# protobufs ======================= |