513b35dc4e
Add mention to the "Build" section of the ReadMe of the requirement of installing an optional component to VS2017.
97 lines
3.7 KiB
Markdown
97 lines
3.7 KiB
Markdown
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 2017 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 2017 or later, as the library uses C# 6 features
|
|
in its implementation, as well as the new Visual Studio 2017 csproj
|
|
format. These features have no impact when using the compiled code -
|
|
they're only relevant when building the `Google.Protobuf` assembly.
|
|
|
|
In order to run and debug the AddressBook example in the IDE, you must
|
|
install the optional component, ".Net Core 1.0 - 1.1 development tools
|
|
for Web" (as it's labelled in current versions of the VS2017
|
|
installer), above and beyond the main .NET Core cross-platform
|
|
development feature.
|
|
|
|
Testing
|
|
=======
|
|
|
|
The unit tests use [NUnit 3](https://github.com/nunit/nunit). Tests can be
|
|
run using the Visual Studio Test Explorer or `dotnet 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, you must edit the `TargetFrameworks` elements of
|
|
[src/Google.Protobuf/Google.Protobuf.csproj](src/Google.Protobuf/Google.Protobuf.csproj)
|
|
(and [src/Google.Protobuf.Test/Google.Protobuf.Test.csproj](src/Google.Protobuf.Test/Google.Protobuf.Test.csproj)
|
|
if you want to run the unit tests):
|
|
|
|
Open the .csproj file in a text editor and simply add `net35` to the list of
|
|
target frameworks, noting that the `TargetFrameworks` element appears twice in
|
|
the file (once in the first `PropertyGroup` element, and again in the second
|
|
`PropertyGroup` element, i.e., the one with the conditional).
|
|
|
|
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
|