1 #region Copyright notice and license 2 // Protocol Buffers - Google's data interchange format 3 // Copyright 2016 Google Inc. All rights reserved. 4 // 5 // Use of this source code is governed by a BSD-style 6 // license that can be found in the LICENSE file or at 7 // https://developers.google.com/open-source/licenses/bsd 8 #endregion 9 10 namespace Google.Protobuf 11 { 12 /// <summary> 13 /// A message type that has a custom string format for diagnostic purposes. 14 /// </summary> 15 /// <remarks> 16 /// <para> 17 /// Calling <see cref="object.ToString"/> on a generated message type normally 18 /// returns the JSON representation. If a message type implements this interface, 19 /// then the <see cref="ToDiagnosticString"/> method will be called instead of the regular 20 /// JSON formatting code, but only when <c>ToString()</c> is called either on the message itself 21 /// or on another message which contains it. This does not affect the normal JSON formatting of 22 /// the message. 23 /// </para> 24 /// <para> 25 /// For example, if you create a proto message representing a GUID, the internal 26 /// representation may be a <c>bytes</c> field or four <c>fixed32</c> fields. However, when debugging 27 /// it may be more convenient to see a result in the same format as <see cref="System.Guid"/> provides. 28 /// </para> 29 /// <para>This interface extends <see cref="IMessage"/> to avoid it accidentally being implemented 30 /// on types other than messages, where it would not be used by anything in the framework.</para> 31 /// </remarks> 32 public interface ICustomDiagnosticMessage : IMessage 33 { 34 /// <summary> 35 /// Returns a string representation of this object, for diagnostic purposes. 36 /// </summary> 37 /// <remarks> 38 /// This method is called when a message is formatted as part of a <see cref="object.ToString"/> 39 /// call. It does not affect the JSON representation used by <see cref="JsonFormatter"/> other than 40 /// in calls to <see cref="JsonFormatter.ToDiagnosticString(IMessage)"/>. While it is recommended 41 /// that the result is valid JSON, this is never assumed by the Protobuf library. 42 /// </remarks> 43 /// <returns>A string representation of this object, for diagnostic purposes.</returns> ToDiagnosticString()44 string ToDiagnosticString(); 45 } 46 } 47