Coleções (C#)Collections (C#)

Para muitos aplicativos, você desejará criar e gerenciar grupos de objetos relacionados.For many applications, you want to create and manage groups of related objects. Há duas maneiras de agrupar objetos: criando matrizes de objetos e criando coleções de objetos.There are two ways to group objects: by creating arrays of objects, and by creating collections of objects.

As matrizes são mais úteis ao criar e trabalhar com um número fixo de objetos fortemente tipados.Arrays are most useful for creating and working with a fixed number of strongly-typed objects. Para obter informações sobre matrizes, consulte Matrizes.For information about arrays, see Arrays.

As coleções fornecem uma maneira mais flexível de trabalhar com grupos de objetos.Collections provide a more flexible way to work with groups of objects. Ao contrário das matrizes, o grupo de objetos com o qual você trabalha pode crescer e reduzir dinamicamente conforme as necessidades do aplicativo são alteradas.Unlike arrays, the group of objects you work with can grow and shrink dynamically as the needs of the application change. Para algumas coleções, você pode atribuir uma chave para qualquer objeto que colocar na coleção para que você possa recuperar rapidamente o objeto, usando a chave.For some collections, you can assign a key to any object that you put into the collection so that you can quickly retrieve the object by using the key.

Uma coleção é uma classe, portanto você deve declarar uma instância da classe antes de adicionar elementos a essa coleção.A collection is a class, so you must declare an instance of the class before you can add elements to that collection.

Se a coleção contiver elementos de apenas um tipo de dados, você poderá usar uma das classes no namespace System.Collections.Generic.If your collection contains elements of only one data type, you can use one of the classes in the System.Collections.Generic namespace. Uma coleção genérica impõe segurança de tipos para que nenhum outro tipo de dados possa ser adicionado a ela.A generic collection enforces type safety so that no other data type can be added to it. Ao recuperar um elemento de uma coleção genérica, você não precisa determinar seu tipo de dados ou convertê-lo.When you retrieve an element from a generic collection, you do not have to determine its data type or convert it.

Observação

Para os exemplos neste tópico, inclua diretivas using para os namespaces System.Collections.Generic e System.Linq.For the examples in this topic, include using directives for the System.Collections.Generic and System.Linq namespaces.

Neste tópicoIn this topic

Usando uma coleção simplesUsing a Simple Collection

Os exemplos nesta seção usam a classe genérica List<T>, que habilita você a trabalhar com uma lista de objetos fortemente tipados.The examples in this section use the generic List<T> class, which enables you to work with a strongly typed list of objects.

O exemplo a seguir cria uma lista de cadeias de caracteres e, em seguida, itera nas cadeias de caracteres usando uma instrução foreach.The following example creates a list of strings and then iterates through the strings by using a or foreach statement.

// Create a list of strings.  
var salmons = new List<string>();  
salmons.Add("chinook");  
salmons.Add("coho");  
salmons.Add("pink");  
salmons.Add("sockeye");  

// Iterate through the list.  
foreach (var salmon in salmons)  
{  
    Console.Write(salmon + " ");  
}  
// Output: chinook coho pink sockeye  

Se o conteúdo de uma coleção for conhecido com antecedência, você poderá usar um inicializador de coleção para inicializar a coleção.If the contents of a collection are known in advance, you can use a collection initializer to initialize the collection. Para obter mais informações, consulte Inicializadores de coleção e objeto.For more information, see Object and Collection Initializers.

O exemplo a seguir é igual ao exemplo anterior, exceto que um inicializador de coleção é usado para adicionar elementos à coleção.The following example is the same as the previous example, except a collection initializer is used to add elements to the collection.

// Create a list of strings by using a  
// collection initializer.  
var salmons = new List<string> { "chinook", "coho", "pink", "sockeye" };  

// Iterate through the list.  
foreach (var salmon in salmons)  
{  
    Console.Write(salmon + " ");  
}  
// Output: chinook coho pink sockeye  

Você pode usar uma instrução for em vez de uma instrução foreach para iterar em uma coleção.You can use a for statement instead of a foreach statement to iterate through a collection. Você realiza isso acessando os elementos da coleção pela posição do índice.You accomplish this by accessing the collection elements by the index position. O índice dos elementos começa em 0 e termina na contagem de elementos, menos de 1.The index of the elements starts at 0 and ends at the element count minus 1.

O exemplo a seguir itera nos elementos de uma coleção usando for em vez de foreach.The following example iterates through the elements of a collection by using for instead of foreach.

// Create a list of strings by using a  
// collection initializer.  
var salmons = new List<string> { "chinook", "coho", "pink", "sockeye" };  

for (var index = 0; index < salmons.Count; index++)  
{  
    Console.Write(salmons[index] + " ");  
}  
// Output: chinook coho pink sockeye  

O exemplo a seguir remove um elemento da coleção, especificando o objeto a ser removido.The following example removes an element from the collection by specifying the object to remove.

// Create a list of strings by using a  
// collection initializer.  
var salmons = new List<string> { "chinook", "coho", "pink", "sockeye" };  

// Remove an element from the list by specifying  
// the object.  
salmons.Remove("coho");  

// Iterate through the list.  
foreach (var salmon in salmons)  
{  
    Console.Write(salmon + " ");  
}  
// Output: chinook pink sockeye  

O exemplo a seguir remove elementos de uma lista genérica.The following example removes elements from a generic list. Em vez de uma instrução foreach, é usada uma instrução for que itera em ordem decrescente.Instead of a foreach statement, a for statement that iterates in descending order is used. Isso é feito porque o método RemoveAt faz com que os elementos após um elemento removido tenham um valor de índice menor.This is because the RemoveAt method causes elements after a removed element to have a lower index value.

var numbers = new List<int> { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };  

// Remove odd numbers.  
for (var index = numbers.Count - 1; index >= 0; index--)  
{  
    if (numbers[index] % 2 == 1)  
    {  
        // Remove the element by specifying  
        // the zero-based index in the list.  
        numbers.RemoveAt(index);  
    }  
}  

// Iterate through the list.  
// A lambda expression is placed in the ForEach method  
// of the List(T) object.  
numbers.ForEach(  
    number => Console.Write(number + " "));  
// Output: 0 2 4 6 8  

Para o tipo dos elementos na List<T>, você também pode definir sua própria classe.For the type of elements in the List<T>, you can also define your own class. No exemplo a seguir, a classe Galaxy que é usada pela List<T> é definida no código.In the following example, the Galaxy class that is used by the List<T> is defined in the code.

private static void IterateThroughList()  
{  
    var theGalaxies = new List<Galaxy>  
        {  
            new Galaxy() { Name="Tadpole", MegaLightYears=400},  
            new Galaxy() { Name="Pinwheel", MegaLightYears=25},  
            new Galaxy() { Name="Milky Way", MegaLightYears=0},  
            new Galaxy() { Name="Andromeda", MegaLightYears=3}  
        };  

    foreach (Galaxy theGalaxy in theGalaxies)  
    {  
        Console.WriteLine(theGalaxy.Name + "  " + theGalaxy.MegaLightYears);  
    }  

    // Output:  
    //  Tadpole  400  
    //  Pinwheel  25  
    //  Milky Way  0  
    //  Andromeda  3  
}  

public class Galaxy  
{  
    public string Name { get; set; }  
    public int MegaLightYears { get; set; }  
}  

Tipos de coleçõesKinds of Collections

Várias coleções comuns são fornecidas pelo .NET Framework.Many common collections are provided by the .NET Framework. Cada tipo de coleção é projetado para uma finalidade específica.Each type of collection is designed for a specific purpose.

Algumas das classes de coleção comuns são descritas nesta seção:Some of the common collection classes are described in this section:

Classes System.Collections.GenericSystem.Collections.Generic Classes

Você pode criar uma coleção genérica usando uma das classes no namespace System.Collections.Generic.You can create a generic collection by using one of the classes in the System.Collections.Generic namespace. Uma coleção genérica é útil quando cada item na coleção tem o mesmo tipo de dados.A generic collection is useful when every item in the collection has the same data type. Uma coleção genérica impõe tipagem forte, permitindo que apenas o tipo de dados desejado seja adicionado.A generic collection enforces strong typing by allowing only the desired data type to be added.

A tabela a seguir lista algumas das classes frequentemente usadas do namespace System.Collections.Generic:The following table lists some of the frequently used classes of the System.Collections.Generic namespace:

ClasseClass DescriçãoDescription
Dictionary<TKey,TValue> Representa uma coleção de pares chave-valor organizados com base na chave.Represents a collection of key/value pairs that are organized based on the key.
List<T> Representa uma lista de objetos que podem ser acessados por índice.Represents a list of objects that can be accessed by index. Fornece métodos para pesquisar, classificar e modificar listas.Provides methods to search, sort, and modify lists.
Queue<T> Representa uma coleção de objetos PEPS (primeiro a entrar, primeiro a sair).Represents a first in, first out (FIFO) collection of objects.
SortedList<TKey,TValue> Representa uma coleção de pares chave/valor que são classificados por chave com base na implementação de IComparer<T> associada.Represents a collection of key/value pairs that are sorted by key based on the associated IComparer<T> implementation.
Stack<T> Representa uma coleção de objetos UEPS (último a entrar, primeiro a sair).Represents a last in, first out (LIFO) collection of objects.

Para obter informações adicionais, consulte Tipos de coleção comumente usados, Selecionando uma classe de coleção e System.Collections.Generic.For additional information, see Commonly Used Collection Types, Selecting a Collection Class, and System.Collections.Generic.

Classes System.Collections.ConcurrentSystem.Collections.Concurrent Classes

No .NET Framework 4 ou mais recente, as coleções no namespace System.Collections.Concurrent fornecem operações thread-safe eficientes para acessar itens da coleção de vários threads.In the .NET Framework 4 or newer, the collections in the System.Collections.Concurrent namespace provide efficient thread-safe operations for accessing collection items from multiple threads.

As classes no namespace System.Collections.Concurrent deverão ser usadas em vez dos tipos correspondentes nos namespaces System.Collections.Generic e System.Collections sempre que vários threads estiverem acessando a coleção simultaneamente.The classes in the System.Collections.Concurrent namespace should be used instead of the corresponding types in the System.Collections.Generic and System.Collections namespaces whenever multiple threads are accessing the collection concurrently. Para obter mais informações, veja Coleções thread-safe e System.Collections.Concurrent.For more information, see Thread-Safe Collections and System.Collections.Concurrent.

Algumas classes incluídas no namespace System.Collections.Concurrent são BlockingCollection<T>, ConcurrentDictionary<TKey,TValue>, ConcurrentQueue<T> e ConcurrentStack<T>.Some classes included in the System.Collections.Concurrent namespace are BlockingCollection<T>, ConcurrentDictionary<TKey,TValue>, ConcurrentQueue<T>, and ConcurrentStack<T>.

Classes System.CollectionsSystem.Collections Classes

As classes no namespace System.Collections não armazenam elementos como objetos especificamente tipados, mas como objetos do tipo Object.The classes in the System.Collections namespace do not store elements as specifically typed objects, but as objects of type Object.

Sempre que possível, você deve usar as coleções genéricas no namespace System.Collections.Generic ou no System.Collections.Concurrent em vez dos tipos herdados no namespace System.Collections.Whenever possible, you should use the generic collections in the System.Collections.Generic namespace or the System.Collections.Concurrent namespace instead of the legacy types in the System.Collections namespace.

A tabela a seguir lista algumas das classes frequentemente usadas no namespace System.Collections:The following table lists some of the frequently used classes in the System.Collections namespace:

ClasseClass DescriçãoDescription
ArrayList Representa uma matriz de objetos cujo tamanho é aumentado dinamicamente conforme necessário.Represents an array of objects whose size is dynamically increased as required.
Hashtable Representa uma coleção de pares chave-valor organizados com base no código hash da chave.Represents a collection of key/value pairs that are organized based on the hash code of the key.
Queue Representa uma coleção de objetos PEPS (primeiro a entrar, primeiro a sair).Represents a first in, first out (FIFO) collection of objects.
Stack Representa uma coleção de objetos UEPS (último a entrar, primeiro a sair).Represents a last in, first out (LIFO) collection of objects.

O namespace System.Collections.Specialized fornece classes de coleções especializadas e fortemente tipadas, como coleções somente de cadeias de caracteres, bem como de dicionários híbridos e de listas vinculadas.The System.Collections.Specialized namespace provides specialized and strongly typed collection classes, such as string-only collections and linked-list and hybrid dictionaries.

Implementando uma coleção de pares chave-valorImplementing a Collection of Key/Value Pairs

A coleção genérica Dictionary<TKey,TValue> permite que você acesse elementos em uma coleção usando a chave de cada elemento.The Dictionary<TKey,TValue> generic collection enables you to access to elements in a collection by using the key of each element. Cada adição ao dicionário consiste em um valor e a respectiva chave associada.Each addition to the dictionary consists of a value and its associated key. A recuperação de um valor usando sua chave é rápida, porque a classe Dictionary é implementada como uma tabela de hash.Retrieving a value by using its key is fast because the Dictionary class is implemented as a hash table.

O exemplo a seguir cria uma coleção Dictionary e itera no dicionário usando uma instrução foreach.The following example creates a Dictionary collection and iterates through the dictionary by using a foreach statement.

private static void IterateThruDictionary()  
{  
    Dictionary<string, Element> elements = BuildDictionary();  

    foreach (KeyValuePair<string, Element> kvp in elements)  
    {  
        Element theElement = kvp.Value;  

        Console.WriteLine("key: " + kvp.Key);  
        Console.WriteLine("values: " + theElement.Symbol + " " +  
            theElement.Name + " " + theElement.AtomicNumber);  
    }  
}  

private static Dictionary<string, Element> BuildDictionary()  
{  
    var elements = new Dictionary<string, Element>();  

    AddToDictionary(elements, "K", "Potassium", 19);  
    AddToDictionary(elements, "Ca", "Calcium", 20);  
    AddToDictionary(elements, "Sc", "Scandium", 21);  
    AddToDictionary(elements, "Ti", "Titanium", 22);  

    return elements;  
}  

private static void AddToDictionary(Dictionary<string, Element> elements,  
    string symbol, string name, int atomicNumber)  
{  
    Element theElement = new Element();  

    theElement.Symbol = symbol;  
    theElement.Name = name;  
    theElement.AtomicNumber = atomicNumber;  

    elements.Add(key: theElement.Symbol, value: theElement);  
}  

public class Element  
{  
    public string Symbol { get; set; }  
    public string Name { get; set; }  
    public int AtomicNumber { get; set; }  
}  

Para, em vez disso, usar um inicializador de coleção para criar a coleção Dictionary, você pode substituir os métodos BuildDictionary e AddToDictionary pelo seguinte método.To instead use a collection initializer to build the Dictionary collection, you can replace the BuildDictionary and AddToDictionary methods with the following method.

private static Dictionary<string, Element> BuildDictionary2()  
{  
    return new Dictionary<string, Element>  
    {  
        {"K",  
            new Element() { Symbol="K", Name="Potassium", AtomicNumber=19}},  
        {"Ca",  
            new Element() { Symbol="Ca", Name="Calcium", AtomicNumber=20}},  
        {"Sc",  
            new Element() { Symbol="Sc", Name="Scandium", AtomicNumber=21}},  
        {"Ti",  
            new Element() { Symbol="Ti", Name="Titanium", AtomicNumber=22}}  
    };  
}  

O exemplo a seguir usa o método ContainsKey e a propriedade Item[TKey] de Dictionary para localizar rapidamente um item por chave.The following example uses the ContainsKey method and the Item[TKey] property of Dictionary to quickly find an item by key. A propriedade Item permite que você acesse um item na coleção elements usando o elements[symbol] no C#.The Item property enables you to access an item in the elements collection by using the elements[symbol] in C#.

private static void FindInDictionary(string symbol)  
{  
    Dictionary<string, Element> elements = BuildDictionary();  

    if (elements.ContainsKey(symbol) == false)  
    {  
        Console.WriteLine(symbol + " not found");  
    }  
    else  
    {  
        Element theElement = elements[symbol];  
        Console.WriteLine("found: " + theElement.Name);  
    }  
}  

O exemplo a seguir usa o método TryGetValue para localizar rapidamente um item por chave.The following example instead uses the TryGetValue method quickly find an item by key.

private static void FindInDictionary2(string symbol)  
{  
    Dictionary<string, Element> elements = BuildDictionary();  

    Element theElement = null;  
    if (elements.TryGetValue(symbol, out theElement) == false)  
        Console.WriteLine(symbol + " not found");  
    else  
        Console.WriteLine("found: " + theElement.Name);  
}  

Usando LINQ para acessar uma coleçãoUsing LINQ to Access a Collection

A LINQ (consulta integrada à linguagem) pode ser usada para acessar coleções.LINQ (Language-Integrated Query) can be used to access collections. As consultas LINQ fornecem recursos de filtragem, classificação e agrupamento.LINQ queries provide filtering, ordering, and grouping capabilities. Para obter mais informações, consulte Introdução à LINQ em C#.For more information, see Getting Started with LINQ in C#.

O exemplo a seguir executa uma consulta LINQ em uma List genérica.The following example runs a LINQ query against a generic List. A consulta LINQ retorna uma coleção diferente que contém os resultados.The LINQ query returns a different collection that contains the results.

private static void ShowLINQ()  
{  
    List<Element> elements = BuildList();  

    // LINQ Query.  
    var subset = from theElement in elements  
                 where theElement.AtomicNumber < 22  
                 orderby theElement.Name  
                 select theElement;  

    foreach (Element theElement in subset)  
    {  
        Console.WriteLine(theElement.Name + " " + theElement.AtomicNumber);  
    }  

    // Output:  
    //  Calcium 20  
    //  Potassium 19  
    //  Scandium 21  
}  

private static List<Element> BuildList()  
{  
    return new List<Element>  
    {  
        { new Element() { Symbol="K", Name="Potassium", AtomicNumber=19}},  
        { new Element() { Symbol="Ca", Name="Calcium", AtomicNumber=20}},  
        { new Element() { Symbol="Sc", Name="Scandium", AtomicNumber=21}},  
        { new Element() { Symbol="Ti", Name="Titanium", AtomicNumber=22}}  
    };  
}  

public class Element  
{  
    public string Symbol { get; set; }  
    public string Name { get; set; }  
    public int AtomicNumber { get; set; }  
}  

Classificando uma coleçãoSorting a Collection

O exemplo a seguir ilustra um procedimento para a classificação de uma coleção.The following example illustrates a procedure for sorting a collection. O exemplo classifica instâncias da classe Car que estão armazenados em uma List<T>.The example sorts instances of the Car class that are stored in a List<T>. A classe Car implementa a interface IComparable<T>, que requer que o método CompareTo seja implementado.The Car class implements the IComparable<T> interface, which requires that the CompareTo method be implemented.

Cada chamada ao método CompareTo faz uma comparação única que é usada para classificação.Each call to the CompareTo method makes a single comparison that is used for sorting. Os códigos escritos pelo usuário no método CompareTo retornam um valor para cada comparação do objeto atual com outro objeto.User-written code in the CompareTo method returns a value for each comparison of the current object with another object. O valor retornado será menor que zero se o objeto atual for menor que o outro objeto, maior que zero se o objeto atual for maior que o outro objeto e zero, se eles forem iguais.The value returned is less than zero if the current object is less than the other object, greater than zero if the current object is greater than the other object, and zero if they are equal. Isso permite que você defina no código os critérios para maior que, menor que e igual.This enables you to define in code the criteria for greater than, less than, and equal.

No método ListCars, a instrução cars.Sort() classifica a lista.In the ListCars method, the cars.Sort() statement sorts the list. Essa chamada para o método Sort da List<T> faz com que o método CompareTo seja chamado automaticamente para os objetos Car na List.This call to the Sort method of the List<T> causes the CompareTo method to be called automatically for the Car objects in the List.

private static void ListCars()  
{  
    var cars = new List<Car>  
    {  
        { new Car() { Name = "car1", Color = "blue", Speed = 20}},  
        { new Car() { Name = "car2", Color = "red", Speed = 50}},  
        { new Car() { Name = "car3", Color = "green", Speed = 10}},  
        { new Car() { Name = "car4", Color = "blue", Speed = 50}},  
        { new Car() { Name = "car5", Color = "blue", Speed = 30}},  
        { new Car() { Name = "car6", Color = "red", Speed = 60}},  
        { new Car() { Name = "car7", Color = "green", Speed = 50}}  
    };  

    // Sort the cars by color alphabetically, and then by speed  
    // in descending order.  
    cars.Sort();  

    // View all of the cars.  
    foreach (Car thisCar in cars)  
    {  
        Console.Write(thisCar.Color.PadRight(5) + " ");  
        Console.Write(thisCar.Speed.ToString() + " ");  
        Console.Write(thisCar.Name);  
        Console.WriteLine();  
    }  

    // Output:  
    //  blue  50 car4  
    //  blue  30 car5  
    //  blue  20 car1  
    //  green 50 car7  
    //  green 10 car3  
    //  red   60 car6  
    //  red   50 car2  
}  

public class Car : IComparable<Car>  
{  
    public string Name { get; set; }  
    public int Speed { get; set; }  
    public string Color { get; set; }  

    public int CompareTo(Car other)  
    {  
        // A call to this method makes a single comparison that is  
        // used for sorting.  

        // Determine the relative order of the objects being compared.  
        // Sort by color alphabetically, and then by speed in  
        // descending order.  

        // Compare the colors.  
        int compare;  
        compare = String.Compare(this.Color, other.Color, true);  

        // If the colors are the same, compare the speeds.  
        if (compare == 0)  
        {  
            compare = this.Speed.CompareTo(other.Speed);  

            // Use descending order for speed.  
            compare = -compare;  
        }  

        return compare;  
    }  
}  

Definindo uma coleção personalizadaDefining a Custom Collection

Você pode definir uma coleção implementando a interface IEnumerable<T> ou IEnumerable.You can define a collection by implementing the IEnumerable<T> or IEnumerable interface. Para obter informações adicionais, consulte Como acessar uma classe de coleção com foreach.For additional information, see How to: Access a Collection Class with foreach.

Embora seja possível definir uma coleção personalizada, é melhor usar as coleções que estão incluídas no .NET Framework, que estão descritas em Tipos de coleções anteriormente neste tópico.Although you can define a custom collection, it is usually better to instead use the collections that are included in the .NET Framework, which are described in Kinds of Collections earlier in this topic.

O exemplo a seguir define uma classe de coleção personalizada chamada AllColors.The following example defines a custom collection class named AllColors. Essa classe implementa a interface IEnumerable, que requer que o método GetEnumerator seja implementado.This class implements the IEnumerable interface, which requires that the GetEnumerator method be implemented.

O método GetEnumerator retorna uma instância da classe ColorEnumerator.The GetEnumerator method returns an instance of the ColorEnumerator class. ColorEnumerator implementa a interface IEnumerator, que requer que a propriedade Current, o método MoveNext e o método Reset sejam implementados.ColorEnumerator implements the IEnumerator interface, which requires that the Current property, MoveNext method, and Reset method be implemented.

private static void ListColors()  
{  
    var colors = new AllColors();  

    foreach (Color theColor in colors)  
    {  
        Console.Write(theColor.Name + " ");  
    }  
    Console.WriteLine();  
    // Output: red blue green  
}  

// Collection class.  
public class AllColors : System.Collections.IEnumerable  
{  
    Color[] _colors =  
    {  
        new Color() { Name = "red" },  
        new Color() { Name = "blue" },  
        new Color() { Name = "green" }  
    };  

    public System.Collections.IEnumerator GetEnumerator()  
    {  
        return new ColorEnumerator(_colors);  

        // Instead of creating a custom enumerator, you could  
        // use the GetEnumerator of the array.  
        //return _colors.GetEnumerator();  
    }  

    // Custom enumerator.  
    private class ColorEnumerator : System.Collections.IEnumerator  
    {  
        private Color[] _colors;  
        private int _position = -1;  

        public ColorEnumerator(Color[] colors)  
        {  
            _colors = colors;  
        }  

        object System.Collections.IEnumerator.Current  
        {  
            get  
            {  
                return _colors[_position];  
            }  
        }  

        bool System.Collections.IEnumerator.MoveNext()  
        {  
            _position++;  
            return (_position < _colors.Length);  
        }  

        void System.Collections.IEnumerator.Reset()  
        {  
            _position = -1;  
        }  
    }  
}  

// Element class.  
public class Color  
{  
    public string Name { get; set; }  
}  

IteratorsIterators

Um iterador é usado para realizar uma iteração personalizada em uma coleção.An iterator is used to perform a custom iteration over a collection. Um iterador pode ser um método ou um acessador get.An iterator can be a method or a get accessor. Um iterador usa uma instrução yield return para retornar um elemento da coleção por vez.An iterator uses a yield return statement to return each element of the collection one at a time.

Você chama um iterador usando uma instrução foreach.You call an iterator by using a foreach statement. Cada iteração do loop foreach chama o iterador.Each iteration of the foreach loop calls the iterator. Quando uma instrução yield return é alcançada no iterador, uma expressão é retornada e o local atual no código é retido.When a yield return statement is reached in the iterator, an expression is returned, and the current location in code is retained. A execução será reiniciada desse local na próxima vez que o iterador for chamado.Execution is restarted from that location the next time that the iterator is called.

Para obter mais informações, consulte Iteradores (C#).For more information, see Iterators (C#).

O exemplo a seguir usa um método iterador.The following example uses an iterator method. O método iterador tem uma instrução yield return que está dentro de um loop for.The iterator method has a yield return statement that is inside a for loop. No método ListEvenNumbers, cada iteração do corpo da instrução foreach cria uma chamada ao método iterador, que avança para a próxima instrução yield return.In the ListEvenNumbers method, each iteration of the foreach statement body creates a call to the iterator method, which proceeds to the next yield return statement.

private static void ListEvenNumbers()  
{  
    foreach (int number in EvenSequence(5, 18))  
    {  
        Console.Write(number.ToString() + " ");  
    }  
    Console.WriteLine();  
    // Output: 6 8 10 12 14 16 18  
}  

private static IEnumerable<int> EvenSequence(  
    int firstNumber, int lastNumber)  
{  
    // Yield even numbers in the range.  
    for (var number = firstNumber; number <= lastNumber; number++)  
    {  
        if (number % 2 == 0)  
        {  
            yield return number;  
        }  
    }  
}  

Consulte tambémSee Also

Inicializadores de objeto e coleçãoObject and Collection Initializers
Conceitos de programação (C#)Programming Concepts (C#)
Instrução Option StrictOption Strict Statement
LINQ to Objects (C#)LINQ to Objects (C#)
PLINQ (LINQ paralelo)Parallel LINQ (PLINQ)
Coleções e Estruturas de DadosCollections and Data Structures
Criando e manipulando coleçõesCreating and Manipulating Collections
Selecionando uma Classe de ColeçãoSelecting a Collection Class
Comparações e Classificações Dentro de ColeçõesComparisons and Sorts Within Collections
Quando Usar Coleções GenéricasWhen to Use Generic Collections
Como acessar uma classe de coleção com foreachHow to: Access a Collection Class with foreach