Este artigo foi traduzido por máquina. Para visualizar o arquivo em inglês, marque a caixa de seleção Inglês. Você também pode exibir o texto Em inglês em uma janela pop-up, movendo o ponteiro do mouse sobre o texto.
Tradução
Inglês

Classe IndexOutOfRangeException

 
System_CAPS_noteObservação

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

A exceção gerada quando ocorre uma tentativa de acessar um elemento de uma matriz ou coleção com um índice que está fora dos limites.

Namespace:   System
Assembly:  mscorlib (em mscorlib.dll)

System.Object
  System.Exception
    System.SystemException
      System.IndexOutOfRangeException

[SerializableAttribute]
[ComVisibleAttribute(true)]
public sealed class IndexOutOfRangeException : SystemException

NomeDescrição
System_CAPS_pubmethodIndexOutOfRangeException()

Inicializa uma nova instância da classe IndexOutOfRangeException.

System_CAPS_pubmethodIndexOutOfRangeException(String)

Inicializa uma nova instância da classe IndexOutOfRangeException com uma mensagem de erro especificada.

System_CAPS_pubmethodIndexOutOfRangeException(String, Exception)

Inicializa uma nova instância da classe IndexOutOfRangeException com uma mensagem de erro especificada e uma referência à exceção interna que é a causa da exceção.

NomeDescrição
System_CAPS_pubpropertyData

Obtém uma coleção de pares de chave/valor que fornecem informações adicionais definidas pelo usuário sobre a exceção.(Herdado de Exception.)

System_CAPS_pubpropertyHelpLink

Obtém ou define um link para o arquivo de ajuda associado a essa exceção.(Herdado de Exception.)

System_CAPS_pubpropertyHResult

Obtém ou define HRESULT, um valor numérico codificado que é atribuído a uma exceção específica.(Herdado de Exception.)

System_CAPS_pubpropertyInnerException

Obtém a instância Exception que causou a exceção atual.(Herdado de Exception.)

System_CAPS_pubpropertyMessage

Obtém uma mensagem que descreve a exceção atual.(Herdado de Exception.)

System_CAPS_pubpropertySource

Obtém ou define o nome do aplicativo ou objeto que causa o erro.(Herdado de Exception.)

System_CAPS_pubpropertyStackTrace

Obtém uma representação de cadeia de caracteres de quadros imediatos na pilha de chamadas.(Herdado de Exception.)

System_CAPS_pubpropertyTargetSite

Obtém o método que gerou a exceção atual.(Herdado de Exception.)

NomeDescrição
System_CAPS_pubmethodEquals(Object)

Determina se o objeto especificado é igual ao objeto atual.(Herdado de Object.)

System_CAPS_pubmethodGetBaseException()

Quando substituído em uma classe derivada, retorna a Exception que é a causa raiz de uma ou mais exceções subsequentes.(Herdado de Exception.)

System_CAPS_pubmethodGetHashCode()

Serve como a função de hash padrão.(Herdado de Object.)

System_CAPS_pubmethodGetObjectData(SerializationInfo, StreamingContext)

Quando substituído em uma classe derivada, define o SerializationInfo com informações sobre a exceção.(Herdado de Exception.)

System_CAPS_pubmethodGetType()

Obtém o tipo de tempo de execução da instância atual.(Herdado de Exception.)

System_CAPS_pubmethodToString()

Cria e retorna uma representação de cadeia de caracteres da exceção atual.(Herdado de Exception.)

Um IndexOutOfRangeException exceção é lançada quando um índice inválido é usado para acessar um membro de uma matriz ou uma coleção, ou de leitura ou gravação de um local específico em um buffer. Essa exceção herda o Exception classe mas não adiciona nenhum membro exclusivo.

Normalmente, um IndexOutOfRangeException exceção é gerada como resultado de erro do desenvolvedor. Em vez de tratamento de exceção, você deve diagnosticar a causa do erro e corrigir seu código. As causas mais comuns do erro são:

  • Esquecer que o limite superior de uma coleção ou uma matriz com base em zero é um menor do que o número de membros ou elementos, como o exemplo a seguir ilustra.

    using System;
    using System.Collections.Generic;
    
    public class Example
    {
       public static void Main()
       {
          List<Char> characters = new List<Char>();
          characters.InsertRange(0, new Char[] { 'a', 'b', 'c', 'd', 'e', 'f' } );
          for (int ctr = 0; ctr <= characters.Count; ctr++)
             Console.Write("'{0}'    ", characters[ctr]);
       }
    }
    // The example displays the following output:
    //    'a'    'b'    'c'    'd'    'e'    'f'
    //    Unhandled Exception: 
    //    System.ArgumentOutOfRangeException: 
    //    Index was out of range. Must be non-negative and less than the size of the collection.
    //    Parameter name: index
    //       at Example.Main()
    

    Para corrigir o erro, você pode usar código semelhante ao seguinte.

    using System;
    using System.Collections.Generic;
    
    public class Example
    {
       public static void Main()
       {
          List<Char> characters = new List<Char>();
          characters.InsertRange(0, new Char[] { 'a', 'b', 'c', 'd', 'e', 'f' } );
          for (int ctr = 0; ctr < characters.Count; ctr++)
             Console.Write("'{0}'    ", characters[ctr]);
       }
    }
    // The example displays the following output:
    //        'a'    'b'    'c'    'd'    'e'    'f'
    

    Como alternativa, em vez de iteração de todos os elementos na matriz por seu índice, você pode usar o (em c#) ou (no Visual Basic).

  • Tentativa de atribuir um elemento de matriz a outra matriz que não foi dimensionada corretamente e que tem menos elementos da matriz original. O exemplo a seguir tenta atribuir o último elemento o value1 matriz para o mesmo elemento de value2 matriz. No entanto, o value2 matriz foi dimensionada incorretamente para ter seis em vez de sete elementos. Como resultado, a atribuição lança um IndexOutOfRangeException exceção.

    public class Example
    {
       public static void Main()
       {
          int[] values1 = { 3, 6, 9, 12, 15, 18, 21 };
          int[] values2 = new int[6];
    
          // Assign last element of the array to the new array.
          values2[values1.Length - 1] = values1[values1.Length - 1];
       }
    }
    // The example displays the following output:
    //       Unhandled Exception: 
    //       System.IndexOutOfRangeException: 
    //       Index was outside the bounds of the array.
    //       at Example.Main()
    
  • Usando um valor retornado por um método de pesquisa a uma parte de uma matriz ou coleção começando na posição de um determinado índice de iteração. Se você se esqueça de verificar se a operação de pesquisa encontrada uma correspondência, o tempo de execução lança um IndexOutOfRangeException exceção, conforme mostrado neste exemplo.

    using System;
    using System.Collections.Generic;
    
    public class Example
    {
       static List<int> numbers = new List<int>();
    
       public static void Main()
       {
          int startValue; 
          string[] args = Environment.GetCommandLineArgs();
          if (args.Length < 2) 
             startValue = 2;
          else 
             if (! Int32.TryParse(args[1], out startValue))
                startValue = 2;
    
          ShowValues(startValue);
       }
    
       private static void ShowValues(int startValue)
       {   
          // Create a collection with numeric values.
          if (numbers.Count == 0)  
             numbers.AddRange( new int[] { 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22} );
    
          // Get the index of a startValue.
          Console.WriteLine("Displaying values greater than or equal to {0}:",
                            startValue);
          int startIndex = numbers.IndexOf(startValue);
          // Display all numbers from startIndex on.
          for (int ctr = startIndex; ctr < numbers.Count; ctr++)
             Console.Write("    {0}", numbers[ctr]);
       }
    }
    // The example displays the following output if the user supplies
    // 7 as a command-line parameter:
    //    Displaying values greater than or equal to 7:
    //    
    //    Unhandled Exception: System.ArgumentOutOfRangeException: 
    //    Index was out of range. Must be non-negative and less than the size of the collection.
    //    Parameter name: index
    //       at System.Collections.Generic.List`1.get_Item(Int32 index)
    //       at Example.ShowValues(Int32 startValue)
    //       at Example.Main()
    

    Nesse caso, o List<T>.IndexOf método retornará -1, que é um valor de índice inválido, quando ele não consegue encontrar uma correspondência. Para corrigir esse erro, verifique o valor de retorno do método de pesquisa antes de iteração da matriz, conforme mostrado neste exemplo.

    using System;
    using System.Collections.Generic;
    
    public class Example
    {
       static List<int> numbers = new List<int>();
    
       public static void Main()
       {
          int startValue; 
          string[] args = Environment.GetCommandLineArgs();
          if (args.Length < 2) 
             startValue = 2;
          else 
             if (! Int32.TryParse(args[1], out startValue))
                startValue = 2;
    
          ShowValues(startValue);
       }
    
       private static void ShowValues(int startValue)
       {   
          // Create a collection with numeric values.
          if (numbers.Count == 0)  
             numbers.AddRange( new int[] { 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22} );
    
          // Get the index of startValue.
          int startIndex = numbers.IndexOf(startValue);
          if (startIndex < 0) {
             Console.WriteLine("Unable to find {0} in the collection.", startValue);
          }
          else {
             // Display all numbers from startIndex on.
             Console.WriteLine("Displaying values greater than or equal to {0}:",
                            startValue);
             for (int ctr = startIndex; ctr < numbers.Count; ctr++)
                Console.Write("    {0}", numbers[ctr]);
          }
       }
    }
    // The example displays the following output if the user supplies
    // 7 as a command-line parameter:
    //      Unable to find 7 in the collection.
    
  • Tentativa de usar ou enumerar um conjunto de resultados, coleção ou matriz retornada por uma consulta sem testar se o objeto retornado tem dados válidos.

  • Usando um valor calculado para definir o índice inicial, o índice final ou o número de itens a ser iterado. Se o resultado da computação for inesperado, isso pode resultar em um IndexOutOfRangeException exceção. Verifique a lógica do programa ao calcular o valor de índice e validar o valor antes da iteração de matriz ou coleção. As seguintes condições devem todas ser true; Caso contrário, um IndexOutOfRangeException exceção:

    • O índice inicial deve ser maior ou igual a Array.GetLowerBound para a dimensão da matriz que você deseja repetir, ou maior que ou igual a 0 para uma coleção.

    • O índice final não pode exceder Array.GetUpperBound para a dimensão da matriz que você deseja repetir, ou não pode ser maior que ou igual do Count propriedade de uma coleção.

    • A equação a seguir deve ser verdadeira para a dimensão da matriz que você deseja iterar:

      start_index >= lower_bound And start_index + items_to_iterate – 1 <= upper_bound
      

      Para uma coleção, a equação a seguir deve ser verdadeira:

      start_index >= 0 And start_index + items_to_iterate <= Count
      
      System_CAPS_tipDica

      O índice inicial de uma matriz ou coleção nunca pode ser um número negativo.

  • Supondo que uma matriz deve ser baseado em zero. Matrizes que não são baseadas em zero podem ser criadas, o Array.CreateInstance(Type, Int32[], Int32[]) método e pode ser retornado por interoperabilidade COM, embora eles não são compatíveis com CLS. O exemplo a seguir ilustra o IndexOutOfRangeException que é gerada quando você tentar repetir uma matriz com base zero criada por meio de Array.CreateInstance(Type, Int32[], Int32[]) método.

    using System;
    
    public class Example
    {
       public static void Main()
       {
          Array values = Array.CreateInstance(typeof(int), new int[] { 10 }, 
                                              new int[] { 1 });
          int value = 2;
          // Assign values.
          for (int ctr = 0; ctr < values.Length; ctr++) {
             values.SetValue(value, ctr);
             value *= 2;
          }
    
          // Display values.
          for (int ctr = 0; ctr < values.Length; ctr++)
             Console.Write("{0}    ", values.GetValue(ctr));
       }
    }
    // The example displays the following output:
    //    Unhandled Exception: 
    //    System.IndexOutOfRangeException: Index was outside the bounds of the array.
    //       at System.Array.InternalGetReference(Void* elemRef, Int32 rank, Int32* pIndices)
    //       at System.Array.SetValue(Object value, Int32 index)
    //       at Example.Main()
    

    Para corrigir o erro, como o exemplo a seguir, você pode chamar o GetLowerBound método em vez de fazer suposições sobre o índice inicial de uma matriz.

    using System;
    
    public class Example
    {
       public static void Main()
       {
          Array values = Array.CreateInstance(typeof(int), new int[] { 10 }, 
                                              new int[] { 1 });
          int value = 2;
          // Assign values.
          for (int ctr = values.GetLowerBound(0); ctr <= values.GetUpperBound(0); ctr++) {
             values.SetValue(value, ctr);
             value *= 2;
          }
    
          // Display values.
          for (int ctr = values.GetLowerBound(0); ctr <= values.GetUpperBound(0); ctr++)
             Console.Write("{0}    ", values.GetValue(ctr));
       }
    }
    // The example displays the following output:
    //        2    4    8    16    32    64    128    256    512    1024
    

    Observe que, quando você chamar o GetLowerBound método para obter o índice inicial de uma matriz, você também deve chamar o Array.GetUpperBound(Int32) método para obter o índice final.

  • Confuso um índice e o valor no índice em uma matriz numérica ou coleção. Este problema normalmente ocorre ao usar o foreach instrução (em c#) ou o For Each instrução (no Visual Basic). O exemplo a seguir ilustra o problema.

    using System;
    
    public class Example
    {
       public static void Main()
       {
          // Generate array of random values.
          int[] values = PopulateArray(5, 10);
          // Display each element in the array.
          foreach (var value in values)
             Console.Write("{0}   ", values[value]);
       }
    
       private static int[] PopulateArray(int items, int maxValue)
       {
          int[] values = new int[items];
          Random rnd = new Random();
          for (int ctr = 0; ctr < items; ctr++)
             values[ctr] = rnd.Next(0, maxValue + 1);   
    
          return values;                                                      
       }
    }
    // The example displays output like the following:
    //    6   4   4
    //    Unhandled Exception: System.IndexOutOfRangeException: 
    //    Index was outside the bounds of the array.
    //       at Example.Main()
    

    A construção de iteração retorna cada valor em uma matriz ou coleção, não seu índice. Para eliminar a exceção, use este código.

    using System;
    
    public class Example
    {
       public static void Main()
       {
          // Generate array of random values.
          int[] values = PopulateArray(5, 10);
          // Display each element in the array.
          foreach (var value in values)
             Console.Write("{0}   ", value);
       }
    
       private static int[] PopulateArray(int items, int maxValue)
       {
          int[] values = new int[items];
          Random rnd = new Random();
          for (int ctr = 0; ctr < items; ctr++)
             values[ctr] = rnd.Next(0, maxValue + 1);   
    
          return values;                                                      
       }
    }
    // The example displays output like the following:
    //        10   6   7   5   8
    
  • Fornecendo um nome de coluna inválido para o DataView.Sort propriedade.

  • Violação de acesso thread-safe. Operações como leitura da mesma StreamReader objeto, gravando no mesmo StreamWriter de objeto de vários threads, ou enumerar os objetos em um Hashtable de diversos threads pode lançar um IndexOutOfRangeException se o objeto não é acessado de uma forma thread-safe. Essa exceção é tipicamente intermitente porque ele se baseia em uma condição de corrida.

Usando valores de índice embutida para manipular uma matriz é provável lançar uma exceção se o valor de índice é inválido ou incorreto, ou se o tamanho da matriz que está sendo manipulação é inesperado. Para impedir que uma operação lançando um IndexOutOfRangeException exceção, você pode fazer o seguinte:

  • Iterar os elementos da matriz usando o foreach instrução (em c#) ou o For Each...Next construir (no Visual Basic) em vez de iteração elementos pelo índice.

  • Iterar os elementos por índice, começando com o índice retornado pelo Array.GetLowerBound método e terminando com o índice retornado pelo Array.GetUpperBound método.

  • Se você estiver atribuindo elementos em uma matriz a outra, verifique se a matriz de destino pelo menos o mesmo número de elementos da matriz de origem comparando seus Array.Length propriedades.

Para obter uma lista de valores de propriedade inicial para uma instância do IndexOutOfRangeException, consulte o IndexOutOfRangeException construtores.

As seguintes instruções de linguagem intermediária (IL) lançam IndexOutOfRangeException:

  • < tipo > Ldelem.

  • faltando ldelema

  • < tipo > Stelem.

IndexOutOfRangeExceptionusa o HRESULT COR_E_INDEXOUTOFRANGE, que tem o valor 0x80131508.

Plataforma Universal do Windows
Disponível desde 8
.NET Framework
Disponível desde 1.1
Biblioteca de Classes Portátil
Com suporte no: plataformas portáteis do .NET
Silverlight
Disponível desde 2.0
Windows Phone Silverlight
Disponível desde 7.0
Windows Phone
Disponível desde 8.1

Quaisquer membros estáticos públicos ( Compartilhado no Visual Basic) desse tipo são thread-safe. Não há garantia de que qualquer membro de instância seja thread-safe.

Retornar ao início
Mostrar: