using, instruction (référence C#)using statement (C# Reference)

Fournit une syntaxe pratique qui garantit l’utilisation correcte d’objets IDisposable.Provides a convenient syntax that ensures the correct use of IDisposable objects. À compter de C# 8,0, l' using instruction garantit l’utilisation correcte des IAsyncDisposable objets.Beginning in C# 8.0, the using statement ensures the correct use of IAsyncDisposable objects.

ExempleExample

L’exemple suivant montre comment utiliser l’instruction 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);
}

À compter de C# 8,0, vous pouvez utiliser la syntaxe alternative suivante pour l' using instruction qui ne requiert pas d’accolades :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);

NotesRemarks

File et Font sont des exemples de types managés qui accèdent à des ressources non managées (dans le cas présent, des handles de fichiers et des contextes d’appareil).File and Font are examples of managed types that access unmanaged resources (in this case file handles and device contexts). Beaucoup d’autres types de ressources non managées et de bibliothèques de classes peuvent les encapsuler.There are many other kinds of unmanaged resources and class library types that encapsulate them. Tous ces types doivent implémenter l' IDisposable interface ou l' IAsyncDisposable interface.All such types must implement the IDisposable interface, or the IAsyncDisposable interface.

Quand la durée de vie d’un objet IDisposable est limitée à une seule méthode, vous devez le déclarer et l’instancier dans l’instruction using.When the lifetime of an IDisposable object is limited to a single method, you should declare and instantiate it in the using statement. L’instruction using appelle la méthode Dispose correctement sur l’objet et, quand vous l’utilisez comme indiqué précédemment, elle met également l’objet lui-même hors de portée dès que Dispose est appelée.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. Dans le using bloc, l’objet est en lecture seule et ne peut pas être modifié ou réassigné.Within the using block, the object is read-only and can't be modified or reassigned. Si l’objet implémente IAsyncDisposable au lieu de IDisposable , l' using instruction appelle DisposeAsync et awaits le retourné ValueTask .If the object implements IAsyncDisposable instead of IDisposable, the using statement calls the DisposeAsync and awaits the returned ValueTask. Pour plus d’informations sur IAsyncDisposable , consultez implémenter une méthode DisposeAsync.For more information on IAsyncDisposable, see Implement a DisposeAsync method.

L' using instruction garantit que Dispose (ou DisposeAsync ) est appelé même si une exception se produit dans le using bloc.The using statement ensures that Dispose (or DisposeAsync) is called even if an exception occurs within the using block. Vous pouvez obtenir le même résultat en plaçant l’objet à l’intérieur d’un try bloc, puis Dispose en appelant (ou DisposeAsync ) dans un finally bloc. en fait, il s’agit de la façon dont l' using instruction est traduite par le compilateur.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. L’exemple de code précédent se développe pour donner le code suivant au moment de la compilation (notez les accolades supplémentaires pour créer la portée limitée de l’objet) :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 using syntaxe d’instruction la plus récente traduit en code similaire.The newer using statement syntax translates to similar code. Le try bloc s’ouvre à l’emplacement où la variable est déclarée.The try block opens where the variable is declared. Le finally bloc est ajouté à la fermeture du bloc englobant, en général à la fin d’une méthode.The finally block is added at the close of the enclosing block, typically at the end of a method.

Pour plus d’informations sur l' try - finally instruction, consultez l’article try-finally .For more information about the try-finally statement, see the try-finally article.

Plusieurs instances d’un type peuvent être déclarées dans une même using instruction, comme illustré dans l’exemple suivant.Multiple instances of a type can be declared in a single using statement, as shown in the following example. Notez que vous ne pouvez pas utiliser de variables implicitement typées ( var ) lorsque vous déclarez plusieurs variables dans une même instruction :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);
}

Vous pouvez combiner plusieurs déclarations du même type à l’aide de la nouvelle syntaxe introduite avec C# 8, comme indiqué dans l’exemple suivant :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);

Vous pouvez instancier l’objet de ressource, puis passer la variable à l' using instruction, mais ce n’est pas une meilleure pratique.You can instantiate the resource object and then pass the variable to the using statement, but this isn't a best practice. Dans ce cas, une fois que le contrôle a quitté le bloc using, l’objet reste dans la portée mais n’a probablement pas accès à ses ressources non managées.In this case, after control leaves the using block, the object remains in scope but probably has no access to its unmanaged resources. En d’autres termes, il n’est plus complètement initialisé.In other words, it's not fully initialized anymore. Si vous essayez d’utiliser l’objet à l’extérieur du bloc using, vous risquez de provoquer la levée d’une exception.If you try to use the object outside the using block, you risk causing an exception to be thrown. Pour cette raison, il est préférable d’instancier l’objet dans l' using instruction et de limiter son étendue au using bloc.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

Pour plus d’informations sur la suppression d’objets IDisposable, consultez Utilisation d’objets qui implémentent IDisposable.For more information about disposing of IDisposable objects, see Using objects that implement IDisposable.

spécification du langage C#C# language specification

Pour plus d’informations, consultez Instruction using dans la spécification du langage C#.For more information, see The using statement in the C# Language Specification. La spécification du langage est la source de référence pour la syntaxe C# et son utilisation.The language specification is the definitive source for C# syntax and usage.

Voir aussiSee also