using (Instrucción, Referencia de C#)using statement (C# Reference)

Ofrece una sintaxis adecuada que garantiza el uso correcto de objetos IDisposable.Provides a convenient syntax that ensures the correct use of IDisposable objects. A partir de C# 8.0, la instrucción using garantiza el uso correcto de los objetos IAsyncDisposable.Beginning in C# 8.0, the using statement ensures the correct use of IAsyncDisposable objects.

EjemploExample

En el ejemplo siguiente se muestra cómo usar la instrucción using.The following example shows how to use the using statement.

string manyLines=@"This is line one
This is line two
Here is line three
The penultimate line is line four
This is the final, fifth line.";

using (var reader = new StringReader(manyLines))
{
    string? item;
    do {
        item = reader.ReadLine();
        Console.WriteLine(item);
    } while(item != null);
}

A partir de C# 8.0, puede usar la siguiente sintaxis alternativa para la instrucción using que no requiere llaves:Beginning with C# 8.0, you can use the following alternative syntax for the using statement that doesn't require braces:

string manyLines=@"This is line one
This is line two
Here is line three
The penultimate line is line four
This is the final, fifth line.";

using var reader = new StringReader(manyLines);
string? item;
do {
    item = reader.ReadLine();
    Console.WriteLine(item);
} while(item != null);

ComentariosRemarks

File y Font son ejemplos de tipos administrados que acceden a recursos no administrados (en este caso, identificadores de archivo y contextos de dispositivo).File and Font are examples of managed types that access unmanaged resources (in this case file handles and device contexts). Hay muchos otros tipos de recursos no administrados y tipos de la biblioteca de clases que los encapsulan.There are many other kinds of unmanaged resources and class library types that encapsulate them. Todos estos tipos deben implementar la interfaz IDisposable o la interfaz IAsyncDisposable.All such types must implement the IDisposable interface, or the IAsyncDisposable interface.

Cuando la duración de un objeto IDisposable se limita a un único método, debe declarar y crear instancias del mismo en la instrucción using.When the lifetime of an IDisposable object is limited to a single method, you should declare and instantiate it in the using statement. La instrucción using llama al método Dispose del objeto de forma correcta y (cuando se usa tal y como se muestra anteriormente) también hace que el propio objeto salga del ámbito en cuanto se llame a Dispose.The using statement calls the Dispose method on the object in the correct way, and (when you use it as shown earlier) it also causes the object itself to go out of scope as soon as Dispose is called. Dentro del bloque using, el objeto es de solo lectura y no se puede modificar ni reasignar.Within the using block, the object is read-only and can't be modified or reassigned. Si el objeto implementa IAsyncDisposable en lugar de IDisposable, la instrucción using llama al objeto DisposeAsync y awaits al objeto ValueTask devuelto.If the object implements IAsyncDisposable instead of IDisposable, the using statement calls the DisposeAsync and awaits the returned ValueTask. Para obtener más información sobre IAsyncDisposable, vea Implementación de un método DisposeAsync.For more information on IAsyncDisposable, see Implement a DisposeAsync method.

La instrucción using asegura que se llama al método Dispose (o DisposeAsync) aunque se produzca una excepción en el bloque using.The using statement ensures that Dispose (or DisposeAsync) is called even if an exception occurs within the using block. Puede obtener el mismo resultado si coloca el objeto dentro de un bloque try y llama a Dispose (o DisposeAsync) en un bloque finally; de hecho, es así como el compilador traduce la instrucción using.You can achieve the same result by putting the object inside a try block and then calling Dispose (or DisposeAsync) in a finally block; in fact, this is how the using statement is translated by the compiler. El ejemplo de código anterior se extiende al siguiente código en tiempo de compilación (tenga en cuenta las llaves adicionales para crear el ámbito limitado del objeto):The code example earlier expands to the following code at compile time (note the extra curly braces to create the limited scope for the object):

string manyLines=@"This is line one
This is line two
Here is line three
The penultimate line is line four
This is the final, fifth line.";

{
    var reader = new StringReader(manyLines);
    try {
        string? item;
        do {
            item = reader.ReadLine();
            Console.WriteLine(item);
        } while(item != null);
    } finally
    {
        reader?.Dispose();
    }
}

La nueva sintaxis de la instrucción using se traduce en un código similar.The newer using statement syntax translates to similar code. Se abre el bloque try en el que se declara la variable.The try block opens where the variable is declared. El bloque finally se agrega al cierre del bloque de inclusión, normalmente, al final de un método.The finally block is added at the close of the enclosing block, typically at the end of a method.

Consulte el artículo sobre try-finally para obtener más información sobre la instrucción try-finally.For more information about the try-finally statement, see the try-finally article.

Se pueden declarar varias instancias de un tipo en una sola instrucción using, tal y como se muestra en el ejemplo siguiente.Multiple instances of a type can be declared in a single using statement, as shown in the following example. Tenga en cuenta que no se pueden usar variables con tipo implícito (var) cuando se declaran varias variables en una sola instrucción:Notice that you can't use implicitly typed variables (var) when you declare multiple variables in a single statement:

string numbers=@"One
Two
Three
Four.";
string letters=@"A
B
C
D.";

using (StringReader left = new StringReader(numbers),
    right = new StringReader(letters))
{
    string? item;
    do {
        item = left.ReadLine();
        Console.Write(item);
        Console.Write("    ");
        item = right.ReadLine();
        Console.WriteLine(item);
    } while(item != null);
}

También puede combinar varias declaraciones del mismo tipo con la nueva sintaxis introducida con C# 8, tal y como se muestra en el ejemplo siguiente:You can combine multiple declarations of the same type using the new syntax introduced with C# 8 as well, as shown in the following example:

string numbers=@"One
Two
Three
Four.";
string letters=@"A
B
C
D.";

using StringReader left = new StringReader(numbers),
    right = new StringReader(letters);
string? item;
do {
    item = left.ReadLine();
    Console.Write(item);
    Console.Write("    ");
    item = right.ReadLine();
    Console.WriteLine(item);
} while(item != null);

Puede crear una instancia del objeto de recurso y luego pasar la variable a la instrucción using, pero esto no es un procedimiento recomendado.You can instantiate the resource object and then pass the variable to the using statement, but this isn't a best practice. En este caso, después de que el control abandone el bloque using el objeto permanece en el ámbito, pero probablemente ya no tenga acceso a sus recursos no administrados.In this case, after control leaves the using block, the object remains in scope but probably has no access to its unmanaged resources. En otras palabras, ya no se inicializa totalmente.In other words, it's not fully initialized anymore. Si intenta usar el objeto fuera del bloque using, corre el riesgo de iniciar una excepción.If you try to use the object outside the using block, you risk causing an exception to be thrown. Por este motivo, es mejor crear una instancia del objeto en la instrucción using y limitar su ámbito al bloque using.For this reason, it's better to instantiate the object in the using statement and limit its scope to the using block.

string manyLines=@"This is line one
This is line two
Here is line three
The penultimate line is line four
This is the final, fifth line.";

var reader = new StringReader(manyLines);
using (reader)
{
    string? item;
    do {
        item = reader.ReadLine();
        Console.WriteLine(item);
    } while(item != null);
}
// reader is in scope here, but has been disposed

Para obtener más información sobre cómo eliminar objetos IDisposable, vea Uso de objetos que implementan IDisposable.For more information about disposing of IDisposable objects, see Using objects that implement IDisposable.

Especificación del lenguaje C#C# language specification

Para obtener más información, vea el apartado Instrucción using en la Especificación del lenguaje C#.For more information, see The using statement in the C# Language Specification. La especificación del lenguaje es la fuente definitiva de la sintaxis y el uso de C#.The language specification is the definitive source for C# syntax and usage.

Vea tambiénSee also