1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
|
As part of the 3.10 release of Google.Protobuf, experimental proto2 support has been released. This document outlines the new changes brought about to include proto2 support. This does not break existing proto3 support and users may continue to use proto3 features without changing their current code. Again the generated code and public API associated with proto2 is experimental and subject to change in the future. APIs for proto2 may be added, removed, or adjusted as feedback is received.
Generated code for proto2 may also be modified by adding, removing, or adjusting APIs as feedback is received.
### Enabling proto2 features
For information about specific proto2 features, please read the [proto2 language guide](https://developers.google.com/protocol-buffers/docs/proto).
Much like other languages, proto2 features are used with proto2 files with the syntax declaration `syntax = "proto2";`. However, please note, proto3 is still the recommended version of protobuf and proto2 support is meant for legacy system interop and advanced uses.
# Generated code
### Messages
Messages in proto2 files are very similar to their proto3 counterparts. They expose the usual property for getting and setting, but they also include properties and methods to handle field presence.
For `optional`/`required` field XYZ, a `HasXYZ` property is included for checking presence and a `ClearXYZ` method is included for clearing the value.
```proto
message Foo {
optional Bar bar = 1;
required Baz baz = 2;
}
```
```cs
var foo = new Foo();
Assert.IsNull(foo.Bar);
Assert.False(foo.HasBar);
foo.Bar = new Bar();
Assert.True(foo.HasBar);
foo.ClearBar();
```
### Messages with extension ranges
Messages which define extension ranges implement the `IExtendableMessage` interface as shown below.
See inline comments for more info.
```cs
public interface IExtendableMessage<T> : IMessage<T> where T : IExtendableMessage<T>
{
// Gets the value of a single value extension. If the extension isn't present, this returns the default value.
TValue GetExtension<TValue>(Extension<T, TValue> extension);
// Gets the value of a repeated extension. If the extension hasn't been set, this returns null to prevent unnecessary allocations.
RepeatedField<TValue> GetExtension<TValue>(RepeatedExtension<T, TValue> extension);
// Gets the value of a repeated extension. This will initialize the value of the repeated field and will never return null.
RepeatedField<TValue> GetOrInitializeExtension<TValue>(RepeatedExtension<T, TValue> extension);
// Sets the value of the extension
void SetExtension<TValue>(Extension<T, TValue> extension, TValue value);
// Returns whether the extension is present in the message
bool HasExtension<TValue>(Extension<T, TValue> extension);
// Clears the value of the extension, removing it from the message
void ClearExtension<TValue>(Extension<T, TValue> extension);
// Clears the value of the repeated extension, removing it from the message. Calling GetExtension after this will always return null.
void ClearExtension<TValue>(RepeatedExtension<T, TValue> extension);
}
```
### Extensions
Extensions are generated in static containers like reflection classes and type classes.
For example for a file called `foo.proto` containing extensions in the file scope, a
`FooExtensions` class is created containing the extensions defined in the file scope.
For easy access, this class can be used with `using static` to bring all extensions into scope.
```proto
option csharp_namespace = "FooBar";
extend Foo {
optional Baz foo_ext = 124;
}
message Baz {
extend Foo {
repeated Baz repeated_foo_ext = 125;
}
}
```
```cs
public static partial class FooExtensions {
public static readonly Extension<Foo, Baz> FooExt = /* initialization */;
}
public partial class Baz {
public partial static class Extensions {
public static readonly RepeatedExtension<Foo, Baz> RepeatedFooExt = /* initialization */;
}
}
```
```cs
using static FooBar.FooExtensions;
using static FooBar.Baz.Extensions;
var foo = new Foo();
foo.SetExtension(FooExt, new Baz());
foo.GetOrInitializeExtension(RepeatedFooExt).Add(new Baz());
```
# APIs
### Message initialization
Initialization refers to checking the status of required fields in a proto2 message. If a message is uninitialized, not all required fields are set in either the message itself or any of its submessages. In other languages, missing required fields throw errors depending on the merge method used. This could cause unforeseen errors at runtime if the incorrect method is used.
However, in this implementation, parsers and input streams don't check messages for initialization on their own and throw errors. Instead it's up to you to handle messages with missing required fields in whatever way you see fit.
Checking message initialization can be done manually via the `IsInitialized` extension method in `MessageExtensions`.
### Extension registries
Just like in Java, extension registries can be constructed to parse extensions when reading new messages
from input streams. The API is fairly similar to the Java API with some added bonuses with C# syntax sugars.
```proto
message Baz {
extend Foo {
optional Baz foo_ext = 124;
}
}
```
```cs
var registry = new ExtensionRegistry()
{
Baz.Extensions.FooExt
};
var foo = Foo.Factory.WithExtensionRegistry(registry).ParseFrom(input);
Assert.True(foo.HasExtension(Bas.Extensions.FooExt));
var fooNoRegistry = Foo.Factory.ParseFrom(input);
Assert.False(foo.HasExtension(Bas.Extensions.FooExt));
```
### Custom options
Due to their limited use and lack of type safety, the original `CustomOptions` APIs are now deprecated. Using the new generated extension identifiers, you can access extensions safely through the GetOption APIs. Note that cloneable values such as
repeated fields and messages will be deep cloned.
Example based on custom options usage example [here](https://github.com/protocolbuffers/protobuf/issues/5007#issuecomment-411604515).
```cs
foreach (var service in input.Services)
{
Console.WriteLine($" {service.Name}");
foreach (var method in service.Methods)
{
var rule = method.GetOption(AnnotationsExtensions.Http);
if (rule != null)
{
Console.WriteLine($" {method.Name}: {rule}");
}
else
{
Console.WriteLine($" {method.Name}: no HTTP binding");
}
}
}
```
### Reflection
Reflection APIs have been extended to enable accessing the new proto2 portions of the library and generated code.
* FieldDescriptor.Extension
* Gets the extension identifier behind an extension field, allowing it to be added to an ExtensionRegistry
* FieldDescriptor.IsExtension
* Returns whether a field is an extension of another type.
* FieldDescriptor.ExtendeeType
* Returns the extended type of an extension field
* IFieldAccessor.HasValue
* Returns whether a field's value is set. For proto3 fields, throws an InvalidOperationException.
* FileDescriptor.Syntax
* Gets the syntax of a file
* FileDescriptor.Extensions
* An immutable list of extensions defined in the file
* MessageDescriptor.Extensions
* An immutable list of extensions defined in the message
```cs
var extensions = Baz.Descriptor.Extensions.GetExtensionsInDeclarationOrder(Foo.Descriptor);
var registry = new ExtensionRegistry();
registry.AddRange(extensions.Select(f => f.Extension));
var baz = Foo.Descriptor.Parser.WithExtensionRegistry(registry).ParseFrom(input);
foreach (var field in extensions)
{
if (field.Accessor.HasValue(baz))
{
Console.WriteLine($"{field.Name}: {field.Accessor.GetValue(baz)}");
}
}
```
|