Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / C#

KeyNotFoundException — uma chave inexistente numa coleção

System.Collections.Generic.KeyNotFoundException assinala uma tentativa de obter um elemento através de uma chave que não existe. Saiba em que diferem as leituras e escritas com o indexador de Dictionary<TKey,TValue> e quando utilizar TryGetValue se for esperada uma chave inexistente.

Versão: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification

Sintaxe

try { var value = dictionary[key]; }
catch (System.Collections.Generic.KeyNotFoundException) { /* Handle the missing key. */ }

System.Collections.Generic.KeyNotFoundException é um tipo de exceção que assinala uma tentativa de obter um elemento de uma coleção através de uma chave que a coleção não contém. O tipo está disponível no .NET 10; a sua utilização não requer funcionalidades da linguagem em versão preview.

Em Dictionary<TKey,TValue>, a leitura de dictionary[key] lança esta exceção se a chave não existir. A escrita de dictionary[key] = value tem um comportamento diferente: adiciona uma chave inexistente ou substitui o valor de uma chave existente. Assim, a ausência de uma chave não significa que todas as operações com o indexador lancem uma exceção.

Quando é esperada uma chave inexistente, utilize TryGetValue(key, out value) em vez de recorrer a try/catch para o fluxo normal do programa. Se a chave estiver ausente, o método devolve false e atribui default(TValue) ao parâmetro de saída. Para int, esse valor é 0; verifique o resultado booleano, porque 0 também pode ser um valor armazenado válido.

O exemplo provoca e captura intencionalmente KeyNotFoundException e, em seguida, demonstra TryGetValue e a adição da chave inexistente através de uma atribuição. O bloco catch apresenta texto fixo em vez da mensagem de sistema da exceção, para que o resultado esperado não dependa do idioma das mensagens do ambiente de execução.

Exemplos

using System;
using System.Collections.Generic;

internal static class Program
{
    private static void Main()
    {
        var scores = new Dictionary<string, int>
        {
            ["Ada"] = 10
        };

        try
        {
            Console.WriteLine(scores["Lin"]);
        }
        catch (KeyNotFoundException)
        {
            Console.WriteLine("Missing key: Lin");
        }

        if (!scores.TryGetValue("Lin", out int score))
        {
            Console.WriteLine($"Not found; out value: {score}");
        }

        scores["Lin"] = 20;
        Console.WriteLine(scores["Lin"]);
    }
}

Resultado

Missing key: Lin
Not found; out value: 0
20

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes