Método System.Object.ToString

Este artigo fornece observações complementares à documentação de referência para esta API.

Object.ToString é um método de formatação comum no .NET. Ele converte um objeto em sua representação de cadeia de caracteres para que ele seja adequado para exibição. (Para obter informações sobre suporte à formatação no .NET, consulte Tipos de formatação.) As implementações padrão do método Object.ToString retornam o nome totalmente qualificado do tipo do objeto.

Os tipos frequentemente substituem o método Object.ToString para fornecer uma representação de cadeia de caracteres mais adequada de um tipo específico. Os tipos também frequentemente sobrecarregam o método Object.ToString para fornecer suporte a cadeias de formato ou formatação sensível à cultura.

O método padrão Object.ToString()

A implementação padrão do método ToString retorna o nome totalmente qualificado do tipo do Object, como mostra o exemplo a seguir.

Object obj = new Object();
Console.WriteLine(obj.ToString());

// The example displays the following output:
//      System.Object

let obj = obj ()
printfn $"{obj.ToString()}"
// printfn $"{obj}" // Equivalent

// The example displays the following output:
//      System.Object

Module Example3
    Public Sub Main()
        Dim obj As New Object()
        Console.WriteLine(obj.ToString())
    End Sub
End Module
' The example displays the following output:
'      System.Object

Como Object é a classe base de todos os tipos de referência no .NET, esse comportamento é herdado por tipos de referência que não substituem o método ToString. O exemplo a seguir ilustra isso. Ele define uma classe chamada Object1 que aceita a implementação padrão de todos os membros Object. Seu método ToString retorna o nome de tipo totalmente qualificado do objeto.

using System;
using Examples;

namespace Examples
{
   public class Object1
   {
   }
}

public class Example5
{
   public static void Main()
   {
      object obj1 = new Object1();
      Console.WriteLine(obj1.ToString());
   }
}
// The example displays the following output:
//   Examples.Object1

type Object1() = class end

let obj1 = Object1()
printfn $"{obj1.ToString()}"
// The example displays the following output:
//   Examples.Object1

Public Class Object1
End Class

Module Example4
    Public Sub Main()
        Dim obj1 As New Object1()
        Console.WriteLine(obj1.ToString())
    End Sub
End Module
' The example displays the following output:
'   Examples.Object1

Sobrescrever o método Object.ToString()

Os tipos geralmente substituem o método Object.ToString para retornar uma cadeia de caracteres que representa a ocorrência do objeto. Por exemplo, os tipos base como Char, Int32e String fornecem implementações ToString que retornam a forma de cadeia de caracteres do valor que o objeto representa. O exemplo a seguir define uma classe, Object2, que substitui o método ToString para retornar o nome do tipo junto com seu valor.

using System;

public class Object2
{
   private object value;

   public Object2(object value)
   {
      this.value = value;
   }

   public override string ToString()
   {
      return base.ToString() + ": " + value.ToString();
   }
}

public class Example6
{
   public static void Main()
   {
      Object2 obj2 = new Object2('a');
      Console.WriteLine(obj2.ToString());
   }
}
// The example displays the following output:
//       Object2: a

type Object2(value: obj) =
    inherit obj ()
    override _.ToString() =
        base.ToString() + ": " + value.ToString()

let obj2 = Object2 'a'
printfn $"{obj2.ToString()}"
// The example displays the following output:
//       Object2: a

Public Class Object2
   Private value As Object
   
   Public Sub New(value As Object)
      Me.value = value
   End Sub
   
   Public Overrides Function ToString() As String
      Return MyBase.ToString + ": " + value.ToString()
   End Function
End Class

Module Example5
    Public Sub Main()
        Dim obj2 As New Object2("a"c)
        Console.WriteLine(obj2.ToString())
    End Sub
End Module
' The example displays the following output:
'       Object2: a

A tabela a seguir lista as categorias de tipo no .NET e indica se elas substituem ou não o método Object.ToString.

Consulte a seção Notas aos herdeiros para obter informações adicionais sobre a substituição de ToString.

Sobrecarregar o método ToString

Além de substituir o método Object.ToString() sem parâmetros, muitos tipos sobrecarregam o método ToString para fornecer versões do método que aceitam parâmetros. Mais comumente, isso é feito para fornecer suporte para formatação variável e formatação sensível à cultura.

O exemplo a seguir sobrecarrega o método ToString para retornar uma cadeia de caracteres de resultado que inclui o valor de vários campos de uma classe Automobile. Ele define quatro cadeias de caracteres de formato: G, que retorna o nome do modelo e o ano; D, que devolve o nome do modelo, o ano e o número de portas; C, que devolve o nome do modelo, o ano e o número de cilindros; e A, que retorna uma cadeia de caracteres com todos os quatro valores de campo.

using System;

public class Automobile
{
   private int _doors;
   private string _cylinders;
   private int _year;
   private string _model;

   public Automobile(string model, int year , int doors,
                     string cylinders)
   {
      _model = model;
      _year = year;
      _doors = doors;
      _cylinders = cylinders;
   }

   public int Doors
   { get { return _doors; } }

   public string Model
   { get { return _model; } }

   public int Year
   { get { return _year; } }

   public string Cylinders
   { get { return _cylinders; } }

   public override string ToString()
   {
      return ToString("G");
   }

   public string ToString(string fmt)
   {
      if (string.IsNullOrEmpty(fmt))
         fmt = "G";

      switch (fmt.ToUpperInvariant())
      {
         case "G":
            return string.Format("{0} {1}", _year, _model);
         case "D":
            return string.Format("{0} {1}, {2} dr.",
                                 _year, _model, _doors);
         case "C":
            return string.Format("{0} {1}, {2}",
                                 _year, _model, _cylinders);
         case "A":
            return string.Format("{0} {1}, {2} dr. {3}",
                                 _year, _model, _doors, _cylinders);
         default:
            string msg = string.Format("'{0}' is an invalid format string",
                                       fmt);
            throw new ArgumentException(msg);
      }
   }
}

public class Example7
{
   public static void Main()
   {
      var auto = new Automobile("Lynx", 2016, 4, "V8");
      Console.WriteLine(auto.ToString());
      Console.WriteLine(auto.ToString("A"));
   }
}
// The example displays the following output:
//       2016 Lynx
//       2016 Lynx, 4 dr. V8

open System

type Automobile(model: string, year: int, doors: int, cylinders: string) =
    member _.Doors = doors
    member _.Model = model
    member _.Year = year
    member _.Cylinders = cylinders

    override this.ToString() =
        this.ToString "G"

    member _.ToString(fmt) =
        let fmt = 
            if String.IsNullOrEmpty fmt then "G"
            else fmt.ToUpperInvariant()

        match fmt with
        | "G" ->
            $"{year} {model}"
        | "D" ->
            $"{year} {model}, {doors} dr."
        | "C" ->
            $"{year} {model}, {cylinders}"
        | "A" ->
            $"{year} {model}, {doors} dr. {cylinders}"
        | _ ->
            raise (ArgumentException $"'{fmt}' is an invalid format string")

let auto = Automobile("Lynx", 2016, 4, "V8")
printfn $"{auto}"
printfn $"""{auto.ToString "A"}"""
// The example displays the following output:
//       2016 Lynx
//       2016 Lynx, 4 dr. V8

Public Class Automobile
   Private _doors As Integer
   Private _cylinders As String
   Private _year As Integer
   Private _model As String
   
   Public Sub New(model As String, year As Integer, doors As Integer,
                  cylinders As String)
      _model = model
      _year = year
      _doors = doors
      _cylinders = cylinders
   End Sub
   
   Public ReadOnly Property Doors As Integer
      Get
          Return _doors
      End Get
   End Property
   
   Public ReadOnly Property Model As String
      Get
         Return _model
      End Get
   End Property
   
   Public ReadOnly Property Year As Integer
      Get
         Return _year
      End Get
   End Property
   
   Public ReadOnly Property Cylinders As String
      Get
         Return _cylinders
      End Get
   End Property
   
   Public Overrides Function ToString() As String
      Return ToString("G")
   End Function
   
   Public Overloads Function ToString(fmt As String) As String
      If String.IsNullOrEmpty(fmt) Then fmt = "G"
      
      Select Case fmt.ToUpperInvariant()
         Case "G"
            Return String.Format("{0} {1}", _year, _model)
         Case "D"
            Return String.Format("{0} {1}, {2} dr.",
                                 _year, _model, _doors)
         Case "C"
            Return String.Format("{0} {1}, {2}",
                                 _year, _model, _cylinders)
         Case "A"
            Return String.Format("{0} {1}, {2} dr. {3}",
                                 _year, _model, _doors, _cylinders)
         Case Else
            Dim msg As String = String.Format("'{0}' is an invalid format string",
                                              fmt)
            Throw New ArgumentException(msg)
      End Select
   End Function
End Class

Module Example6
    Public Sub Main()
        Dim auto As New Automobile("Lynx", 2016, 4, "V8")
        Console.WriteLine(auto.ToString())
        Console.WriteLine(auto.ToString("A"))
    End Sub
End Module
' The example displays the following output:
'       2016 Lynx
'       2016 Lynx, 4 dr. V8

O exemplo a seguir invoca o método sobrecarregado Decimal.ToString(String, IFormatProvider) para apresentar a formatação adaptada à cultura de um valor monetário.

using System;
using System.Globalization;

public class Example8
{
   public static void Main()
   {
      string[] cultureNames = { "en-US", "en-GB", "fr-FR",
                                "hr-HR", "ja-JP" };
      Decimal value = 1603.49m;
      foreach (var cultureName in cultureNames) {
         CultureInfo culture = new CultureInfo(cultureName);
         Console.WriteLine($"{culture.Name}: {value.ToString("C2", culture)}");
      }
   }
}
// The example displays the following output:
//       en-US: $1,603.49
//       en-GB: £1,603.49
//       fr-FR: 1 603,49 €
//       hr-HR: 1.603,49 kn
//       ja-JP: ¥1,603.49

open System.Globalization

let cultureNames =
    [| "en-US"; "en-GB"; "fr-FR"; "hr-HR"; "ja-JP" |]
let value = 1603.49m
for cultureName in cultureNames do
    let culture = CultureInfo cultureName
    printfn $"""{culture.Name}: {value.ToString("C2", culture)}"""
// The example displays the following output:
//       en-US: $1,603.49
//       en-GB: £1,603.49
//       fr-FR: 1 603,49 €
//       hr-HR: 1.603,49 kn
//       ja-JP: ¥1,603.49

Imports System.Globalization

Module Example7
    Public Sub Main()
        Dim cultureNames() As String = {"en-US", "en-GB", "fr-FR",
                                       "hr-HR", "ja-JP"}
        Dim value As Decimal = 1603.49D
        For Each cultureName In cultureNames
            Dim culture As New CultureInfo(cultureName)
            Console.WriteLine("{0}: {1}", culture.Name,
                           value.ToString("C2", culture))
        Next
    End Sub
End Module
' The example displays the following output:
'       en-US: $1,603.49
'       en-GB: £1,603.49
'       fr-FR: 1 603,49 €
'       hr-HR: 1.603,49 kn
'       ja-JP: ¥1,603.49

Para obter mais informações sobre cadeias de caracteres de formato e formatação sensível à cultura, consulte Tipos de formatação. Para obter as cadeias de caracteres de formato suportadas por valores numéricos, consulte Cadeias de caracteres de formato numérico padrão e Cadeias de caracteres de formato numérico personalizado. Para obter as cadeias de caracteres de formato suportadas por valores de data e hora, consulte Cadeias de caracteres de formato de data e hora padrão e Cadeias de caracteres de formato de data e hora personalizadas.

Estender o método Object.ToString

Como um tipo herda o método Object.ToString padrão, você pode achar seu comportamento indesejável e querer alterá-lo. Isso é particularmente verdadeiro para matrizes e classes de coleções. Embora você possa esperar que o método ToString de uma matriz ou classe de coleção exiba os valores de seus membros, em vez disso, ele exibe o nome do tipo totalmente qualificado, como mostra o exemplo a seguir.

int[] values = { 1, 2, 4, 8, 16, 32, 64, 128 };
Console.WriteLine(values.ToString());

List<int> list = new List<int>(values);
Console.WriteLine(list.ToString());

// The example displays the following output:
//       System.Int32[]
//       System.Collections.Generic.List`1[System.Int32]

let values = [| 1; 2; 4; 8; 16; 32; 64; 128 |]
printfn $"{values}"

let list = ResizeArray values
printfn $"{list}"

// The example displays the following output:
//       System.Int32[]
//       System.Collections.Generic.List`1[System.Int32]

Imports System.Collections.Generic

Module Example
   Public Sub Main()
      Dim values() As Integer = { 1, 2, 4, 8, 16, 32, 64, 128 }
      Console.WriteLine(values.ToString())
      
      Dim list As New List(Of Integer)(values)
      Console.WriteLine(list.ToString())
   End Sub
End Module
' The example displays the following output:
'    System.Int32[]
'    System.Collections.Generic.List`1[System.Int32]

Você tem várias opções para produzir a string de resultados pretendida.

• Se o tipo for uma matriz, um objeto de coleção ou um objeto que implementa as interfaces IEnumerable ou IEnumerable<T>, você pode enumerar seus elementos usando a instrução foreach em C# ou a construção For Each...Next no Visual Basic.

• Se a classe não for sealed (em C#) ou NotInheritable (em Visual Basic), você poderá desenvolver uma classe wrapper que herda da classe base cujo método Object.ToString você deseja personalizar. No mínimo, isso requer que você faça o seguinte:

  1. Implemente todos os construtores necessários. As classes derivadas não herdam seus construtores de classe base.
  2. Substitua o método Object.ToString para retornar a cadeia de caracteres de resultado desejada.

  O exemplo a seguir define uma classe wrapper para a classe List<T>. Ele substitui o método Object.ToString para exibir o valor de cada método da coleção em vez do nome do tipo totalmente qualificado.

  using System;
  using System.Collections.Generic;
  
  public class CList<T> : List<T>
  {
     public CList(IEnumerable<T> collection) : base(collection)
     { }
  
     public CList() : base()
     {}
  
     public override string ToString()
     {
        string retVal = string.Empty;
        foreach (T item in this) {
           if (string.IsNullOrEmpty(retVal))
              retVal += item.ToString();
           else
              retVal += string.Format(", {0}", item);
        }
        return retVal;
     }
  }
  
  public class Example2
  {
     public static void Main()
     {
        var list2 = new CList<int>();
        list2.Add(1000);
        list2.Add(2000);
        Console.WriteLine(list2.ToString());
     }
  }
  // The example displays the following output:
  //    1000, 2000
  

  open System
  open System.Collections.Generic
  
  type CList<'T>() = 
      inherit ResizeArray<'T>()
      
      override this.ToString() =
          let mutable retVal = String.Empty
          for item in this do
              if String.IsNullOrEmpty retVal then
                  retVal <- retVal + string item
              else
                  retVal <- retVal + $", {item}"
          retVal
  
  let list2 = CList()
  list2.Add 1000
  list2.Add 2000
  printfn $"{list2}"
  // The example displays the following output:
  //    1000, 2000
  

  Imports System.Collections.Generic
  
  Public Class CList(Of T) : Inherits List(Of T)
     Public Sub New(capacity As Integer)
        MyBase.New(capacity)
     End Sub
  
     Public Sub New(collection As IEnumerable(Of T))
        MyBase.New(collection)
     End Sub
  
     Public Sub New()
        MyBase.New()
     End Sub
  
     Public Overrides Function ToString() As String
        Dim retVal As String = String.Empty
        For Each item As T In Me
           If String.IsNullOrEmpty(retval) Then
              retVal += item.ToString()
           Else
              retval += String.Format(", {0}", item)
           End If
        Next
        Return retVal
     End Function
  End Class
  
  Module Example1
      Public Sub Main()
          Dim list2 As New CList(Of Integer)
          list2.Add(1000)
          list2.Add(2000)
          Console.WriteLine(list2.ToString())
      End Sub
  End Module
  ' The example displays the following output:
  '       1000, 2000
  

• Desenvolva um método de extensão que retorna a cadeia de caracteres de resultado desejada. Observe que você não pode substituir o método Object.ToString padrão dessa maneira, ou seja, sua classe de extensão (em C#) ou módulo (em Visual Basic) não pode ter um método sem parâmetros chamado ToString que é chamado no lugar do método ToString do tipo original. Você terá que fornecer algum outro nome para sua substituição de ToString sem parâmetros.

  O exemplo a seguir define dois métodos que estendem a classe List<T>: um método ToString2 sem parâmetros e um método ToString com um parâmetro String que representa uma cadeia de caracteres de formato.

  using System;
  using System.Collections.Generic;
  
  public static class StringExtensions
  {
     public static string ToString2<T>(this List<T> l)
     {
        string retVal = string.Empty;
        foreach (T item in l)
           retVal += string.Format("{0}{1}", string.IsNullOrEmpty(retVal) ?
                                                       "" : ", ",
                                    item);
        return string.IsNullOrEmpty(retVal) ? "{}" : "{ " + retVal + " }";
     }
  
     public static string ToString<T>(this List<T> l, string fmt)
     {
        string retVal = string.Empty;
        foreach (T item in l) {
           IFormattable ifmt = item as IFormattable;
           if (ifmt != null)
              retVal += string.Format("{0}{1}",
                                      string.IsNullOrEmpty(retVal) ?
                                         "" : ", ", ifmt.ToString(fmt, null));
           else
              retVal += ToString2(l);
        }
        return string.IsNullOrEmpty(retVal) ? "{}" : "{ " + retVal + " }";
     }
  }
  
  public class Example3
  {
     public static void Main()
     {
        List<int> list = new List<int>();
        list.Add(1000);
        list.Add(2000);
        Console.WriteLine(list.ToString2());
        Console.WriteLine(list.ToString("N0"));
     }
  }
  // The example displays the following output:
  //       { 1000, 2000 }
  //       { 1,000, 2,000 }
  

  open System
  open System.Collections.Generic
  
  type List<'T> with
      member this.ToString2<'T>() = 
          let mutable retVal = String.Empty
          for item in this do
             retVal <- retVal + $"""{if String.IsNullOrEmpty retVal then "" else ", "}{item}"""
          if String.IsNullOrEmpty retVal then "{}" else "{ " + retVal + " }"
  
      member this.ToString<'T>(fmt: string) =
          let mutable retVal = String.Empty
          for item in this do
              match box item with
              | :? IFormattable as ifmt ->
                  retVal <- retVal + $"""{if String.IsNullOrEmpty retVal then "" else ", "}{ifmt.ToString(fmt, null)}"""
              | _ ->
                  retVal <- retVal + this.ToString2()
          if String.IsNullOrEmpty retVal then "{}" else "{ " + retVal + " }"
  
  let list = ResizeArray()
  list.Add 1000
  list.Add 2000
  printfn $"{list.ToString2()}"
  printfn $"""{list.ToString "N0"}"""
  // The example displays the following output:
  //       { 1000, 2000 }
  //       { 1,000, 2,000 }
  

  Imports System.Collections.Generic
  Imports System.Runtime.CompilerServices
  
  Public Module StringExtensions
     <Extension()>
     Public Function ToString2(Of T)(l As List(Of T)) As String
        Dim retVal As String = ""
        For Each item As T In l
           retVal += String.Format("{0}{1}", If(String.IsNullOrEmpty(retVal),
                                                       "", ", "),
                                    item)
        Next
        Return If(String.IsNullOrEmpty(retVal), "{}", "{ " + retVal + " }")
     End Function
  
     <Extension()>
     Public Function ToString(Of T)(l As List(Of T), fmt As String) As String
        Dim retVal As String = String.Empty
        For Each item In l
           Dim ifmt As IFormattable = TryCast(item, IFormattable)
           If ifmt IsNot Nothing Then
              retVal += String.Format("{0}{1}",
                                      If(String.IsNullOrEmpty(retval),
                                         "", ", "), ifmt.ToString(fmt, Nothing))
           Else
              retVal += ToString2(l)
           End If
        Next
        Return If(String.IsNullOrEmpty(retVal), "{}", "{ " + retVal + " }")
     End Function
  End Module
  
  Module Example2
      Public Sub Main()
          Dim list As New List(Of Integer)
          list.Add(1000)
          list.Add(2000)
          Console.WriteLine(list.ToString2())
          Console.WriteLine(list.ToString("N0"))
      End Sub
  End Module
  ' The example displays the following output:
  '       { 1000, 2000 }
  '       { 1,000, 2,000 }
  

Notas para o Tempo de Execução do Windows

Quando você chama o método ToString em uma classe no Tempo de Execução do Windows, ele fornece o comportamento padrão para classes que não substituem ToString. Isso faz parte do suporte que o .NET fornece para o Windows Runtime (consulte Suporte do .NET para aplicações da Windows Store epara o Windows Runtime). As classes no Tempo de Execução do Windows não herdam Objecte nem sempre implementam um ToString. No entanto, eles parecem sempre ter os métodos ToString, Equals(Object)e GetHashCode quando utilizados no teu código C# ou Visual Basic, e o .NET fornece um comportamento predefinido para estes métodos.

O Common Language Runtime usa IStringable.ToString em um objeto do Tempo de Execução do Windows antes de voltar para a implementação padrão do Object.ToString.

O Tempo de Execução do Windows e a interface IStringable

O Tempo de Execução do Windows inclui uma interface IStringable cujo único método, IStringable.ToString, fornece suporte básico de formatação comparável ao fornecido por Object.ToString. Para evitar ambiguidade, você não deve implementar IStringable em tipos gerenciados.

Quando os objetos gerenciados são chamados por código nativo ou por código escrito em linguagens como JavaScript ou C++/CX, eles parecem implementar IStringable. O Common Language Runtime roteia automaticamente chamadas de IStringable.ToString para Object.ToString se IStringable não for implementado no objeto gerido.

Se optar por implementar IStringable em um tipo gerido público exportado num componente do Windows Runtime, as seguintes restrições aplicam-se:

• Você pode definir a interface IStringable somente em uma relação "class implements", da seguinte maneira:

  public class NewClass : IStringable
  

  Public Class NewClass : Implements IStringable
  

• Não é possível implementar IStringable numa interface.

• Não é possível declarar um parâmetro do tipo IStringable.

• IStringable não pode ser o tipo de retorno de um método, propriedade ou campo.

• Você não pode ocultar sua implementação IStringable de classes base usando uma definição de método como a seguinte:

  public class NewClass : IStringable
  {
     public new string ToString()
     {
        return "New ToString in NewClass";
     }
  }
  

  Em vez disso, a implementação de IStringable.ToString deve sempre substituir a implementação da classe base. Você pode ocultar uma implementação de ToString somente invocando-a em uma instância de classe com tipagem forte.

Sob uma variedade de condições, chamadas de código nativo para um tipo gerido que implementa IStringable ou oculta a sua implementação de ToString podem produzir um comportamento inesperado.