Merge remote-tracking branch 'origin/csharp-0.4-dev'

Author: externl

content/slice/language-guide/class-types.md

@@ -44,14 +44,15 @@ example:
 ```slice
 class CarPart {
     id: string
+    revision: int32
 }
 
 class RearBumper : CarPart {
     color: Color
 }
 ```
 
-`RearBumper` has two fields: `id` (inherited from `CartPart`) and `color`.
+`RearBumper` has three fields: `id` and `revision` (inherited from `CartPart`) and `color`.
 
 A derived class cannot redefine a field of its base class: all the fields must have unique names.
 
@@ -210,64 +211,90 @@ For example:
 ```slice
 class CarPart {
     id: string
+    revision: int32
     tag(1) shippingWeight: float64?
 }
 ```
 
 ```csharp
 public partial class CarPart : SliceClass
 {
-    public string Id;
-    public double? ShippingWeight;
+    public required string Id { get; set; }
+
+    public int Revision { get; set; }
+
+    public double? ShippingWeight { get; set; }
+
+    // Parameterless constructor
+    public CarPart()
+    {
+    }
 
     // Primary constructor
-    public CarPart(string id, double? shippingWeight)
+    public CarPart(
+        string id,
+        int revision,
+        double? shippingWeight)
     {
-       ...
+        this.Id = id;
+        this.Revision = revision;
+        this.ShippingWeight = shippingWeight;
     }
 
     // Secondary constructor
-    public CarPart(string id)
+    public CarPart(string id, int revision)
     {
-       ...
+        this.Id = id;
+        this.Revision = revision;
     }
-
 }
 ```
 
 {% /aside %}
 
-The mapped class has a primary constructor which sets all the fields. If any field has an optional type, the mapped
-class has a second constructor with a parameter for each non-nullable C# field.
+The mapped C# class provides a parameterless constructor and a primary constructor which sets all the fields. If any
+field has an optional type, the mapped class also provides a secondary constructor with a parameter for each
+non-nullable C# field.
 
-Slice class inheritance maps the C# class inheritance as you would expect:
+Slice class inheritance maps to C# class inheritance as you would expect:
 
 {% aside alignment="top" %}
 
 ```slice
-class FrontBumper : CarPart {
+class RearBumper : CarPart {
     color: Color
 }
 ```
 
 ```csharp
 public partial class RearBumper : CarPart
 {
-    public Color Color;
+    public Color Color { get; set; }
+
+    // Parameterless constructor
+    public RearBumper()
+    {
+    }
 
     // Primary constructor
     public RearBumper(
         string id,
+        int revision,
         double? shippingWeight,
         Color color)
+        : base(id, revision, shippingWeight)
     {
-        ...
+        this.Color = color;
     }
 
     // Secondary constructor
-    public RearBumper(string id, Color color)
+    public RearBumper(
+        string id,
+        int revision,
+        Color color)
+        : base(id, revision)
     {
-        ...
+       this.Color = color;
     }
 }
 ```

content/slice/language-guide/exception.md

@@ -76,29 +76,40 @@ exception TranslationException {
 ```
 
 ```csharp
-public partial class TranslationException
-    : SliceException
+public partial class TranslationException :
+    SliceException
 {
-    public TranslationErrorCode ErrorCode;
-    public string? DetectedLanguage;
+    public TranslationErrorCode ErrorCode { get; set; }
+    public string? DetectedLanguage { get; set; }
+
+    // Parameterless constructor
+    public TranslationException()
+    {
+    }
 
     // Primary constructor
     public TranslationException(
         TranslationErrorCode errorCode,
-        string? detectedLanguage,
-        string? message = null,
-        System.Exception? innerException = null)
-        : base(message, innerException)
+        string? detectedLanguage)
+    {
+        this.ErrorCode = errorCode;
+        this.DetectedLanguage = detectedLanguage;
+    }
+
+    // Secondary constructor
+    public TranslationException(
+        TranslationErrorCode errorCode)
     {
-        ...
+        this.ErrorCode = errorCode;
     }
 }
 ```
 
 {% /aside %}
 
-The mapped C# class provides a primary constructor with parameters for all its fields, plus an optional message and an
-optional inner exception (like most exceptions in C#).
+The mapped C# class provides a parameterless constructor and a primary constructor which sets all the fields. If any
+field has an optional type, the mapped class also provides a secondary constructor with a parameter for each
+non-nullable C# field.
 
 Slice exception inheritance maps to C# class inheritance:
 
@@ -117,66 +128,41 @@ exception DerivedException : BaseException {
 ```csharp
 public partial class BaseException : SliceException
 {
-    public int ErrorCode;
+    public int ErrorCode { get; set; }
 
-    // Primary constructor
-    public BaseException(
-        int errorCode,
-        string? message = null,
-        System.Exception? innerException = null)
-        : base(message, innerException)
+    public BaseException()
+    {
+    }
+
+    public BaseException(int errorCode)
     {
-        ...
+        this.ErrorCode = errorCode;
     }
 }
 
 public partial class DerivedException : BaseException
 {
-    public double Measurement;
+    public double Measurement { get; set; }
+
+    public DerivedException()
+    {
+    }
 
-    // Primary constructor.
     public DerivedException(
         int errorCode,
-        double measurement,
-        string? message = null,
-        System.Exception? innerException = null)
-        : base(errorCode, message, innerException)
+        double measurement)
+        : base(errorCode)
     {
-        ...
+        this.Measurement = measurement;
     }
 }
 ```
 
 {% /aside %}
 
-### ConvertToInternalError
-
-When the generated code decodes an exception from a payload, it sets the exception's
-[ConvertToInternalError][convert-to-internal-error] property to `true`.
-
-This way, when the implementation of an operation makes an invocation and this invocation throws an exception, by
-default, this exception is not re-sent as-is but gets converted into a response with status code
-[InternalError]. If you don't want this conversion, you need to catch the exception and set
-`ConvertToInternalError` to `false`:
-
-```csharp
-try
-{
-    ...make invocation...
-}
-catch (DispatchException exception)
-{
-    // Don't convert to internal error.
-    exception.ConvertToInternalError = false;
-    throw;
-}
-```
-
-[convert-to-internal-error]: csharp:IceRpc.DispatchException#IceRpc_DispatchException_ConvertToInternalError
 [exception-specification]: operation#exception-specification
 [sliced-format]: class-types#slicing
 
 [SliceException]: csharp:ZeroC.Slice.SliceException
-[InternalError]: csharp:IceRpc.StatusCode#IceRpc_StatusCode_InternalError
 
 {% /slice1 %}

content/slice/language-guide/fields.md

@@ -30,7 +30,7 @@ and `Dictionary<int32, string>` are constructed types.
 When you define a field, you can specify whether this field must hold a value of its type, or if holding a special "not
 set" value is also acceptable. In this latter situation, you would give the field an optional type, with a `?` suffix.
 
-This special "not set" value corresponds to null in C#, `std::nullopt` in C++, nil in Swift, etc.
+This special "not set" value corresponds to `null` in C#, `std::nullopt` in C++, `nil` in Swift, etc.
 
 For example:
 
@@ -58,11 +58,11 @@ Leaving tagged fields aside, only a few field types can be marked optional with
 ```slice
 struct Person {
     name: string
-    dataOfBirth: WellKnownTypes::TimeStamp?
+    dateOfBirth: WellKnownTypes::TimeStamp?
 }
 ```
 
-The field `dataOfBirth` may have a value or a "not set" value (when the date of birth is unknown).
+The field `dateOfBirth` may have a value or a "not set" value (when the date of birth is unknown).
 {% /slice2 %}
 
 {% callout %}
@@ -185,8 +185,12 @@ applications that expect tag 7 fields (in this tag number scope) to be encoded a
 
 ## C# mapping
 
-A field `name: Type` is mapped to a C# field with the same name, with name converted to Pascal case. The type of the C#
-field is the mapped C# type for `Type`.
+A field `name: Type` is mapped to a C# property with the same name, with name converted to Pascal case. The type of the
+C# property is the mapped C# type for `Type`.
+
+When a Slice field type maps to a non-nullable C# reference type (for example, a C# string), the mapped property is
+"required". This ensures you provide a value for this property during construction or initialization of the enclosing
+type.
 
 Tagged fields are mapped just like regular fields. The tag and tag number don't appear in the mapped C# API.
 

content/slice/language-guide/struct-types.md

@@ -82,12 +82,12 @@ compact struct PostalAddress {
 ```csharp
 public partial record struct PostalAddress
 {
-    public string RecipientFullName;
-    public string StreetAddress1;
-    public string StreetAddress2;
-    public string City;
-    public StateAbbreviation State;
-    public string Zip;
+    public required string RecipientFullName { get; set; }
+    public required string StreetAddress1 { get; set; }
+    public required string StreetAddress2 { get; set; }
+    public required string City { get; set; }
+    public StateAbbreviation State { get; set; }
+    public required string Zip { get; set; }
 
     // Primary constructor.
     public PostalAddress(
@@ -98,7 +98,12 @@ public partial record struct PostalAddress
         StateAbbreviation state,
         string zip)
     {
-        ...
+        this.RecipientFullName = recipientFullName;
+        this.StreetAddress1 = streetAddress1;
+        this.StreetAddress2 = streetAddress2;
+        this.City = city;
+        this.State = state;
+        this.Zip = zip;
     }
 
     // Decoding constructor.
@@ -137,13 +142,13 @@ struct PostalAddress {
 ```csharp
 public partial record struct PostalAddress
 {
-    public string RecipientFullName;
-    public string StreetAddress1;
-    public string? StreetAddress2;
-    public string? StreetAddress3; // tagged
-    public string City;
-    public StateAbbreviation State;
-    public string Zip;
+    public required string RecipientFullName { get; set; }
+    public required string StreetAddress1 { get; set; }
+    public string? StreetAddress2 { get; set; }
+    public string? StreetAddress3 { get; set; }
+    public required string City { get; set; }
+    public StateAbbreviation State { get; set; }
+    public required string Zip { get; set; }
 
     // Primary constructor.
     public PostalAddress(
@@ -155,7 +160,13 @@ public partial record struct PostalAddress
         StateAbbreviation state,
         string zip)
     {
-        ...
+        this.RecipientFullName = recipientFullName;
+        this.StreetAddress1 = streetAddress1;
+        this.StreetAddress2 = streetAddress2;
+        this.StreetAddress3 = streetAddress3;
+        this.City = city;
+        this.State = state;
+        this.Zip = zip;
     }
 
     // Decoding constructor.
@@ -195,17 +206,16 @@ compact struct Point { x: int32, y: int32 }
 ```csharp
 public readonly partial record struct Point
 {
-    public readonly int X;
-
-    public readonly int Y;
+    public int X { get; init; }
+    public int Y { get; init; }
 
     ...
 }
 ```
 
 {% /aside %}
 
-You can also apply `cs::readonly` to a struct field to map this field to a read-only C# field.
+You can also apply `cs::readonly` to a struct field to map this field to a get-init property.
 
 [tagged-fields]: fields#tagged-fields