From 9b558b23c1e9a83d08ffa8159f6ebe1212627d23 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Thu, 4 Jan 2024 11:38:05 +0800 Subject: [PATCH 1/2] Improve StatusProto XML docs --- src/Grpc.StatusProto/ExceptionExtensions.cs | 35 +++++----- src/Grpc.StatusProto/MetadataExtensions.cs | 24 ++++--- .../RpcExceptionExtensions.cs | 4 +- src/Grpc.StatusProto/RpcStatusExtensions.cs | 66 ++++++++++--------- 4 files changed, 68 insertions(+), 61 deletions(-) diff --git a/src/Grpc.StatusProto/ExceptionExtensions.cs b/src/Grpc.StatusProto/ExceptionExtensions.cs index b22397eb4..23f48544d 100644 --- a/src/Grpc.StatusProto/ExceptionExtensions.cs +++ b/src/Grpc.StatusProto/ExceptionExtensions.cs @@ -18,12 +18,12 @@ namespace Grpc.Core; /// -/// Extensions methods for +/// Extensions methods for converting to . /// public static class ExceptionExtensions { /// - /// Create a from an , + /// Create a from an , /// populating the Message and StackTrace from the exception. /// Note: experimental API that can change or be removed without any prior notice. /// @@ -31,27 +31,32 @@ public static class ExceptionExtensions /// /// For example: /// - /// try { /* ... */ + /// try + /// { + /// /* ... */ /// } - /// catch (Exception e) { - /// Google.Rpc.Status status = new() { - /// Code = (int)StatusCode.Internal, - /// Message = "Internal error", - /// Details = { - /// // populate debugInfo from the exception - /// Any.Pack(e.ToRpcDebugInfo()) - /// } - /// }; - /// // ... + /// catch (Exception e) + /// { + /// Google.Rpc.Status status = new() + /// { + /// Code = (int)StatusCode.Internal, + /// Message = "Internal error", + /// Details = + /// { + /// // populate debugInfo from the exception + /// Any.Pack(e.ToRpcDebugInfo()) + /// } + /// }; + /// // ... /// } /// /// /// - /// + /// The exception to create a from. /// Maximum number of inner exceptions to include in the StackTrace. Defaults /// to not including any inner exceptions /// - /// A new populated from the exception. + /// A new populated from the exception. /// public static DebugInfo ToRpcDebugInfo(this Exception exception, int innerDepth = 0) { diff --git a/src/Grpc.StatusProto/MetadataExtensions.cs b/src/Grpc.StatusProto/MetadataExtensions.cs index 4cbe2b6a1..9999c575e 100644 --- a/src/Grpc.StatusProto/MetadataExtensions.cs +++ b/src/Grpc.StatusProto/MetadataExtensions.cs @@ -18,26 +18,24 @@ namespace Grpc.Core; /// -/// Extension methods for the Grpc.Core.Metadata +/// Extension methods for using with . /// public static class MetadataExtensions { /// - /// Name of key in the metadata for the binary encoding of - /// + /// Name of key in the metadata for the binary encoding of . /// public const string StatusDetailsTrailerName = "grpc-status-details-bin"; /// - /// Get the from the metadata. + /// Get from the metadata with the grpc-status-details-bin key. /// Note: experimental API that can change or be removed without any prior notice. /// - /// - /// if true then null is returned on a parsing error, - /// otherwise - /// will be thrown if the metadata cannot be parsed. + /// The metadata. + /// If true then is returned on a parsing error, + /// otherwise an error will be thrown if the metadata cannot be parsed. /// - /// The found or null if it was + /// The or if grpc-status-details-bin was /// not present or could the data could not be parsed. /// public static Google.Rpc.Status? GetRpcStatus(this Metadata metadata, bool ignoreParseError = false) @@ -61,12 +59,12 @@ public static class MetadataExtensions } /// - /// Add to the metadata. - /// Any existing status in the metadata will be overwritten. + /// Add to the metadata with the grpc-status-details-bin key. + /// An existing status in the metadata will be overwritten. /// Note: experimental API that can change or be removed without any prior notice. /// - /// - /// Status to add + /// The metadata. + /// The status to add. public static void SetRpcStatus(this Metadata metadata, Google.Rpc.Status status) { ArgumentNullThrowHelper.ThrowIfNull(metadata); diff --git a/src/Grpc.StatusProto/RpcExceptionExtensions.cs b/src/Grpc.StatusProto/RpcExceptionExtensions.cs index 5a7cfa3f1..16d5123d0 100644 --- a/src/Grpc.StatusProto/RpcExceptionExtensions.cs +++ b/src/Grpc.StatusProto/RpcExceptionExtensions.cs @@ -17,7 +17,7 @@ namespace Grpc.Core; /// -/// Extensions to for handling rich error model. +/// Extension methods for getting from . /// public static class RpcExceptionExtensions { @@ -26,7 +26,7 @@ public static class RpcExceptionExtensions /// from the trailers in an , if present. /// Note: experimental API that can change or be removed without any prior notice. /// - /// The RPC exception to retrieve details from. Must not be null. + /// The to retrieve details from. Must not be null. /// The message specified in the exception, or null /// if there is no such information. public static Google.Rpc.Status? GetRpcStatus(this RpcException ex) diff --git a/src/Grpc.StatusProto/RpcStatusExtensions.cs b/src/Grpc.StatusProto/RpcStatusExtensions.cs index a3c8efd6a..4d90ce034 100644 --- a/src/Grpc.StatusProto/RpcStatusExtensions.cs +++ b/src/Grpc.StatusProto/RpcStatusExtensions.cs @@ -17,38 +17,40 @@ namespace Grpc.Core; /// -/// Extensions for to retrieve detailed error information. -/// Based on ideas from: -/// https://github.com/googleapis/gax-dotnet/blob/main/Google.Api.Gax.Grpc/RpcExceptionExtensions.cs +/// Extensions methods for converting to . /// public static class RpcStatusExtensions { /// - /// Create a from the + /// Create a from the . /// Note: experimental API that can change or be removed without any prior notice. /// /// /// - /// The and in the - /// within the exception are populated from the details in the - /// + /// The and on + /// within the exception are populated from the details from + /// . /// /// /// /// Example: /// - /// throw new Google.Rpc.Status { - /// Code = (int) StatusCode.NotFound, - /// Message = "Simple error message", - /// Details = { - /// Any.Pack(new ErrorInfo { Domain = "example", Reason = "some reason" }) - /// } - /// }.ToRpcException(); + /// var status = new Google.Rpc.Status + /// { + /// Code = (int) StatusCode.NotFound, + /// Message = "Simple error message", + /// Details = + /// { + /// Any.Pack(new ErrorInfo { Domain = "example", Reason = "some reason" }) + /// } + /// }; + /// + /// throw status.ToRpcException(); /// /// /// /// - /// The RPC status. Must not be null + /// The . Must not be null /// A populated with the details from the status. public static RpcException ToRpcException(this Google.Rpc.Status status) { @@ -66,12 +68,12 @@ public static RpcException ToRpcException(this Google.Rpc.Status status) // // Check here that we can convert Google.Rpc.Status.Code to Grpc.Core.StatusCode, // and if not use StatusCode.Unknown. - var statusCode = System.Enum.IsDefined(typeof(StatusCode), status.Code) ? (StatusCode)status.Code : StatusCode.Unknown; + var statusCode = Enum.IsDefined(typeof(StatusCode), status.Code) ? (StatusCode)status.Code : StatusCode.Unknown; return status.ToRpcException(statusCode, status.Message); } /// - /// Create a from the + /// Create a from the . /// Note: experimental API that can change or be removed without any prior notice. /// /// @@ -84,29 +86,31 @@ public static RpcException ToRpcException(this Google.Rpc.Status status) /// /// Example: /// - /// throw new Google.Rpc.Status { - /// Code = (int) StatusCode.NotFound, - /// Message = "Simple error message", - /// Details = { - /// Any.Pack(new ErrorInfo { Domain = "example", Reason = "some reason" }) - /// } - /// }.ToRpcException(StatusCode.NotFound, "status message"); + /// var status = new Google.Rpc.Status + /// { + /// Code = (int) StatusCode.NotFound, + /// Message = "Simple error message", + /// Details = + /// { + /// Any.Pack(new ErrorInfo { Domain = "example", Reason = "some reason" }) + /// } + /// }; + /// + /// throw status.ToRpcException(StatusCode.NotFound, "status message"); /// /// /// /// - /// - /// The status to set in the contained - /// The details to set in the contained - /// + /// The . Must not be null + /// The status to set in the exception's + /// The details to set in the exception's + /// A populated with the details from the status. public static RpcException ToRpcException(this Google.Rpc.Status status, StatusCode statusCode, string message) { ArgumentNullThrowHelper.ThrowIfNull(status); var metadata = new Metadata(); metadata.SetRpcStatus(status); - return new RpcException( - new Grpc.Core.Status(statusCode, message), - metadata); + return new RpcException(new Status(statusCode, message), metadata); } } From 9707fc6a81381d052a4937d9f4fcc7dc49299b89 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Thu, 4 Jan 2024 12:10:56 +0800 Subject: [PATCH 2/2] Add to nuget script --- kokoro/build_nuget.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/kokoro/build_nuget.sh b/kokoro/build_nuget.sh index cd1e16fd2..aac444588 100755 --- a/kokoro/build_nuget.sh +++ b/kokoro/build_nuget.sh @@ -46,4 +46,5 @@ build/expand_dev_version.sh (cd src/Grpc.AspNetCore && dotnet pack --configuration Release --output ../../artifacts -p:ContinuousIntegrationBuild=true) (cd src/Grpc.AspNetCore.Web && dotnet pack --configuration Release --output ../../artifacts -p:ContinuousIntegrationBuild=true) (cd src/Grpc.AspNetCore.HealthChecks && dotnet pack --configuration Release --output ../../artifacts -p:ContinuousIntegrationBuild=true) +(cd src/Grpc.StatusProto && dotnet pack --configuration Release --output ../../artifacts -p:ContinuousIntegrationBuild=true) (cd src/dotnet-grpc && dotnet pack --configuration Release --output ../../artifacts -p:ContinuousIntegrationBuild=true)