From 686faf55c27858b582c02f1e452d813c07b95c81 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 13 Oct 2021 18:00:13 -0700 Subject: [PATCH 1/3] update exceptions for file.replace --- xml/System.IO/File.xml | 2738 ++++++++++++++++++++-------------------- 1 file changed, 1371 insertions(+), 1367 deletions(-) diff --git a/xml/System.IO/File.xml b/xml/System.IO/File.xml index d2a8aa1e2f8..ccbab5f17dc 100644 --- a/xml/System.IO/File.xml +++ b/xml/System.IO/File.xml @@ -53,51 +53,51 @@ Provides static methods for the creation, copying, deletion, moving, and opening of a single file, and aids in the creation of objects. - class for typical operations such as copying, moving, renaming, creating, opening, deleting, and appending to a single file at a time. You can also use the class to get and set file attributes or information related to the creation, access, and writing of a file. If you want to perform operations on multiple files, see or . - - Many of the methods return other I/O types when you create or open files. You can use these other types to further manipulate a file. For more information, see specific members such as , , or . - - Because all methods are static, it might be more efficient to use a method rather than a corresponding instance method if you want to perform only one action. All methods require the path to the file that you are manipulating. - - The static methods of the class perform security checks on all methods. If you are going to reuse an object several times, consider using the corresponding instance method of instead, because the security check will not always be necessary. - - By default, full read/write access to new files is granted to all users. - - The following table describes the enumerations that are used to customize the behavior of various methods. - -|Enumeration|Description| -|-----------------|-----------------| -||Specifies read and write access to a file.| -||Specifies the level of access permitted for a file that is already in use.| -||Specifies whether the contents of an existing file are preserved or overwritten, and whether requests to create an existing file cause an exception.| - + class for typical operations such as copying, moving, renaming, creating, opening, deleting, and appending to a single file at a time. You can also use the class to get and set file attributes or information related to the creation, access, and writing of a file. If you want to perform operations on multiple files, see or . + + Many of the methods return other I/O types when you create or open files. You can use these other types to further manipulate a file. For more information, see specific members such as , , or . + + Because all methods are static, it might be more efficient to use a method rather than a corresponding instance method if you want to perform only one action. All methods require the path to the file that you are manipulating. + + The static methods of the class perform security checks on all methods. If you are going to reuse an object several times, consider using the corresponding instance method of instead, because the security check will not always be necessary. + + By default, full read/write access to new files is granted to all users. + + The following table describes the enumerations that are used to customize the behavior of various methods. + +|Enumeration|Description| +|-----------------|-----------------| +||Specifies read and write access to a file.| +||Specifies the level of access permitted for a file that is already in use.| +||Specifies whether the contents of an existing file are preserved or overwritten, and whether requests to create an existing file cause an exception.| + > [!NOTE] -> In members that accept a path as an input string, that path must be well-formed or an exception is raised. For example, if a path is fully qualified but begins with a space, the path is not trimmed in methods of the class. Therefore, the path is malformed and an exception is raised. Similarly, a path or a combination of paths cannot be fully qualified twice. For example, "c:\temp c:\windows" also raises an exception in most cases. Ensure that your paths are well-formed when using methods that accept a path string. - - In members that accept a path, the path can refer to a file or just a directory. The specified path can also refer to a relative path or a Universal Naming Convention (UNC) path for a server and share name. For example, all the following are acceptable paths: - -- `"c:\\\MyDir\\\MyFile.txt"` in C#, or `"c:\MyDir\MyFile.txt"` in Visual Basic. - +> In members that accept a path as an input string, that path must be well-formed or an exception is raised. For example, if a path is fully qualified but begins with a space, the path is not trimmed in methods of the class. Therefore, the path is malformed and an exception is raised. Similarly, a path or a combination of paths cannot be fully qualified twice. For example, "c:\temp c:\windows" also raises an exception in most cases. Ensure that your paths are well-formed when using methods that accept a path string. + + In members that accept a path, the path can refer to a file or just a directory. The specified path can also refer to a relative path or a Universal Naming Convention (UNC) path for a server and share name. For example, all the following are acceptable paths: + +- `"c:\\\MyDir\\\MyFile.txt"` in C#, or `"c:\MyDir\MyFile.txt"` in Visual Basic. + - `"c:\\\MyDir"` in C#, or `"c:\MyDir"` in Visual Basic. - + - `"MyDir\\\MySubdir"` in C#, or `"MyDir\MySubDir"` in Visual Basic. - + - `"\\\\\\\MyServer\\\MyShare"` in C#, or `"\\\MyServer\MyShare"` in Visual Basic. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates how to use the class to check whether a file exists, and depending on the result, either create a new file and write to it, or open the existing file and read from it. Before running the code, create a `c:\temp` folder. - + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates how to use the class to check whether a file exists, and depending on the result, either create a new file and write to it, or open the existing file and read from it. Before running the code, create a `c:\temp` folder. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File Class Example/CPP/file class example.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Class Example/CS/file class example.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Class Example/VB/file class example.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Class Example/VB/file class example.vb" id="Snippet1"::: + ]]> @@ -168,19 +168,19 @@ The lines to append to the file. Appends lines to a file, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file. - @@ -196,14 +196,14 @@ is in an invalid format. The caller does not have permission to write to the file. - specifies a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - + specifies a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + is a directory. @@ -259,17 +259,17 @@ The character encoding to use. Appends lines to a file by using a specified encoding, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file. - method. - -- The contents of a collection that implements an of strings. - + method. + +- The contents of a collection that implements an of strings. + ]]> @@ -285,18 +285,18 @@ is in an invalid format. The caller does not have the required permission. - specifies a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - is a directory. - - -or- - + specifies a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + is a directory. + + -or- + The caller does not have the required permission. @@ -450,21 +450,21 @@ The string to append to the file. Opens a file, appends the specified string to the file, and then closes the file. If the file does not exist, this method creates a file, writes the specified string to the file, then closes the file. - method to add extra text to the end of a file. In this example, a file is created if it doesn't already exist, and text is added to it. However, the directory named `temp` on drive C must exist for the example to complete successfully. - + method to add extra text to the end of a file. In this example, a file is created if it doesn't already exist, and text is added to it. However, the directory named `temp` on drive C must exist for the example to complete successfully. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllText/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText/vb/AllText.vb" id="Snippet00"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -474,18 +474,18 @@ The specified path is invalid (for example, the directory doesn't exist or it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. is in an invalid format. @@ -546,21 +546,21 @@ The character encoding to use. Appends the specified string to the file using the specified encoding, creating the file if it does not already exist. - method to add extra text to the end of a file. In this example, a file is created if it doesn't already exist, and text is added to it. However, the directory named `temp` on drive C must exist for the example to complete successfully. - + method to add extra text to the end of a file. In this example, a file is created if it doesn't already exist, and text is added to it. However, the directory named `temp` on drive C must exist for the example to complete successfully. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/vb/AllText.vb" id="Snippet00"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -570,18 +570,18 @@ The specified path is invalid (for example, the directory doesn't exist or it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. is in an invalid format. @@ -729,26 +729,26 @@ Creates a that appends UTF-8 encoded text to an existing file, or to a new file if the specified file does not exist. A stream writer that appends UTF-8 encoded text to the specified file or to a new file. - constructor overload. If the file specified by `path` does not exist, it is created. If the file does exist, write operations to the append text to the file. Additional threads are permitted to read the file while it is open. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - The `path` parameter is not case-sensitive. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example appends text to a file. The method creates a new file if the file doesn't exist. However, the directory named `temp` on drive C must exist for the example to complete successfully. - + constructor overload. If the file specified by `path` does not exist, it is created. If the file does exist, write operations to the append text to the file. Additional threads are permitted to read the file while it is open. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + The `path` parameter is not case-sensitive. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example appends text to a file. The method creates a new file if the file doesn't exist. However, the directory named `temp` on drive C must exist for the example to complete successfully. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File_AppendText/CPP/file_appendtext.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File_AppendText/CS/file_appendtext.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File_AppendText/VB/file_appendtext.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File_AppendText/VB/file_appendtext.vb" id="Snippet1"::: + ]]> The caller does not have the required permission. @@ -822,34 +822,34 @@ The name of the destination file. This cannot be a directory or an existing file. Copies an existing file to a new file. Overwriting a file of the same name is not allowed. - method overload with the `overwrite` parameter set to `false`. - - The `sourceFileName` and `destFileName` parameters can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see the method. This method does not support wildcard characters in the parameters. - - The attributes of the original file are retained in the copied file. - - - -## Examples - The following example copies files to the C:\archives\2008 backup folder. It uses the two overloads of the method as follows: - -- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. - -- It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. - + method overload with the `overwrite` parameter set to `false`. + + The `sourceFileName` and `destFileName` parameters can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see the method. This method does not support wildcard characters in the parameters. + + The attributes of the original file are retained in the copied file. + + + +## Examples + The following example copies files to the C:\archives\2008 backup folder. It uses the two overloads of the method as follows: + +- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. + +- It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/filecopydelete/cs/program.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/filecopydelete/vb/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/filecopydelete/vb/program.vb" id="Snippet1"::: + ]]> The caller does not have the required permission. - .NET Framework and .NET Core versions older than 2.1: or is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. - - -or- - + .NET Framework and .NET Core versions older than 2.1: or is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. + + -or- + or specifies a directory. or is . @@ -858,10 +858,10 @@ was not found. - exists. - - -or- - + exists. + + -or- + An I/O error has occurred. or is in an invalid format. @@ -922,42 +922,42 @@ if the destination file can be overwritten; otherwise, . Copies an existing file to a new file. Overwriting a file of the same name is allowed. - method as follows: - -- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. - - It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. - + method as follows: + +- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. + + It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/filecopydelete/cs/program.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/filecopydelete/vb/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/filecopydelete/vb/program.vb" id="Snippet1"::: + ]]> - The caller does not have the required permission. - - -or- - + The caller does not have the required permission. + + -or- + is read-only. - - -or- - + + -or- + is , exists and is hidden, but is not hidden. - .NET Framework and .NET Core versions older than 2.1: or is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. - - -or- - + .NET Framework and .NET Core versions older than 2.1: or is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. + + -or- + or specifies a directory. or is . @@ -966,10 +966,10 @@ was not found. - exists and is . - - -or- - + exists and is . + + -or- + An I/O error has occurred. or is in an invalid format. @@ -1042,40 +1042,40 @@ Creates or overwrites a file in the specified path. A that provides read/write access to the file specified in . - object created by this method has a default value of ; no other process or code can access the created file until the original file handle is closed. - - This method is equivalent to the method overload using the default buffer size of 4,096 bytes. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. - - By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example creates a file in the specified path, writes some information to the file, and reads from the file. - + object created by this method has a default value of ; no other process or code can access the created file until the original file handle is closed. + + This method is equivalent to the method overload using the default buffer size of 4,096 bytes. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. + + By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example creates a file in the specified path, writes some information to the file, and reads from the file. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File Create1/CPP/file create1.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Create1/CS/file create1.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Create1/VB/file create1.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Create1/VB/file create1.vb" id="Snippet1"::: + ]]> - The caller does not have the required permission. - - -or- - + The caller does not have the required permission. + + -or- + specified a file that is read-only. - - -or- - + + -or- + specified a file that is hidden. .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -1144,38 +1144,38 @@ Creates or overwrites a file in the specified path, specifying a buffer size. A with the specified buffer size that provides read/write access to the file specified in . - object created by this method has a default value of ; no other process or code can access the created file until the original file handle is closed. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. - - By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example creates a file with the specified buffer size. - + object created by this method has a default value of ; no other process or code can access the created file until the original file handle is closed. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. + + By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example creates a file with the specified buffer size. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File Create2/CPP/file create2.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Create2/CS/file create2.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Create2/VB/file create2.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Create2/VB/file create2.vb" id="Snippet1"::: + ]]> - The caller does not have the required permission. - - -or- - + The caller does not have the required permission. + + -or- + specified a file that is read-only. - - -or- - + + -or- + specified a file that is hidden. .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -1245,27 +1245,27 @@ Creates or overwrites a file in the specified path, specifying a buffer size and options that describe how to create or overwrite the file. A new file with the specified buffer size. - . - - This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. - - By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. + + By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> - The caller does not have the required permission. - - -or- - + The caller does not have the required permission. + + -or- + specified a file that is read-only. - - -or- - + + -or- + specified a file that is hidden. .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -1317,30 +1317,30 @@ Creates or overwrites a file in the specified path, specifying a buffer size, options that describe how to create or overwrite the file, and a value that determines the access control and audit security for the file. A new file with the specified buffer size, file options, and file security. - . - - This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. - - By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. + + By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + > [!IMPORTANT] > This method was ported to .NET Core 3.1 in the following form: . ]]> - The caller does not have the required permission. - - -or- - + The caller does not have the required permission. + + -or- + specified a file that is read-only. - - -or- - + + -or- + specified a file that is hidden. .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -1454,34 +1454,34 @@ An I/O error occurred. Creates or opens a file for writing UTF-8 encoded text. If the file already exists, its contents are overwritten. A that writes to the specified file using UTF-8 encoding. - constructor overload with the `append` parameter set to `false`. If the file specified by `path` does not exist, it is created. If the file does exist, its contents are overwritten. Additional threads are permitted to read the file while it is open. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example creates a file for text writing and reading. - + constructor overload with the `append` parameter set to `false`. If the file specified by `path` does not exist, it is created. If the file does exist, its contents are overwritten. Additional threads are permitted to read the file while it is open. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example creates a file for text writing and reading. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File CreateText/CPP/file createtext.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File CreateText/CS/file createtext.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File CreateText/VB/file createtext.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File CreateText/VB/file createtext.vb" id="Snippet1"::: + ]]> - The caller does not have the required permission. - - -or- - + The caller does not have the required permission. + + -or- + specified a file that is read-only. - - -or- - + + -or- + specified a file that is hidden. .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -1547,55 +1547,55 @@ An I/O error occurred. A path that describes a file to decrypt. Decrypts a file that was encrypted by the current account using the method. - method allows you to decrypt a file that was encrypted using the method. The method can decrypt only files that were encrypted using the current user account. + method allows you to decrypt a file that was encrypted using the method. The method can decrypt only files that were encrypted using the current user account. > [!IMPORTANT] > This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a or , depending on the situation. - > + > > Use of this API in .NET Core is not recommended; it is included to enable portability for applications that move to .NET Core but still explicitly target Windows. - The method requires exclusive access to the file being decrypted, and will raise an exception if another process is using the file. If the file is not encrypted, will return a nonzero value, which indicates success. - - Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. - - The current file system must be formatted as NTFS and the current operating system must be Windows NT or later. - -## Examples - The following code example uses the method and the method to encrypt and then decrypt a file. The file must exist for the example to work. - + The method requires exclusive access to the file being decrypted, and will raise an exception if another process is using the file. If the file is not encrypted, will return a nonzero value, which indicates success. + + Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. + + The current file system must be formatted as NTFS and the current operating system must be Windows NT or later. + +## Examples + The following code example uses the method and the method to encrypt and then decrypt a file. The file must exist for the example to work. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/CS/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/VB/sample.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: The parameter is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. The parameter is . An invalid drive was specified. The file described by the parameter could not be found. - An I/O error occurred while opening the file. For example, the encrypted file is already open. - - -or- - + An I/O error occurred while opening the file. For example, the encrypted file is already open. + + -or- + This operation is not supported on the current platform. The specified path, file name, or both exceed the system-defined maximum length. The current operating system is not Windows NT or later. The file system is not NTFS. - The parameter specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - The parameter specified a directory. - - -or- - + The parameter specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + The parameter specified a directory. + + -or- + The caller does not have the required permission. @@ -1649,49 +1649,49 @@ An I/O error occurred. The name of the file to be deleted. Wildcard characters are not supported. Deletes the specified file. - . - - If the file to be deleted does not exist, no exception is thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example copies groups of files to the C:\archives\2008 backup folder and then deletes them from the source folder. - + . + + If the file to be deleted does not exist, no exception is thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example copies groups of files to the C:\archives\2008 backup folder and then deletes them from the source folder. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/filecopydelete/cs/program.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/filecopydelete/vb/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/filecopydelete/vb/program.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. is . The specified path is invalid (for example, it is on an unmapped drive). - The specified file is in use. - - -or- - + The specified file is in use. + + -or- + There is an open handle on the file, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories and files. For more information, see [How to: Enumerate Directories and Files](/dotnet/standard/io/how-to-enumerate-directories-and-files). is in an invalid format. The specified path, file name, or both exceed the system-defined maximum length. - The caller does not have the required permission. - - -or- - - The file is an executable file that is in use. - - -or- - - is a directory. - - -or- - + The caller does not have the required permission. + + -or- + + The file is an executable file that is in use. + + -or- + + is a directory. + + -or- + specified a read-only file. File and Stream I/O Reading Text From A File @@ -1749,56 +1749,56 @@ An I/O error occurred. A path that describes a file to encrypt. Encrypts a file so that only the account used to encrypt the file can decrypt it. - method allows you to encrypt a file so that only the account used to call this method can decrypt it. Use the method to decrypt a file encrypted by the method. + method allows you to encrypt a file so that only the account used to call this method can decrypt it. Use the method to decrypt a file encrypted by the method. > [!IMPORTANT] > This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a or , depending on the situation. - > + > > Use of this API in .NET Core is not recommended; it is included to enable portability for applications that move to .NET Core but still explicitly target Windows. - The method requires exclusive access to the file being encrypted, and will fail if another process is using the file. - - Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. - - This method is not available on all versions of Windows. For example, it is not available on Home editions. - - The current file system must be formatted as NTFS. - -## Examples - The following code example uses the method and the method to encrypt and then decrypt a file. The file must exist for the example to work. - + The method requires exclusive access to the file being encrypted, and will fail if another process is using the file. + + Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. + + This method is not available on all versions of Windows. For example, it is not available on Home editions. + + The current file system must be formatted as NTFS. + +## Examples + The following code example uses the method and the method to encrypt and then decrypt a file. The file must exist for the example to work. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/CS/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/VB/sample.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: The parameter is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. The parameter is . An invalid drive was specified. The file described by the parameter could not be found. - An I/O error occurred while opening the file. - - -or- - + An I/O error occurred while opening the file. + + -or- + This operation is not supported on the current platform. The specified path, file name, or both exceed the system-defined maximum length. The current operating system is not Windows NT or later. The file system is not NTFS. - The parameter specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - The parameter specified a directory. - - -or- - + The parameter specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + The parameter specified a directory. + + -or- + The caller does not have the required permission. @@ -1855,29 +1855,29 @@ An I/O error occurred. if the caller has the required permissions and contains the name of an existing file; otherwise, . This method also returns if is , an invalid path, or a zero-length string. If the caller does not have sufficient permissions to read the specified file, no exception is thrown and the method returns regardless of the existence of . - method should not be used for path validation, this method merely checks if the file specified in `path` exists. Passing an invalid path to returns `false`. To check whether the path contains any invalid characters, you can call the method to retrieve the characters that are invalid for the file system. You can also create a regular expression to test the whether the path is valid for your environment. For examples of acceptable paths, see . - - To check if a directory exists, see . - - Be aware that another process can potentially do something with the file in between the time you call the method and perform another operation on the file, such as . - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - If `path` describes a directory, this method returns `false`. Trailing spaces are removed from the `path` parameter before determining if the file exists. - - The method returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. - - - -## Examples - The following example determines if a file exists. - + method should not be used for path validation, this method merely checks if the file specified in `path` exists. Passing an invalid path to returns `false`. To check whether the path contains any invalid characters, you can call the method to retrieve the characters that are invalid for the file system. You can also create a regular expression to test the whether the path is valid for your environment. For examples of acceptable paths, see . + + To check if a directory exists, see . + + Be aware that another process can potentially do something with the file in between the time you call the method and perform another operation on the file, such as . + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + If `path` describes a directory, this method returns `false`. Trailing spaces are removed from the `path` parameter before determining if the file exists. + + The method returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. + + + +## Examples + The following example determines if a file exists. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Exists/CS/program.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Exists/VB/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Exists/VB/program.vb" id="Snippet1"::: + ]]> @@ -1895,11 +1895,11 @@ An I/O error occurred. Gets a object that encapsulates the access control list (ACL) entries for a specified file. - methods to retrieve the access control list (ACL) entries for a specified file. - + methods to retrieve the access control list (ACL) entries for a specified file. + ]]> @@ -1938,41 +1938,41 @@ An I/O error occurred. Gets a object that encapsulates the access control list (ACL) entries for a specified file. A object that encapsulates the access control rules for the file described by the parameter. - method to retrieve the access control list (ACL) entries for a file. - - An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - - In NTFS environments, and are granted to the user if the user has rights on the parent folder. To deny and , deny on the parent directory. - - - -## Examples - The following code example uses the and the methods to add and then remove an access control list (ACL) entry from a file. You must supply a valid user or group account to run this example. - + method to retrieve the access control list (ACL) entries for a file. + + An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). + + In NTFS environments, and are granted to the user if the user has rights on the parent folder. To deny and , deny on the parent directory. + + + +## Examples + The following code example uses the and the methods to add and then remove an access control list (ACL) entry from a file. You must supply a valid user or group account to run this example. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/CS/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: + ]]> An I/O error occurred while opening the file. The parameter is . The file could not be found. - The parameter specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - The parameter specified a directory. - - -or- - + The parameter specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + The parameter specified a directory. + + -or- + The caller does not have the required permission. @@ -2012,32 +2012,32 @@ An I/O error occurred. Gets a object that encapsulates the specified type of access control list (ACL) entries for a particular file. A object that encapsulates the access control rules for the file described by the parameter. - method to retrieve the access control list (ACL) entries for a file. - - An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - - In NTFS environments, and are granted to the user if the user has rights on the parent folder. To deny and , deny on the parent directory. - + method to retrieve the access control list (ACL) entries for a file. + + An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). + + In NTFS environments, and are granted to the user if the user has rights on the parent folder. To deny and , deny on the parent directory. + ]]> An I/O error occurred while opening the file. The parameter is . The file could not be found. - The parameter specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - The parameter specified a directory. - - -or- - + The parameter specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + The parameter specified a directory. + + -or- + The caller does not have the required permission. @@ -2092,22 +2092,22 @@ An I/O error occurred. Gets the of the file on the path. The of the file on the path. - . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates the `GetAttributes` and `SetAttributes` methods by applying the `Archive` and `Hidden` attributes to a file. - + . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates the `GetAttributes` and `SetAttributes` methods by applying the `Archive` and `Hidden` attributes to a file. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File GetAttributes/CPP/file getattributes.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File GetAttributes/CS/file getattributes.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File GetAttributes/VB/file getattributes.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File GetAttributes/VB/file getattributes.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is empty, contains only white spaces, or contains invalid characters. @@ -2176,28 +2176,28 @@ An I/O error occurred. Returns the creation date and time of the specified file or directory. A structure set to the creation date and time for the specified file or directory. This value is expressed in local time. - [!NOTE] -> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. - - NTFS-formatted drives may cache information about a file, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates `GetCreationTime`. - - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.getcreationtime/vb/module1.vb" id="Snippet1"::: - +> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. + + NTFS-formatted drives may cache information about a file, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates `GetCreationTime`. + + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.getcreationtime/vb/module1.vb" id="Snippet1"::: + ]]> The caller does not have the required permission. @@ -2264,26 +2264,26 @@ An I/O error occurred. Returns the creation date and time, in coordinated universal time (UTC), of the specified file or directory. A structure set to the creation date and time for the specified file or directory. This value is expressed in UTC time. - [!NOTE] -> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. - - If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). - - NTFS-formatted drives may cache information about a file, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates the method. - - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.getcreationtime/vb/module2.vb" id="Snippet2"::: - +> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. + + If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). + + NTFS-formatted drives may cache information about a file, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates the method. + + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.getcreationtime/vb/module2.vb" id="Snippet2"::: + ]]> The caller does not have the required permission. @@ -2350,28 +2350,28 @@ An I/O error occurred. Returns the date and time the specified file or directory was last accessed. A structure set to the date and time that the specified file or directory was last accessed. This value is expressed in local time. - [!NOTE] -> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. - - If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates `GetLastAccessTime`. - +> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. + + If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates `GetLastAccessTime`. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File GetLastAccess/CPP/file getlastaccess.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File GetLastAccess/CS/file getlastaccess.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File GetLastAccess/VB/file getlastaccess.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File GetLastAccess/VB/file getlastaccess.vb" id="Snippet1"::: + ]]> The caller does not have the required permission. @@ -2438,19 +2438,19 @@ An I/O error occurred. Returns the date and time, in coordinated universal time (UTC), that the specified file or directory was last accessed. A structure set to the date and time that the specified file or directory was last accessed. This value is expressed in UTC time. - [!NOTE] -> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. - - If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. + + If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The caller does not have the required permission. @@ -2517,28 +2517,28 @@ An I/O error occurred. Returns the date and time the specified file or directory was last written to. A structure set to the date and time that the specified file or directory was last written to. This value is expressed in local time. - [!NOTE] -> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. Each operating system manages the last write time according to its own rules. To improve performance, an operating system might not set the last write time value to the exact time of the last write operation, but might set it to a close approximation instead. - - If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates `GetLastWriteTime`. - +> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. Each operating system manages the last write time according to its own rules. To improve performance, an operating system might not set the last write time value to the exact time of the last write operation, but might set it to a close approximation instead. + + If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates `GetLastWriteTime`. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File GetLastWrite/CPP/file getlastwrite.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File GetLastWrite/CS/file getlastwrite.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File GetLastWrite/VB/file getlastwrite.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File GetLastWrite/VB/file getlastwrite.vb" id="Snippet1"::: + ]]> The caller does not have the required permission. @@ -2605,19 +2605,19 @@ An I/O error occurred. Returns the date and time, in coordinated universal time (UTC), that the specified file or directory was last written to. A structure set to the date and time that the specified file or directory was last written to. This value is expressed in UTC time. - [!NOTE] -> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. Each operating system manages the last write time according to its own rules. To improve performance, an operating system might not set the last write time value to the exact time of the last write operation, but might set it to a close approximation instead. - - If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. Each operating system manages the last write time according to its own rules. To improve performance, an operating system might not set the last write time value to the exact time of the last write operation, but might set it to a close approximation instead. + + If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The caller does not have the required permission. @@ -2695,7 +2695,7 @@ Note that if you attempt to replace a file by moving a file of the same name int - In .NET Core 3.0 and later versions, you can call setting the parameter `overwrite` to `true`, which will replace the file if it exists. -- In all .NET versions, you can call to copy with overwrite, then call `Delete` to remove the excess source file. This strategy is advisable if the file being copied is small, and you are looking for an "atomic" file operation. If you `Delete` the file first, and the system or program crashes, the destination file will no longer exist. +- In all .NET versions, you can call to copy with overwrite, then call `Delete` to remove the excess source file. This strategy is advisable if the file being copied is small, and you are looking for an "atomic" file operation. If you `Delete` the file first, and the system or program crashes, the destination file will no longer exist. - In all .NET versions, you can call before calling `Move`, which will only delete the file if it exists. @@ -2889,22 +2889,22 @@ The following example moves a file. Opens a on the specified path with read/write access with no sharing. A opened in the specified mode and path, with read/write access and not shared. - . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example creates a temporary file and writes some text to it. The example then opens the file, using T:System.IO.FileMode.Open; that is, if the file did not already exist, it would not be created. - + . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example creates a temporary file and writes some text to it. The example then opens the file, using T:System.IO.FileMode.Open; that is, if the file did not already exist, it would not be created. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File Open1/CPP/file open1.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Open1/CS/file open1.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Open1/VB/file open1.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Open1/VB/file open1.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -2914,22 +2914,22 @@ The following example moves a file. The specified path is invalid, (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - - The caller does not have the required permission. - - -or- - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + + The caller does not have the required permission. + + -or- + is and the specified file is a hidden file. specified an invalid value. @@ -3040,26 +3040,26 @@ The following example moves a file. Opens a on the specified path, with the specified mode and access with no sharing. An unshared that provides access to the specified file, with the specified mode and access. - . - - - -## Examples - The following example opens a file with read-only access. - + . + + + +## Examples + The following example opens a file with read-only access. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File Open2/CPP/file open2.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Open2/CS/file open2.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Open2/VB/file open2.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Open2/VB/file open2.vb" id="Snippet1"::: + ]]> - .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. - - -or- - + .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. + + -or- + specified and specified , , , or . is . @@ -3067,18 +3067,18 @@ The following example moves a file. The specified path is invalid, (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only and is not . - - -or- - - specified a directory. - - -or- - - The caller does not have the required permission. - - -or- - + specified a file that is read-only and is not . + + -or- + + specified a directory. + + -or- + + The caller does not have the required permission. + + -or- + is and the specified file is a hidden file. or specified an invalid value. @@ -3147,28 +3147,28 @@ The following example moves a file. Opens a on the specified path, having the specified mode with read, write, or read/write access and the specified sharing option. A on the specified path, having the specified mode with read, write, or read/write access and the specified sharing option. - . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example opens a file with read-only access and with file sharing disallowed. - + . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example opens a file with read-only access and with file sharing disallowed. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File Open3/CPP/file open3.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Open3/CS/file open3.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Open3/VB/file open3.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Open3/VB/file open3.vb" id="Snippet1"::: + ]]> - .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. - - -or- - + .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. + + -or- + specified and specified , , , or . is . @@ -3176,18 +3176,18 @@ The following example moves a file. The specified path is invalid, (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only and is not . - - -or- - - specified a directory. - - -or- - - The caller does not have the required permission. - - -or- - + specified a file that is read-only and is not . + + -or- + + specified a directory. + + -or- + + The caller does not have the required permission. + + -or- + is and the specified file is a hidden file. , , or specified an invalid value. @@ -3313,24 +3313,24 @@ The following example moves a file. Opens an existing file for reading. A read-only on the specified path. - constructor overload with a value of , a value of and a value of . - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example opens a file for reading. - + constructor overload with a value of , a value of and a value of . + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example opens a file for reading. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File OpenRead/CPP/file openread.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File OpenRead/CS/file openread.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File OpenRead/VB/file openread.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File OpenRead/VB/file openread.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -3339,10 +3339,10 @@ The following example moves a file. The specified path, file name, or both exceed the system-defined maximum length. The specified path is invalid, (for example, it is on an unmapped drive). - specified a directory. - - -or- - + specified a directory. + + -or- + The caller does not have the required permission. The file specified in was not found. @@ -3405,24 +3405,24 @@ The following example moves a file. Opens an existing UTF-8 encoded text file for reading. A on the specified path. - constructor overload. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example opens a text file for reading. - + constructor overload. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example opens a text file for reading. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File OpenText/CPP/file opentext.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File OpenText/CS/file opentext.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File OpenText/VB/file opentext.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File OpenText/VB/file opentext.vb" id="Snippet1"::: + ]]> The caller does not have the required permission. @@ -3491,34 +3491,34 @@ The following example moves a file. Opens an existing file or creates a new file for writing. An unshared object on the specified path with access. - constructor overload with file mode set to , the access set to , and the share mode set to . - - The method opens a file if one already exists for the file path, or creates a new file if one does not exist. For an existing file, it does not append the new text to the existing text. Instead, it overwrites the existing characters with the new characters. If you overwrite a longer string (such as "This is a test of the OpenWrite method") with a shorter string (such as "Second run"), the file will contain a mix of the strings ("Second runtest of the OpenWrite method"). - - The `path` parameter may specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, use the method. - + constructor overload with file mode set to , the access set to , and the share mode set to . + + The method opens a file if one already exists for the file path, or creates a new file if one does not exist. For an existing file, it does not append the new text to the existing text. Instead, it overwrites the existing characters with the new characters. If you overwrite a longer string (such as "This is a test of the OpenWrite method") with a shorter string (such as "Second run"), the file will contain a mix of the strings ("Second runtest of the OpenWrite method"). + + The `path` parameter may specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, use the method. + The returned does not support reading. To open a file for both reading and writing, use . - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example opens a file for reading and writing. - + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example opens a file for reading and writing. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File OpenWrite/CPP/file openwrite.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File OpenWrite/CS/file openwrite.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File OpenWrite/VB/file openwrite.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File OpenWrite/VB/file openwrite.vb" id="Snippet1"::: + ]]> - The caller does not have the required permission. - - -or- - + The caller does not have the required permission. + + -or- + specified a read-only file or directory. .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -3583,11 +3583,11 @@ The following example moves a file. Opens a binary file, reads the contents of the file into a byte array, and then closes the file. A byte array containing the contents of the file. - .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -3596,14 +3596,14 @@ The following example moves a file. The specified path, file name, or both exceed the system-defined maximum length. The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. The file specified in was not found. @@ -3716,21 +3716,21 @@ The following example moves a file. Opens a text file, reads all lines of the file, and then closes the file. A string array containing all lines of the file. - method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. - + method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllLines/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines/vb/AllText.vb" id="Snippet00"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -3740,18 +3740,18 @@ The following example moves a file. The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. The file specified in was not found. @@ -3815,21 +3815,21 @@ The following example moves a file. Opens a file, reads all lines of the file with the specified encoding, and then closes the file. A string array containing all lines of the file. - method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. - + method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllLines_Encoding/cs/AllText_Encoding.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines_Encoding/vb/AllText_Encoding.vb" id="Snippet00"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines_Encoding/vb/AllText_Encoding.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -3839,21 +3839,21 @@ The following example moves a file. The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - - The caller does not have the required permission. - The file specified in was not found. - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + + The caller does not have the required permission. + The file specified in was not found. + is in an invalid format. The caller does not have the required permission. File and Stream I/O @@ -4006,25 +4006,25 @@ The following example moves a file. Opens a text file, reads all the text in the file, and then closes the file. A string containing all the text in the file. - method overload when reading files that might contain imported text, because unrecognized characters may not be read correctly. - - The file handle is guaranteed to be closed by this method, even if exceptions are raised. - - - -## Examples - The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. - + + This method attempts to automatically detect the encoding of a file based on the presence of byte order marks. Encoding formats UTF-8 and UTF-32 (both big-endian and little-endian) can be detected. + + Use the method overload when reading files that might contain imported text, because unrecognized characters may not be read correctly. + + The file handle is guaranteed to be closed by this method, even if exceptions are raised. + + + +## Examples + The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllText/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText/vb/AllText.vb" id="Snippet00"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -4034,18 +4034,18 @@ The following example moves a file. The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. The file specified in was not found. @@ -4109,25 +4109,25 @@ The following example moves a file. Opens a file, reads all text in the file with the specified encoding, and then closes the file. A string containing all text in the file. - property for the `encoding` parameter. - - - -## Examples - The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. - + + This method attempts to automatically detect the encoding of a file based on the presence of byte order marks. Encoding formats UTF-8 and UTF-32 (both big-endian and little-endian) can be detected. + + The file handle is guaranteed to be closed by this method, even if exceptions are raised. + + To use the encoding settings as configured for your operating system, specify the property for the `encoding` parameter. + + + +## Examples + The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/vb/AllText.vb" id="Snippet00"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -4137,18 +4137,18 @@ The following example moves a file. The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. The file specified in was not found. @@ -4303,34 +4303,34 @@ The following example moves a file. Reads the lines of a file. All the lines of the file, or the lines that are the result of a query. - and methods differ as follows: When you use , you can start enumerating the collection of strings before the whole collection is returned; when you use , you must wait for the whole array of strings be returned before you can access the array. Therefore, when you are working with very large files, can be more efficient. - - You can use the method to do the following: - -- Perform [LINQ to Objects](/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) queries on a file to obtain a filtered set of its lines. - -- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. - -- Create an immediately populated instance of a collection that takes an collection of strings for its constructor, such as a or a . - - This method uses for the encoding value. - - - -## Examples - The following example reads the lines of a file to find lines that contain specified strings. - + and methods differ as follows: When you use , you can start enumerating the collection of strings before the whole collection is returned; when you use , you must wait for the whole array of strings be returned before you can access the array. Therefore, when you are working with very large files, can be more efficient. + + You can use the method to do the following: + +- Perform [LINQ to Objects](/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) queries on a file to obtain a filtered set of its lines. + +- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. + +- Create an immediately populated instance of a collection that takes an collection of strings for its constructor, such as a or a . + + This method uses for the encoding value. + + + +## Examples + The following example reads the lines of a file to find lines that contain specified strings. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.file.readlines/cs/program.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.readlines/vb/program.vb" id="Snippet1"::: - - The following example uses the method in a LINQ query that enumerates all directories for files that have a .txt extension, reads each line of the file, and displays the line if it contains the string "Microsoft". - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.readlines/vb/program.vb" id="Snippet1"::: + + The following example uses the method in a LINQ query that enumerates all directories for files that have a .txt extension, reads each line of the file, and displays the line if it contains the string "Microsoft". + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.directory.enumeratefiles/cs/program.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directory.enumeratefiles/vb/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directory.enumeratefiles/vb/program.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters defined by the method. @@ -4344,18 +4344,18 @@ The following example moves a file. exceeds the system-defined maximum length. The caller does not have the required permission. - specifies a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - is a directory. - - -or- - + specifies a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + is a directory. + + -or- + The caller does not have the required permission. @@ -4410,21 +4410,21 @@ The following example moves a file. Read the lines of a file that has a specified encoding. All the lines of the file, or the lines that are the result of a query. - and methods differ as follows: When you use , you can start enumerating the collection of strings before the whole collection is returned. When you use , you must wait for the whole array of strings be returned before you can access the array. Therefore, when you are working with very large files, can be more efficient. - - You can use the method to do the following: - -- Perform [LINQ to Objects](/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) queries on a file to obtain a filtered set of its lines. - -- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. - -- Create an immediately populated instance of a collection that takes an collection of strings for its constructor, such as a or a . - + and methods differ as follows: When you use , you can start enumerating the collection of strings before the whole collection is returned. When you use , you must wait for the whole array of strings be returned before you can access the array. Therefore, when you are working with very large files, can be more efficient. + + You can use the method to do the following: + +- Perform [LINQ to Objects](/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) queries on a file to obtain a filtered set of its lines. + +- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. + +- Create an immediately populated instance of a collection that takes an collection of strings for its constructor, such as a or a . + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters as defined by the method. @@ -4438,18 +4438,18 @@ The following example moves a file. exceeds the system-defined maximum length. The caller does not have the required permission. - specifies a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - is a directory. - - -or- - + specifies a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + is a directory. + + -or- + The caller does not have the required permission. @@ -4462,11 +4462,11 @@ The following example moves a file. Replaces the contents of a specified file with the contents of another file, deleting the original file, and creating a backup of the replaced file. - methods replace the contents of a specified file with the contents of another file. They also create a backup of the file that was replaced. - + methods replace the contents of a specified file with the contents of another file. They also create a backup of the file that was replaced. + ]]> @@ -4517,59 +4517,61 @@ The following example moves a file. The name of the backup file. Replaces the contents of a specified file with the contents of another file, deleting the original file, and creating a backup of the replaced file. - method replaces the contents of a specified file with the contents of another file. It also creates a backup of the file that was replaced. - - If the `sourceFileName` and `destinationFileName` are on different volumes, this method will raise an exception. If the `destinationBackupFileName` is on a different volume from the source file, the backup file will be deleted. - - Pass `null` to the `destinationBackupFileName` parameter if you do not want to create a backup of the file being replaced. + method replaces the contents of a specified file with the contents of another file. It also creates a backup of the file that was replaced. + + If the `sourceFileName` and `destinationFileName` are on different volumes, this method will raise an exception. If the `destinationBackupFileName` is on a different volume from the source file, the backup file will be deleted. + + Pass `null` to the `destinationBackupFileName` parameter if you do not want to create a backup of the file being replaced. If the `destinationBackupFileName` already exists it will be overwritten with the contents of the `destinationFileName` file. - - - -## Examples - The following code example uses the method to replace a file with another file and create a backup of the replaced file. - + +## Examples + The following code example uses the method to replace a file with another file and create a backup of the replaced file. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/IO.File.Replace/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/IO.File.Replace/CS/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.Replace/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.Replace/VB/sample.vb" id="Snippet1"::: + ]]> - The path described by the parameter was not of a legal form. - - -or- - + The path described by the parameter was not of a legal form. + + -or- + The path described by the parameter was not of a legal form. The parameter is . An invalid drive was specified. - The file described by the current object could not be found. - - -or- - + The file described by the current object could not be found. + + -or- + The file described by the parameter could not be found. - An I/O error occurred while opening the file. - + An I/O error occurred while opening the file. + -or- - + The and parameters specify the same file. The specified path, file name, or both exceed the system-defined maximum length. - The or parameter specifies a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - Source or destination parameters specify a directory instead of a file. - - -or- - - The caller does not have the required permission. + The or parameter specifies a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + Source or destination parameters specify a directory instead of a file. + + -or- + + The caller does not have the required permission. + +-or + + and specify the same existing directory. @@ -4627,59 +4629,61 @@ The following example moves a file. to ignore merge errors (such as attributes and access control lists (ACLs)) from the replaced file to the replacement file; otherwise, . Replaces the contents of a specified file with the contents of another file, deleting the original file, and creating a backup of the replaced file and optionally ignores merge errors. - method replaces the contents of a specified file with the contents of another file. It also creates a backup of the file that was replaced. - - If the `sourceFileName` and `destinationFileName` are on different volumes, this method will raise an exception. If the `destinationBackupFileName` is on a different volume from the source file, the backup file will be deleted. - - Pass `null` to the `destinationBackupFileName` parameter if you do not want to create a backup of the file being replaced. + method replaces the contents of a specified file with the contents of another file. It also creates a backup of the file that was replaced. + + If the `sourceFileName` and `destinationFileName` are on different volumes, this method will raise an exception. If the `destinationBackupFileName` is on a different volume from the source file, the backup file will be deleted. + + Pass `null` to the `destinationBackupFileName` parameter if you do not want to create a backup of the file being replaced. If the `destinationBackupFileName` already exists it will be overwritten with the contents of the `destinationFileName` file. - - - -## Examples - The following code example uses the method to replace a file with another file and create a backup of the replaced file. - + +## Examples + The following code example uses the method to replace a file with another file and create a backup of the replaced file. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/IO.File.Replace/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/IO.File.Replace/CS/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.Replace/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.Replace/VB/sample.vb" id="Snippet1"::: + ]]> - The path described by the parameter was not of a legal form. - - -or- - + The path described by the parameter was not of a legal form. + + -or- + The path described by the parameter was not of a legal form. The parameter is . An invalid drive was specified. - The file described by the current object could not be found. - - -or- - + The file described by the current object could not be found. + + -or- + The file described by the parameter could not be found. - An I/O error occurred while opening the file. - + An I/O error occurred while opening the file. + -or- - + The and parameters specify the same file. The specified path, file name, or both exceed the system-defined maximum length. - The or parameter specifies a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - Source or destination parameters specify a directory instead of a file. - - -or- - - The caller does not have the required permission. + The or parameter specifies a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + Source or destination parameters specify a directory instead of a file. + + -or- + + The caller does not have the required permission. + +-or + + and specify the same existing directory. @@ -4777,58 +4781,58 @@ There are too many levels of symbolic links. A object that describes an ACL entry to apply to the file described by the parameter. Applies access control list (ACL) entries described by a object to the specified file. - method applies access control list (ACL) entries to a file that represents the noninherited ACL list. - + method applies access control list (ACL) entries to a file that represents the noninherited ACL list. + > [!CAUTION] -> The ACL specified for the `fileSecurity` parameter replaces the existing ACL for the file. To add permissions for a new user, use the method to obtain the existing ACL, modify it, and then use to apply it back to the file. - - An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - - The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it is not possible to retrieve a object from one file and reapply the same object to another file. - - To copy ACL information from one file to another: - -1. Use the method to retrieve the object from the source file. - -2. Create a new object for the destination file. - -3. Use the or method of the source object to retrieve the ACL information. - -4. Use the or method to copy the information retrieved in step 3 to the destination object. - -5. Set the destination object to the destination file using the method. - - In NTFS environments, and are granted to the user if the user has rights on the parent folder. To deny and , deny on the parent directory. - - - -## Examples - The following code example uses the and methods to add and then remove an access control list (ACL) entry from a file. You must supply a valid user or group account to run this example. - +> The ACL specified for the `fileSecurity` parameter replaces the existing ACL for the file. To add permissions for a new user, use the method to obtain the existing ACL, modify it, and then use to apply it back to the file. + + An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). + + The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it is not possible to retrieve a object from one file and reapply the same object to another file. + + To copy ACL information from one file to another: + +1. Use the method to retrieve the object from the source file. + +2. Create a new object for the destination file. + +3. Use the or method of the source object to retrieve the ACL information. + +4. Use the or method to copy the information retrieved in step 3 to the destination object. + +5. Set the destination object to the destination file using the method. + + In NTFS environments, and are granted to the user if the user has rights on the parent folder. To deny and , deny on the parent directory. + + + +## Examples + The following code example uses the and methods to add and then remove an access control list (ACL) entry from a file. You must supply a valid user or group account to run this example. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/CS/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: + ]]> An I/O error occurred while opening the file. The parameter is . The file could not be found. - The parameter specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - The parameter specified a directory. - - -or- - + The parameter specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + The parameter specified a directory. + + -or- + The caller does not have the required permission. The parameter is . @@ -4886,26 +4890,26 @@ There are too many levels of symbolic links. A bitwise combination of the enumeration values. Sets the specified of the file on the specified path. - . - - Certain file attributes, such as and , can be combined. Other attributes, such as , must be used alone. - - It is not possible to change the compression status of a object using the method. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates the `GetAttributes` and `SetAttributes` methods by applying the `Archive` and `Hidden` attributes to a file. - + . + + Certain file attributes, such as and , can be combined. Other attributes, such as , must be used alone. + + It is not possible to change the compression status of a object using the method. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates the `GetAttributes` and `SetAttributes` methods by applying the `Archive` and `Hidden` attributes to a file. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File GetAttributes/CPP/file getattributes.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File GetAttributes/CS/file getattributes.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File GetAttributes/VB/file getattributes.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File GetAttributes/VB/file getattributes.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is empty, contains only white spaces, contains invalid characters, or the file attribute is invalid. @@ -4915,18 +4919,18 @@ There are too many levels of symbolic links. The specified path is invalid, (for example, it is on an unmapped drive). The file cannot be found. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. File and Stream I/O @@ -4980,15 +4984,15 @@ There are too many levels of symbolic links. A containing the value to set for the creation date and time of . This value is expressed in local time. Sets the date and time the file was created. - . - - NTFS-formatted drives may cache file meta-info, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + NTFS-formatted drives may cache file meta-info, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The specified path was not found. @@ -5060,15 +5064,15 @@ There are too many levels of symbolic links. A containing the value to set for the creation date and time of . This value is expressed in UTC time. Sets the date and time, in coordinated universal time (UTC), that the file was created. - . - - NTFS-formatted drives may cache file meta-info, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + NTFS-formatted drives may cache file meta-info, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The specified path was not found. @@ -5134,22 +5138,22 @@ There are too many levels of symbolic links. A containing the value to set for the last access date and time of . This value is expressed in local time. Sets the date and time the specified file was last accessed. - . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example checks the file system for the specified file, creating it if necessary, and then sets and gets the last access time. - + . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example checks the file system for the specified file, creating it if necessary, and then sets and gets the last access time. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File SetLastAccess/CPP/file setlastaccess.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File SetLastAccess/CS/file setlastaccess.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File SetLastAccess/VB/file setlastaccess.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File SetLastAccess/VB/file setlastaccess.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -5220,13 +5224,13 @@ There are too many levels of symbolic links. A containing the value to set for the last access date and time of . This value is expressed in UTC time. Sets the date and time, in coordinated universal time (UTC), that the specified file was last accessed. - . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -5291,22 +5295,22 @@ There are too many levels of symbolic links. A containing the value to set for the last write date and time of . This value is expressed in local time. Sets the date and time that the specified file was last written to. - . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example checks the file system for the specified file, creating the file if necessary, and then sets and gets the last write time of the file. - + . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example checks the file system for the specified file, creating the file if necessary, and then sets and gets the last write time of the file. + :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File SetLastWrite/CPP/file setlastwrite.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File SetLastWrite/CS/file setlastwrite.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File SetLastWrite/VB/file setlastwrite.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File SetLastWrite/VB/file setlastwrite.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -5377,13 +5381,13 @@ There are too many levels of symbolic links. A containing the value to set for the last write date and time of . This value is expressed in UTC time. Sets the date and time, in coordinated universal time (UTC), that the specified file was last written to. - . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -5453,11 +5457,11 @@ There are too many levels of symbolic links. The bytes to write to the file. Creates a new file, writes the specified byte array to the file, and then closes the file. If the target file already exists, it is overwritten. - .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -5468,21 +5472,21 @@ There are too many levels of symbolic links. An I/O error occurred while opening the file. specified a file that is read-only. - - -or- - + + -or- + specified a file that is hidden. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. is in an invalid format. @@ -5592,23 +5596,23 @@ There are too many levels of symbolic links. The lines to write to the file. Creates a new file, writes a collection of strings to the file, and then closes the file. - method is to write out data by using UTF-8 encoding without a byte order mark (BOM). If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. - - If the target file already exists, it is overwritten. - - You can use this method to create the contents for a collection class that takes an in its constructor, such as a , , or a class. - - - -## Examples - The following example writes selected lines from a sample data file to a file. - + method is to write out data by using UTF-8 encoding without a byte order mark (BOM). If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. + + If the target file already exists, it is overwritten. + + You can use this method to create the contents for a collection class that takes an in its constructor, such as a , , or a class. + + + +## Examples + The following example writes selected lines from a sample data file to a file. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.file.writeallappendall/cs/program.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.writeallappendall/vb/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.writeallappendall/vb/program.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters defined by the method. @@ -5623,21 +5627,21 @@ There are too many levels of symbolic links. The caller does not have the required permission. specified a file that is read-only. - - -or- - + + -or- + specified a file that is hidden. - - -or- - - This operation is not supported on the current platform. - - -or- - - is a directory. - - -or- - + + -or- + + This operation is not supported on the current platform. + + -or- + + is a directory. + + -or- + The caller does not have the required permission. @@ -5690,23 +5694,23 @@ There are too many levels of symbolic links. The string array to write to the file. Creates a new file, write the specified string array to the file, and then closes the file. - method is to write out data using UTF-8 encoding without a byte order mark (BOM). If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. - - Given a string array and a file path, this method opens the specified file, writes the string array to the file, and then closes the file. - - - -## Examples - The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. - + method is to write out data using UTF-8 encoding without a byte order mark (BOM). If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. + + Given a string array and a file path, this method opens the specified file, writes the string array to the file, and then closes the file. + + + +## Examples + The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllLines/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines/vb/AllText.vb" id="Snippet00"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -5716,21 +5720,21 @@ There are too many levels of symbolic links. An I/O error occurred while opening the file. specified a file that is read-only. - - -or- - - specified a file that is hidden. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + + -or- + + specified a file that is hidden. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. is in an invalid format. @@ -5789,17 +5793,17 @@ There are too many levels of symbolic links. The character encoding to use. Creates a new file by using the specified encoding, writes a collection of strings to the file, and then closes the file. - method. - -- The contents of a collection that implements an of strings. - + method. + +- The contents of a collection that implements an of strings. + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters defined by the method. @@ -5814,21 +5818,21 @@ There are too many levels of symbolic links. The caller does not have the required permission. specified a file that is read-only. - - -or- - - specified a file that is hidden. - - -or- - - This operation is not supported on the current platform. - - -or- - - is a directory. - - -or- - + + -or- + + specified a file that is hidden. + + -or- + + This operation is not supported on the current platform. + + -or- + + is a directory. + + -or- + The caller does not have the required permission. @@ -5883,21 +5887,21 @@ There are too many levels of symbolic links. An object that represents the character encoding applied to the string array. Creates a new file, writes the specified string array to the file by using the specified encoding, and then closes the file. - method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. - + method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllLines_Encoding/cs/AllText_Encoding.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines_Encoding/vb/AllText_Encoding.vb" id="Snippet00"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines_Encoding/vb/AllText_Encoding.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -5907,21 +5911,21 @@ There are too many levels of symbolic links. An I/O error occurred while opening the file. specified a file that is read-only. - - -or- - - specified a file that is hidden. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + + -or- + + specified a file that is hidden. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. is in an invalid format. @@ -6078,21 +6082,21 @@ There are too many levels of symbolic links. The string to write to the file. Creates a new file, writes the specified string to the file, and then closes the file. If the target file already exists, it is overwritten. - method will return an empty byte array. If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. - - Given a string and a file path, this method opens the specified file, writes the string to the file, and then closes the file. - - - -## Examples - The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. - + method will return an empty byte array. If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. + + Given a string and a file path, this method opens the specified file, writes the string to the file, and then closes the file. + + + +## Examples + The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllText/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText/vb/AllText.vb" id="Snippet00"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -6103,21 +6107,21 @@ There are too many levels of symbolic links. An I/O error occurred while opening the file. specified a file that is read-only. - - -or- - - specified a file that is hidden. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + + -or- + + specified a file that is hidden. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. is in an invalid format. @@ -6178,19 +6182,19 @@ There are too many levels of symbolic links. The encoding to apply to the string. Creates a new file, writes the specified string to the file using the specified encoding, and then closes the file. If the target file already exists, it is overwritten. - method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. - + method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. + :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/vb/AllText.vb" id="Snippet00"::: - + :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -6201,21 +6205,21 @@ There are too many levels of symbolic links. An I/O error occurred while opening the file. specified a file that is read-only. - - -or- - - specified a file that is hidden. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + + -or- + + specified a file that is hidden. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. is in an invalid format. From 58a66ca1bb8a4561830a471d00a878b7ff9fb39b Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 23 Mar 2022 21:21:41 -0700 Subject: [PATCH 2/3] reset file --- xml/System.IO/File.xml | 3196 ++++++++++++++++++++-------------------- 1 file changed, 1634 insertions(+), 1562 deletions(-) diff --git a/xml/System.IO/File.xml b/xml/System.IO/File.xml index ccbab5f17dc..ac8e432fa61 100644 --- a/xml/System.IO/File.xml +++ b/xml/System.IO/File.xml @@ -1,10 +1,10 @@ - - + + - + - + @@ -34,11 +34,14 @@ System.Runtime 6.0.0.0 + 7.0.0.0 + + System.Object @@ -53,51 +56,51 @@ Provides static methods for the creation, copying, deletion, moving, and opening of a single file, and aids in the creation of objects. - class for typical operations such as copying, moving, renaming, creating, opening, deleting, and appending to a single file at a time. You can also use the class to get and set file attributes or information related to the creation, access, and writing of a file. If you want to perform operations on multiple files, see or . - - Many of the methods return other I/O types when you create or open files. You can use these other types to further manipulate a file. For more information, see specific members such as , , or . - - Because all methods are static, it might be more efficient to use a method rather than a corresponding instance method if you want to perform only one action. All methods require the path to the file that you are manipulating. - - The static methods of the class perform security checks on all methods. If you are going to reuse an object several times, consider using the corresponding instance method of instead, because the security check will not always be necessary. - - By default, full read/write access to new files is granted to all users. - - The following table describes the enumerations that are used to customize the behavior of various methods. - -|Enumeration|Description| -|-----------------|-----------------| -||Specifies read and write access to a file.| -||Specifies the level of access permitted for a file that is already in use.| -||Specifies whether the contents of an existing file are preserved or overwritten, and whether requests to create an existing file cause an exception.| - + class for typical operations such as copying, moving, renaming, creating, opening, deleting, and appending to a single file at a time. You can also use the class to get and set file attributes or information related to the creation, access, and writing of a file. If you want to perform operations on multiple files, see or . + + Many of the methods return other I/O types when you create or open files. You can use these other types to further manipulate a file. For more information, see specific members such as , , or . + + Because all methods are static, it might be more efficient to use a method rather than a corresponding instance method if you want to perform only one action. All methods require the path to the file that you are manipulating. + + The static methods of the class perform security checks on all methods. If you are going to reuse an object several times, consider using the corresponding instance method of instead, because the security check will not always be necessary. + + By default, full read/write access to new files is granted to all users. + + The following table describes the enumerations that are used to customize the behavior of various methods. + +|Enumeration|Description| +|-----------------|-----------------| +||Specifies read and write access to a file.| +||Specifies the level of access permitted for a file that is already in use.| +||Specifies whether the contents of an existing file are preserved or overwritten, and whether requests to create an existing file cause an exception.| + > [!NOTE] -> In members that accept a path as an input string, that path must be well-formed or an exception is raised. For example, if a path is fully qualified but begins with a space, the path is not trimmed in methods of the class. Therefore, the path is malformed and an exception is raised. Similarly, a path or a combination of paths cannot be fully qualified twice. For example, "c:\temp c:\windows" also raises an exception in most cases. Ensure that your paths are well-formed when using methods that accept a path string. - - In members that accept a path, the path can refer to a file or just a directory. The specified path can also refer to a relative path or a Universal Naming Convention (UNC) path for a server and share name. For example, all the following are acceptable paths: - -- `"c:\\\MyDir\\\MyFile.txt"` in C#, or `"c:\MyDir\MyFile.txt"` in Visual Basic. - +> In members that accept a path as an input string, that path must be well-formed or an exception is raised. For example, if a path is fully qualified but begins with a space, the path is not trimmed in methods of the class. Therefore, the path is malformed and an exception is raised. Similarly, a path or a combination of paths cannot be fully qualified twice. For example, "c:\temp c:\windows" also raises an exception in most cases. Ensure that your paths are well-formed when using methods that accept a path string. + + In members that accept a path, the path can refer to a file or just a directory. The specified path can also refer to a relative path or a Universal Naming Convention (UNC) path for a server and share name. For example, all the following are acceptable paths: + +- `"c:\\\MyDir\\\MyFile.txt"` in C#, or `"c:\MyDir\MyFile.txt"` in Visual Basic. + - `"c:\\\MyDir"` in C#, or `"c:\MyDir"` in Visual Basic. - + - `"MyDir\\\MySubdir"` in C#, or `"MyDir\MySubDir"` in Visual Basic. - + - `"\\\\\\\MyServer\\\MyShare"` in C#, or `"\\\MyServer\MyShare"` in Visual Basic. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates how to use the class to check whether a file exists, and depending on the result, either create a new file and write to it, or open the existing file and read from it. Before running the code, create a `c:\temp` folder. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File Class Example/CPP/file class example.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Class Example/CS/file class example.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Class Example/VB/file class example.vb" id="Snippet1"::: - + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates how to use the class to check whether a file exists, and depending on the result, either create a new file and write to it, or open the existing file and read from it. Before running the code, create a `c:\temp` folder. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File Class Example/CPP/file class example.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/Overview/file class example.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File Class Example/VB/file class example.vb" id="Snippet1"::: + ]]> @@ -149,6 +152,7 @@ System.Runtime 6.0.0.0 + 7.0.0.0 @@ -160,27 +164,27 @@ System.Void - - + + The file to append the lines to. The file is created if it doesn't already exist. The lines to append to the file. Appends lines to a file, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file. - @@ -196,14 +200,14 @@ is in an invalid format. The caller does not have permission to write to the file. - specifies a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - + specifies a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + is a directory. @@ -238,6 +242,7 @@ System.Runtime 6.0.0.0 + 7.0.0.0 @@ -249,9 +254,9 @@ System.Void - - - + + + The file to append the lines to. The file is created if it doesn't already exist. @@ -259,17 +264,17 @@ The character encoding to use. Appends lines to a file by using a specified encoding, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file. - method. - -- The contents of a collection that implements an of strings. - + method. + +- The contents of a collection that implements an of strings. + ]]> @@ -285,18 +290,18 @@ is in an invalid format. The caller does not have the required permission. - specifies a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - is a directory. - - -or- - + specifies a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + is a directory. + + -or- + The caller does not have the required permission. @@ -325,14 +330,15 @@ System.Runtime 6.0.0.0 + 7.0.0.0 System.Threading.Tasks.Task - - - + + + The file to append the lines to. The file is created if it doesn't already exist. @@ -368,15 +374,16 @@ System.Runtime 6.0.0.0 + 7.0.0.0 System.Threading.Tasks.Task - - - - + + + + The file to append the lines to. The file is created if it doesn't already exist. @@ -405,7 +412,7 @@ - + Method System.IO.FileSystem @@ -431,6 +438,7 @@ System.Runtime 6.0.0.0 + 7.0.0.0 @@ -442,29 +450,29 @@ System.Void - - + + The file to append the specified string to. The string to append to the file. Opens a file, appends the specified string to the file, and then closes the file. If the file does not exist, this method creates a file, writes the specified string to the file, then closes the file. - method to add extra text to the end of a file. In this example, a file is created if it doesn't already exist, and text is added to it. However, the directory named `temp` on drive C must exist for the example to complete successfully. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllText/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText/vb/AllText.vb" id="Snippet00"::: - + method to add extra text to the end of a file. In this example, a file is created if it doesn't already exist, and text is added to it. However, the directory named `temp` on drive C must exist for the example to complete successfully. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/AppendAllText/AllText.cs" id="Snippet00"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -474,18 +482,18 @@ The specified path is invalid (for example, the directory doesn't exist or it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. is in an invalid format. @@ -499,7 +507,7 @@ - + Method System.IO.FileSystem @@ -525,6 +533,7 @@ System.Runtime 6.0.0.0 + 7.0.0.0 @@ -536,9 +545,9 @@ System.Void - - - + + + The file to append the specified string to. @@ -546,21 +555,21 @@ The character encoding to use. Appends the specified string to the file using the specified encoding, creating the file if it does not already exist. - method to add extra text to the end of a file. In this example, a file is created if it doesn't already exist, and text is added to it. However, the directory named `temp` on drive C must exist for the example to complete successfully. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/vb/AllText.vb" id="Snippet00"::: - + method to add extra text to the end of a file. In this example, a file is created if it doesn't already exist, and text is added to it. However, the directory named `temp` on drive C must exist for the example to complete successfully. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/AppendAllText/AllText1.cs" id="Snippet00"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -570,18 +579,18 @@ The specified path is invalid (for example, the directory doesn't exist or it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. is in an invalid format. @@ -589,7 +598,7 @@ - + @@ -614,14 +623,15 @@ System.Runtime 6.0.0.0 + 7.0.0.0 System.Threading.Tasks.Task - - - + + + The file to append the specified string to. @@ -633,7 +643,7 @@ - + @@ -658,15 +668,16 @@ System.Runtime 6.0.0.0 + 7.0.0.0 System.Threading.Tasks.Task - - - - + + + + The file to append the specified string to. @@ -711,6 +722,7 @@ System.Runtime 6.0.0.0 + 7.0.0.0 @@ -729,26 +741,26 @@ Creates a that appends UTF-8 encoded text to an existing file, or to a new file if the specified file does not exist. A stream writer that appends UTF-8 encoded text to the specified file or to a new file. - constructor overload. If the file specified by `path` does not exist, it is created. If the file does exist, write operations to the append text to the file. Additional threads are permitted to read the file while it is open. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - The `path` parameter is not case-sensitive. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example appends text to a file. The method creates a new file if the file doesn't exist. However, the directory named `temp` on drive C must exist for the example to complete successfully. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File_AppendText/CPP/file_appendtext.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File_AppendText/CS/file_appendtext.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File_AppendText/VB/file_appendtext.vb" id="Snippet1"::: - + constructor overload. If the file specified by `path` does not exist, it is created. If the file does exist, write operations to the append text to the file. Additional threads are permitted to read the file while it is open. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + The `path` parameter is not case-sensitive. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example appends text to a file. The method creates a new file if the file doesn't exist. However, the directory named `temp` on drive C must exist for the example to complete successfully. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File_AppendText/CPP/file_appendtext.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/AppendText/file_appendtext.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File_AppendText/VB/file_appendtext.vb" id="Snippet1"::: + ]]> The caller does not have the required permission. @@ -809,6 +821,7 @@ System.Runtime 6.0.0.0 + 7.0.0.0 System.Void @@ -822,34 +835,35 @@ The name of the destination file. This cannot be a directory or an existing file. Copies an existing file to a new file. Overwriting a file of the same name is not allowed. - method overload with the `overwrite` parameter set to `false`. - - The `sourceFileName` and `destFileName` parameters can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see the method. This method does not support wildcard characters in the parameters. - - The attributes of the original file are retained in the copied file. - - - -## Examples - The following example copies files to the C:\archives\2008 backup folder. It uses the two overloads of the method as follows: - -- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. - -- It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/filecopydelete/cs/program.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/filecopydelete/vb/program.vb" id="Snippet1"::: - + method overload with the `overwrite` parameter set to `false`. + + The `sourceFileName` and `destFileName` parameters can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see the method. This method does not support wildcard characters in the parameters. + + The attributes of the original file are retained in the copied file. + + + +## Examples + The following example copies files to the C:\archives\2008 backup folder. It uses the two overloads of the method as follows: + +- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. + +- It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/Copy/program.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/filecopydelete/vb/program.vb" id="Snippet1"::: + ]]> The caller does not have the required permission. - .NET Framework and .NET Core versions older than 2.1: or is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. - - -or- - + + or is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. + + -or- + or specifies a directory. or is . @@ -858,10 +872,10 @@ was not found. - exists. - - -or- - + exists. + + -or- + An I/O error has occurred. or is in an invalid format. @@ -906,6 +920,7 @@ System.Runtime 6.0.0.0 + 7.0.0.0 System.Void @@ -922,42 +937,43 @@ if the destination file can be overwritten; otherwise, . Copies an existing file to a new file. Overwriting a file of the same name is allowed. - method as follows: - -- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. - - It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/filecopydelete/cs/program.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/filecopydelete/vb/program.vb" id="Snippet1"::: - + method as follows: + +- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. + + It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/Copy/program.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/filecopydelete/vb/program.vb" id="Snippet1"::: + ]]> - The caller does not have the required permission. - - -or- - + The caller does not have the required permission. + + -or- + is read-only. - - -or- - + + -or- + is , exists and is hidden, but is not hidden. - .NET Framework and .NET Core versions older than 2.1: or is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. - - -or- - + + or is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. + + -or- + or specifies a directory. or is . @@ -966,10 +982,10 @@ was not found. - exists and is . - - -or- - + exists and is . + + -or- + An I/O error has occurred. or is in an invalid format. @@ -1024,6 +1040,7 @@ System.Runtime 6.0.0.0 + 7.0.0.0 @@ -1042,40 +1059,40 @@ Creates or overwrites a file in the specified path. A that provides read/write access to the file specified in . - object created by this method has a default value of ; no other process or code can access the created file until the original file handle is closed. - - This method is equivalent to the method overload using the default buffer size of 4,096 bytes. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. - - By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example creates a file in the specified path, writes some information to the file, and reads from the file. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File Create1/CPP/file create1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Create1/CS/file create1.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Create1/VB/file create1.vb" id="Snippet1"::: - + object created by this method has a default value of ; no other process or code can access the created file until the original file handle is closed. + + This method is equivalent to the method overload using the default buffer size of 4,096 bytes. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. + + By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example creates a file in the specified path, writes some information to the file, and reads from the file. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File Create1/CPP/file create1.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/Create/file create1.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File Create1/VB/file create1.vb" id="Snippet1"::: + ]]> - The caller does not have the required permission. - - -or- - + The caller does not have the required permission. + + -or- + specified a file that is read-only. - - -or- - + + -or- + specified a file that is hidden. .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -1124,6 +1141,7 @@ System.Runtime 6.0.0.0 + 7.0.0.0 @@ -1144,38 +1162,38 @@ Creates or overwrites a file in the specified path, specifying a buffer size. A with the specified buffer size that provides read/write access to the file specified in . - object created by this method has a default value of ; no other process or code can access the created file until the original file handle is closed. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. - - By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example creates a file with the specified buffer size. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File Create2/CPP/file create2.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Create2/CS/file create2.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Create2/VB/file create2.vb" id="Snippet1"::: - + object created by this method has a default value of ; no other process or code can access the created file until the original file handle is closed. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. + + By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example creates a file with the specified buffer size. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File Create2/CPP/file create2.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/Create/file create2.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File Create2/VB/file create2.vb" id="Snippet1"::: + ]]> - The caller does not have the required permission. - - -or- - + The caller does not have the required permission. + + -or- + specified a file that is read-only. - - -or- - + + -or- + specified a file that is hidden. .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -1223,6 +1241,7 @@ System.Runtime 6.0.0.0 + 7.0.0.0 @@ -1234,9 +1253,9 @@ System.IO.FileStream - - - + + + The path and name of the file to create. @@ -1245,27 +1264,27 @@ Creates or overwrites a file in the specified path, specifying a buffer size and options that describe how to create or overwrite the file. A new file with the specified buffer size. - . - - This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. - - By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. + + By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> - The caller does not have the required permission. - - -or- - + The caller does not have the required permission. + + -or- + specified a file that is read-only. - - -or- - + + -or- + specified a file that is hidden. .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -1317,30 +1336,30 @@ Creates or overwrites a file in the specified path, specifying a buffer size, options that describe how to create or overwrite the file, and a value that determines the access control and audit security for the file. A new file with the specified buffer size, file options, and file security. - . - - This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. - - By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are overwritten. + + By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + > [!IMPORTANT] > This method was ported to .NET Core 3.1 in the following form: . ]]> - The caller does not have the required permission. - - -or- - + The caller does not have the required permission. + + -or- + specified a file that is read-only. - - -or- - + + -or- + specified a file that is hidden. .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -1363,6 +1382,7 @@ System.Runtime 6.0.0.0 + 7.0.0.0 System.IO.FileSystem @@ -1377,8 +1397,8 @@ System.IO.FileSystemInfo - - + + The path where the symbolic link should be created. @@ -1436,6 +1456,7 @@ An I/O error occurred. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -1454,34 +1475,34 @@ An I/O error occurred. Creates or opens a file for writing UTF-8 encoded text. If the file already exists, its contents are overwritten. A that writes to the specified file using UTF-8 encoding. - constructor overload with the `append` parameter set to `false`. If the file specified by `path` does not exist, it is created. If the file does exist, its contents are overwritten. Additional threads are permitted to read the file while it is open. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example creates a file for text writing and reading. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File CreateText/CPP/file createtext.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File CreateText/CS/file createtext.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File CreateText/VB/file createtext.vb" id="Snippet1"::: - + constructor overload with the `append` parameter set to `false`. If the file specified by `path` does not exist, it is created. If the file does exist, its contents are overwritten. Additional threads are permitted to read the file while it is open. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example creates a file for text writing and reading. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File CreateText/CPP/file createtext.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/CreateText/file createtext.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File CreateText/VB/file createtext.vb" id="Snippet1"::: + ]]> - The caller does not have the required permission. - - -or- - + The caller does not have the required permission. + + -or- + specified a file that is read-only. - - -or- - + + -or- + specified a file that is hidden. .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -1526,9 +1547,10 @@ An I/O error occurred. System.Runtime 6.0.0.0 + 7.0.0.0 - + [System.Runtime.Versioning.SupportedOSPlatform("windows")] [<System.Runtime.Versioning.SupportedOSPlatform("windows")>] @@ -1541,61 +1563,61 @@ An I/O error occurred. System.Void - + A path that describes a file to decrypt. Decrypts a file that was encrypted by the current account using the method. - method allows you to decrypt a file that was encrypted using the method. The method can decrypt only files that were encrypted using the current user account. + method allows you to decrypt a file that was encrypted using the method. The method can decrypt only files that were encrypted using the current user account. > [!IMPORTANT] > This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a or , depending on the situation. - > + > > Use of this API in .NET Core is not recommended; it is included to enable portability for applications that move to .NET Core but still explicitly target Windows. - The method requires exclusive access to the file being decrypted, and will raise an exception if another process is using the file. If the file is not encrypted, will return a nonzero value, which indicates success. - - Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. - - The current file system must be formatted as NTFS and the current operating system must be Windows NT or later. - -## Examples - The following code example uses the method and the method to encrypt and then decrypt a file. The file must exist for the example to work. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/cpp/sample.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/CS/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/VB/sample.vb" id="Snippet1"::: - + The method requires exclusive access to the file being decrypted, and will raise an exception if another process is using the file. If the file is not encrypted, will return a nonzero value, which indicates success. + + Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. + + The current file system must be formatted as NTFS and the current operating system must be Windows NT or later. + +## Examples + The following code example uses the method and the method to encrypt and then decrypt a file. The file must exist for the example to work. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/cpp/sample.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/Decrypt/sample.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/VB/sample.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: The parameter is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. The parameter is . An invalid drive was specified. The file described by the parameter could not be found. - An I/O error occurred while opening the file. For example, the encrypted file is already open. - - -or- - + An I/O error occurred while opening the file. For example, the encrypted file is already open. + + -or- + This operation is not supported on the current platform. The specified path, file name, or both exceed the system-defined maximum length. The current operating system is not Windows NT or later. The file system is not NTFS. - The parameter specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - The parameter specified a directory. - - -or- - + The parameter specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + The parameter specified a directory. + + -or- + The caller does not have the required permission. @@ -1632,6 +1654,7 @@ An I/O error occurred. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -1649,49 +1672,49 @@ An I/O error occurred. The name of the file to be deleted. Wildcard characters are not supported. Deletes the specified file. - . - - If the file to be deleted does not exist, no exception is thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example copies groups of files to the C:\archives\2008 backup folder and then deletes them from the source folder. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/filecopydelete/cs/program.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/filecopydelete/vb/program.vb" id="Snippet1"::: - + . + + If the file to be deleted does not exist, no exception is thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example copies groups of files to the C:\archives\2008 backup folder and then deletes them from the source folder. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/Copy/program.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/filecopydelete/vb/program.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. is . The specified path is invalid (for example, it is on an unmapped drive). - The specified file is in use. - - -or- - + The specified file is in use. + + -or- + There is an open handle on the file, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories and files. For more information, see [How to: Enumerate Directories and Files](/dotnet/standard/io/how-to-enumerate-directories-and-files). is in an invalid format. The specified path, file name, or both exceed the system-defined maximum length. - The caller does not have the required permission. - - -or- - - The file is an executable file that is in use. - - -or- - - is a directory. - - -or- - + The caller does not have the required permission. + + -or- + + The file is an executable file that is in use. + + -or- + + is a directory. + + -or- + specified a read-only file. File and Stream I/O Reading Text From A File @@ -1728,9 +1751,10 @@ An I/O error occurred. System.Runtime 6.0.0.0 + 7.0.0.0 - + [System.Runtime.Versioning.SupportedOSPlatform("windows")] [<System.Runtime.Versioning.SupportedOSPlatform("windows")>] @@ -1743,62 +1767,62 @@ An I/O error occurred. System.Void - + A path that describes a file to encrypt. Encrypts a file so that only the account used to encrypt the file can decrypt it. - method allows you to encrypt a file so that only the account used to call this method can decrypt it. Use the method to decrypt a file encrypted by the method. + method allows you to encrypt a file so that only the account used to call this method can decrypt it. Use the method to decrypt a file encrypted by the method. > [!IMPORTANT] > This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a or , depending on the situation. - > + > > Use of this API in .NET Core is not recommended; it is included to enable portability for applications that move to .NET Core but still explicitly target Windows. - The method requires exclusive access to the file being encrypted, and will fail if another process is using the file. - - Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. - - This method is not available on all versions of Windows. For example, it is not available on Home editions. - - The current file system must be formatted as NTFS. - -## Examples - The following code example uses the method and the method to encrypt and then decrypt a file. The file must exist for the example to work. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/cpp/sample.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/CS/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/VB/sample.vb" id="Snippet1"::: - + The method requires exclusive access to the file being encrypted, and will fail if another process is using the file. + + Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. + + This method is not available on all versions of Windows. For example, it is not available on Home editions. + + The current file system must be formatted as NTFS. + +## Examples + The following code example uses the method and the method to encrypt and then decrypt a file. The file must exist for the example to work. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/cpp/sample.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/Decrypt/sample.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.File.Encrypt-Decrypt/VB/sample.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: The parameter is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. The parameter is . An invalid drive was specified. The file described by the parameter could not be found. - An I/O error occurred while opening the file. - - -or- - + An I/O error occurred while opening the file. + + -or- + This operation is not supported on the current platform. The specified path, file name, or both exceed the system-defined maximum length. The current operating system is not Windows NT or later. The file system is not NTFS. - The parameter specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - The parameter specified a directory. - - -or- - + The parameter specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + The parameter specified a directory. + + -or- + The caller does not have the required permission. @@ -1809,7 +1833,7 @@ An I/O error occurred. - + Method System.IO.FileSystem @@ -1836,6 +1860,7 @@ An I/O error occurred. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -1855,29 +1880,29 @@ An I/O error occurred. if the caller has the required permissions and contains the name of an existing file; otherwise, . This method also returns if is , an invalid path, or a zero-length string. If the caller does not have sufficient permissions to read the specified file, no exception is thrown and the method returns regardless of the existence of . - method should not be used for path validation, this method merely checks if the file specified in `path` exists. Passing an invalid path to returns `false`. To check whether the path contains any invalid characters, you can call the method to retrieve the characters that are invalid for the file system. You can also create a regular expression to test the whether the path is valid for your environment. For examples of acceptable paths, see . - - To check if a directory exists, see . - - Be aware that another process can potentially do something with the file in between the time you call the method and perform another operation on the file, such as . - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - If `path` describes a directory, this method returns `false`. Trailing spaces are removed from the `path` parameter before determining if the file exists. - - The method returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. - - - -## Examples - The following example determines if a file exists. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Exists/CS/program.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Exists/VB/program.vb" id="Snippet1"::: - + method should not be used for path validation, this method merely checks if the file specified in `path` exists. Passing an invalid path to returns `false`. To check whether the path contains any invalid characters, you can call the method to retrieve the characters that are invalid for the file system. You can also create a regular expression to test the whether the path is valid for your environment. For examples of acceptable paths, see . + + To check if a directory exists, see . + + Be aware that another process can potentially do something with the file in between the time you call the method and perform another operation on the file, such as . + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + If `path` describes a directory, this method returns `false`. Trailing spaces are removed from the `path` parameter before determining if the file exists. + + The method returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. + + + +## Examples + The following example determines if a file exists. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/Exists/program.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File Exists/VB/program.vb" id="Snippet1"::: + ]]> @@ -1895,11 +1920,11 @@ An I/O error occurred. Gets a object that encapsulates the access control list (ACL) entries for a specified file. - methods to retrieve the access control list (ACL) entries for a specified file. - + methods to retrieve the access control list (ACL) entries for a specified file. + ]]> @@ -1938,41 +1963,41 @@ An I/O error occurred. Gets a object that encapsulates the access control list (ACL) entries for a specified file. A object that encapsulates the access control rules for the file described by the parameter. - method to retrieve the access control list (ACL) entries for a file. - - An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - - In NTFS environments, and are granted to the user if the user has rights on the parent folder. To deny and , deny on the parent directory. - - - -## Examples - The following code example uses the and the methods to add and then remove an access control list (ACL) entry from a file. You must supply a valid user or group account to run this example. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/cpp/sample.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/CS/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: - + method to retrieve the access control list (ACL) entries for a file. + + An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). + + In NTFS environments, and are granted to the user if the user has rights on the parent folder. To deny and , deny on the parent directory. + + + +## Examples + The following code example uses the and the methods to add and then remove an access control list (ACL) entry from a file. You must supply a valid user or group account to run this example. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/cpp/sample.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/GetAccessControl/sample.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: + ]]> An I/O error occurred while opening the file. The parameter is . The file could not be found. - The parameter specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - The parameter specified a directory. - - -or- - + The parameter specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + The parameter specified a directory. + + -or- + The caller does not have the required permission. @@ -2012,32 +2037,32 @@ An I/O error occurred. Gets a object that encapsulates the specified type of access control list (ACL) entries for a particular file. A object that encapsulates the access control rules for the file described by the parameter. - method to retrieve the access control list (ACL) entries for a file. - - An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - - In NTFS environments, and are granted to the user if the user has rights on the parent folder. To deny and , deny on the parent directory. - + method to retrieve the access control list (ACL) entries for a file. + + An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). + + In NTFS environments, and are granted to the user if the user has rights on the parent folder. To deny and , deny on the parent directory. + ]]> An I/O error occurred while opening the file. The parameter is . The file could not be found. - The parameter specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - The parameter specified a directory. - - -or- - + The parameter specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + The parameter specified a directory. + + -or- + The caller does not have the required permission. @@ -2074,6 +2099,7 @@ An I/O error occurred. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -2092,22 +2118,22 @@ An I/O error occurred. Gets the of the file on the path. The of the file on the path. - . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates the `GetAttributes` and `SetAttributes` methods by applying the `Archive` and `Hidden` attributes to a file. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File GetAttributes/CPP/file getattributes.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File GetAttributes/CS/file getattributes.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File GetAttributes/VB/file getattributes.vb" id="Snippet1"::: - + . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates the `GetAttributes` and `SetAttributes` methods by applying the `Archive` and `Hidden` attributes to a file. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File GetAttributes/CPP/file getattributes.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/GetAttributes/file getattributes.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File GetAttributes/VB/file getattributes.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is empty, contains only white spaces, or contains invalid characters. @@ -2158,6 +2184,7 @@ An I/O error occurred. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -2176,28 +2203,28 @@ An I/O error occurred. Returns the creation date and time of the specified file or directory. A structure set to the creation date and time for the specified file or directory. This value is expressed in local time. - [!NOTE] -> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. - - NTFS-formatted drives may cache information about a file, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates `GetCreationTime`. - - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.getcreationtime/vb/module1.vb" id="Snippet1"::: - +> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. + + NTFS-formatted drives may cache information about a file, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates `GetCreationTime`. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.getcreationtime/vb/module1.vb" id="Snippet1"::: + ]]> The caller does not have the required permission. @@ -2246,6 +2273,7 @@ An I/O error occurred. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -2264,26 +2292,26 @@ An I/O error occurred. Returns the creation date and time, in coordinated universal time (UTC), of the specified file or directory. A structure set to the creation date and time for the specified file or directory. This value is expressed in UTC time. - [!NOTE] -> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. - - If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). - - NTFS-formatted drives may cache information about a file, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates the method. - - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.getcreationtime/vb/module2.vb" id="Snippet2"::: - +> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. + + If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). + + NTFS-formatted drives may cache information about a file, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates the method. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.getcreationtime/vb/module2.vb" id="Snippet2"::: + ]]> The caller does not have the required permission. @@ -2332,6 +2360,7 @@ An I/O error occurred. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -2350,28 +2379,28 @@ An I/O error occurred. Returns the date and time the specified file or directory was last accessed. A structure set to the date and time that the specified file or directory was last accessed. This value is expressed in local time. - [!NOTE] -> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. - - If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates `GetLastAccessTime`. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File GetLastAccess/CPP/file getlastaccess.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File GetLastAccess/CS/file getlastaccess.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File GetLastAccess/VB/file getlastaccess.vb" id="Snippet1"::: - +> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. + + If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates `GetLastAccessTime`. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File GetLastAccess/CPP/file getlastaccess.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/GetLastAccessTime/file getlastaccess.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File GetLastAccess/VB/file getlastaccess.vb" id="Snippet1"::: + ]]> The caller does not have the required permission. @@ -2420,6 +2449,7 @@ An I/O error occurred. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -2438,19 +2468,19 @@ An I/O error occurred. Returns the date and time, in coordinated universal time (UTC), that the specified file or directory was last accessed. A structure set to the date and time that the specified file or directory was last accessed. This value is expressed in UTC time. - [!NOTE] -> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. - - If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. + + If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The caller does not have the required permission. @@ -2499,6 +2529,7 @@ An I/O error occurred. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -2517,28 +2548,28 @@ An I/O error occurred. Returns the date and time the specified file or directory was last written to. A structure set to the date and time that the specified file or directory was last written to. This value is expressed in local time. - [!NOTE] -> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. Each operating system manages the last write time according to its own rules. To improve performance, an operating system might not set the last write time value to the exact time of the last write operation, but might set it to a close approximation instead. - - If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates `GetLastWriteTime`. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File GetLastWrite/CPP/file getlastwrite.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File GetLastWrite/CS/file getlastwrite.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File GetLastWrite/VB/file getlastwrite.vb" id="Snippet1"::: - +> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. Each operating system manages the last write time according to its own rules. To improve performance, an operating system might not set the last write time value to the exact time of the last write operation, but might set it to a close approximation instead. + + If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates `GetLastWriteTime`. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File GetLastWrite/CPP/file getlastwrite.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/GetLastWriteTime/file getlastwrite.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File GetLastWrite/VB/file getlastwrite.vb" id="Snippet1"::: + ]]> The caller does not have the required permission. @@ -2587,6 +2618,7 @@ An I/O error occurred. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -2605,19 +2637,19 @@ An I/O error occurred. Returns the date and time, in coordinated universal time (UTC), that the specified file or directory was last written to. A structure set to the date and time that the specified file or directory was last written to. This value is expressed in UTC time. - [!NOTE] -> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. Each operating system manages the last write time according to its own rules. To improve performance, an operating system might not set the last write time value to the exact time of the last write operation, but might set it to a close approximation instead. - - If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. Each operating system manages the last write time according to its own rules. To improve performance, an operating system might not set the last write time value to the exact time of the last write operation, but might set it to a close approximation instead. + + If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The caller does not have the required permission. @@ -2666,6 +2698,7 @@ An I/O error occurred. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -2695,7 +2728,7 @@ Note that if you attempt to replace a file by moving a file of the same name int - In .NET Core 3.0 and later versions, you can call setting the parameter `overwrite` to `true`, which will replace the file if it exists. -- In all .NET versions, you can call to copy with overwrite, then call `Delete` to remove the excess source file. This strategy is advisable if the file being copied is small, and you are looking for an "atomic" file operation. If you `Delete` the file first, and the system or program crashes, the destination file will no longer exist. +- In all .NET versions, you can call to copy with overwrite, then call `Delete` to remove the excess source file. This strategy is advisable if the file being copied is small, and you are looking for an "atomic" file operation. If you `Delete` the file first, and the system or program crashes, the destination file will no longer exist. - In all .NET versions, you can call before calling `Move`, which will only delete the file if it exists. @@ -2711,9 +2744,9 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The following example moves a file. -:::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File Move/CPP/file move.cpp" id="Snippet1"::: -:::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Move/CS/file move.cs" id="Snippet1"::: -:::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Move/VB/file move.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File Move/CPP/file move.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.IO/File/Move/file move.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File Move/VB/file move.vb" id="Snippet1"::: ]]> @@ -2764,14 +2797,15 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 System.Void - - - + + + The name of the file to move. Can include a relative or absolute path. @@ -2798,9 +2832,9 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The following example moves a file. -:::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File Move/CPP/file move.cpp" id="Snippet1"::: -:::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Move/CS/file move.cs" id="Snippet1"::: -:::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Move/VB/file move.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File Move/CPP/file move.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.IO/File/Move/file move.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File Move/VB/file move.vb" id="Snippet1"::: ]]> @@ -2869,6 +2903,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -2889,22 +2924,22 @@ The following example moves a file. Opens a on the specified path with read/write access with no sharing. A opened in the specified mode and path, with read/write access and not shared. - . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example creates a temporary file and writes some text to it. The example then opens the file, using T:System.IO.FileMode.Open; that is, if the file did not already exist, it would not be created. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File Open1/CPP/file open1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Open1/CS/file open1.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Open1/VB/file open1.vb" id="Snippet1"::: - + . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example creates a temporary file and writes some text to it. The example then opens the file, using T:System.IO.FileMode.Open; that is, if the file did not already exist, it would not be created. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File Open1/CPP/file open1.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/Open/file open1.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File Open1/VB/file open1.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -2914,22 +2949,22 @@ The following example moves a file. The specified path is invalid, (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - - The caller does not have the required permission. - - -or- - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + + The caller does not have the required permission. + + -or- + is and the specified file is a hidden file. specified an invalid value. @@ -2952,6 +2987,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 System.IO.FileSystem @@ -2966,8 +3002,8 @@ The following example moves a file. System.IO.FileStream - - + + The path of the file to open. @@ -3018,6 +3054,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -3040,26 +3077,26 @@ The following example moves a file. Opens a on the specified path, with the specified mode and access with no sharing. An unshared that provides access to the specified file, with the specified mode and access. - . - - - -## Examples - The following example opens a file with read-only access. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File Open2/CPP/file open2.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Open2/CS/file open2.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Open2/VB/file open2.vb" id="Snippet1"::: - + . + + + +## Examples + The following example opens a file with read-only access. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File Open2/CPP/file open2.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/Open/file open2.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File Open2/VB/file open2.vb" id="Snippet1"::: + ]]> - .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. - - -or- - + .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. + + -or- + specified and specified , , , or . is . @@ -3067,18 +3104,18 @@ The following example moves a file. The specified path is invalid, (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only and is not . - - -or- - - specified a directory. - - -or- - - The caller does not have the required permission. - - -or- - + specified a file that is read-only and is not . + + -or- + + specified a directory. + + -or- + + The caller does not have the required permission. + + -or- + is and the specified file is a hidden file. or specified an invalid value. @@ -3123,6 +3160,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -3147,28 +3185,28 @@ The following example moves a file. Opens a on the specified path, having the specified mode with read, write, or read/write access and the specified sharing option. A on the specified path, having the specified mode with read, write, or read/write access and the specified sharing option. - . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example opens a file with read-only access and with file sharing disallowed. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File Open3/CPP/file open3.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File Open3/CS/file open3.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File Open3/VB/file open3.vb" id="Snippet1"::: - + . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example opens a file with read-only access and with file sharing disallowed. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File Open3/CPP/file open3.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/Open/file open3.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File Open3/VB/file open3.vb" id="Snippet1"::: + ]]> - .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. - - -or- - + .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. + + -or- + specified and specified , , , or . is . @@ -3176,18 +3214,18 @@ The following example moves a file. The specified path is invalid, (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only and is not . - - -or- - - specified a directory. - - -or- - - The caller does not have the required permission. - - -or- - + specified a file that is read-only and is not . + + -or- + + specified a directory. + + -or- + + The caller does not have the required permission. + + -or- + is and the specified file is a hidden file. , , or specified an invalid value. @@ -3209,6 +3247,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 System.IO.FileSystem @@ -3223,12 +3262,12 @@ The following example moves a file. Microsoft.Win32.SafeHandles.SafeFileHandle - - - - - - + + + + + + A relative or absolute path for the file that the current instance will encapsulate. @@ -3295,6 +3334,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -3313,24 +3353,24 @@ The following example moves a file. Opens an existing file for reading. A read-only on the specified path. - constructor overload with a value of , a value of and a value of . - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example opens a file for reading. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File OpenRead/CPP/file openread.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File OpenRead/CS/file openread.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File OpenRead/VB/file openread.vb" id="Snippet1"::: - + constructor overload with a value of , a value of and a value of . + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example opens a file for reading. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File OpenRead/CPP/file openread.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/OpenRead/file openread.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File OpenRead/VB/file openread.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -3339,10 +3379,10 @@ The following example moves a file. The specified path, file name, or both exceed the system-defined maximum length. The specified path is invalid, (for example, it is on an unmapped drive). - specified a directory. - - -or- - + specified a directory. + + -or- + The caller does not have the required permission. The file specified in was not found. @@ -3387,6 +3427,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -3405,24 +3446,24 @@ The following example moves a file. Opens an existing UTF-8 encoded text file for reading. A on the specified path. - constructor overload. - - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example opens a text file for reading. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File OpenText/CPP/file opentext.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File OpenText/CS/file opentext.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File OpenText/VB/file opentext.vb" id="Snippet1"::: - + constructor overload. + + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example opens a text file for reading. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File OpenText/CPP/file opentext.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/OpenText/file opentext.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File OpenText/VB/file opentext.vb" id="Snippet1"::: + ]]> The caller does not have the required permission. @@ -3473,6 +3514,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -3491,34 +3533,34 @@ The following example moves a file. Opens an existing file or creates a new file for writing. An unshared object on the specified path with access. - constructor overload with file mode set to , the access set to , and the share mode set to . - - The method opens a file if one already exists for the file path, or creates a new file if one does not exist. For an existing file, it does not append the new text to the existing text. Instead, it overwrites the existing characters with the new characters. If you overwrite a longer string (such as "This is a test of the OpenWrite method") with a shorter string (such as "Second run"), the file will contain a mix of the strings ("Second runtest of the OpenWrite method"). - - The `path` parameter may specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, use the method. - + constructor overload with file mode set to , the access set to , and the share mode set to . + + The method opens a file if one already exists for the file path, or creates a new file if one does not exist. For an existing file, it does not append the new text to the existing text. Instead, it overwrites the existing characters with the new characters. If you overwrite a longer string (such as "This is a test of the OpenWrite method") with a shorter string (such as "Second run"), the file will contain a mix of the strings ("Second runtest of the OpenWrite method"). + + The `path` parameter may specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, use the method. + The returned does not support reading. To open a file for both reading and writing, use . - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example opens a file for reading and writing. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File OpenWrite/CPP/file openwrite.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File OpenWrite/CS/file openwrite.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File OpenWrite/VB/file openwrite.vb" id="Snippet1"::: - + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example opens a file for reading and writing. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File OpenWrite/CPP/file openwrite.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/OpenWrite/file openwrite.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File OpenWrite/VB/file openwrite.vb" id="Snippet1"::: + ]]> - The caller does not have the required permission. - - -or- - + The caller does not have the required permission. + + -or- + specified a read-only file or directory. .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -3565,6 +3607,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -3576,18 +3619,18 @@ The following example moves a file. System.Byte[] - + The file to open for reading. Opens a binary file, reads the contents of the file into a byte array, and then closes the file. A byte array containing the contents of the file. - .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -3596,14 +3639,14 @@ The following example moves a file. The specified path, file name, or both exceed the system-defined maximum length. The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. The file specified in was not found. @@ -3640,13 +3683,14 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 System.Threading.Tasks.Task<System.Byte[]> - - + + The file to open for reading. @@ -3698,6 +3742,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -3709,28 +3754,28 @@ The following example moves a file. System.String[] - + The file to open for reading. Opens a text file, reads all lines of the file, and then closes the file. A string array containing all lines of the file. - method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllLines/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines/vb/AllText.vb" id="Snippet00"::: - + method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/ReadAllLines/AllText.cs" id="Snippet00"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -3740,18 +3785,18 @@ The following example moves a file. The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. The file specified in was not found. @@ -3795,6 +3840,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -3806,8 +3852,8 @@ The following example moves a file. System.String[] - - + + The file to open for reading. @@ -3815,21 +3861,21 @@ The following example moves a file. Opens a file, reads all lines of the file with the specified encoding, and then closes the file. A string array containing all lines of the file. - method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllLines_Encoding/cs/AllText_Encoding.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines_Encoding/vb/AllText_Encoding.vb" id="Snippet00"::: - + method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/ReadAllLines/AllText_Encoding.cs" id="Snippet00"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines_Encoding/vb/AllText_Encoding.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -3839,18 +3885,18 @@ The following example moves a file. The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. The file specified in was not found. @@ -3887,13 +3933,14 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 System.Threading.Tasks.Task<System.String[]> - - + + The file to open for reading. @@ -3928,14 +3975,15 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 System.Threading.Tasks.Task<System.String[]> - - - + + + The file to open for reading. @@ -3988,6 +4036,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -3999,32 +4048,32 @@ The following example moves a file. System.String - + The file to open for reading. Opens a text file, reads all the text in the file, and then closes the file. A string containing all the text in the file. - method overload when reading files that might contain imported text, because unrecognized characters may not be read correctly. - - The file handle is guaranteed to be closed by this method, even if exceptions are raised. - - - -## Examples - The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllText/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText/vb/AllText.vb" id="Snippet00"::: - + + This method attempts to automatically detect the encoding of a file based on the presence of byte order marks. Encoding formats UTF-8 and UTF-32 (both big-endian and little-endian) can be detected. + + Use the method overload when reading files that might contain imported text, because unrecognized characters may not be read correctly. + + The file handle is guaranteed to be closed by this method, even if exceptions are raised. + + + +## Examples + The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/AppendAllText/AllText.cs" id="Snippet00"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -4034,18 +4083,18 @@ The following example moves a file. The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. The file specified in was not found. @@ -4089,6 +4138,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -4100,8 +4150,8 @@ The following example moves a file. System.String - - + + The file to open for reading. @@ -4109,25 +4159,25 @@ The following example moves a file. Opens a file, reads all text in the file with the specified encoding, and then closes the file. A string containing all text in the file. - property for the `encoding` parameter. - - - -## Examples - The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/vb/AllText.vb" id="Snippet00"::: - + + This method attempts to automatically detect the encoding of a file based on the presence of byte order marks. Encoding formats UTF-8 and UTF-32 (both big-endian and little-endian) can be detected. + + The file handle is guaranteed to be closed by this method, even if exceptions are raised. + + To use the encoding settings as configured for your operating system, specify the property for the `encoding` parameter. + + + +## Examples + The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/AppendAllText/AllText1.cs" id="Snippet00"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -4137,18 +4187,18 @@ The following example moves a file. The specified path is invalid (for example, it is on an unmapped drive). An I/O error occurred while opening the file. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. The file specified in was not found. @@ -4185,13 +4235,14 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 System.Threading.Tasks.Task<System.String> - - + + The file to open for reading. @@ -4226,14 +4277,15 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 System.Threading.Tasks.Task<System.String> - - - + + + The file to open for reading. @@ -4285,6 +4337,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -4296,41 +4349,41 @@ The following example moves a file. System.Collections.Generic.IEnumerable<System.String> - + The file to read. Reads the lines of a file. All the lines of the file, or the lines that are the result of a query. - and methods differ as follows: When you use , you can start enumerating the collection of strings before the whole collection is returned; when you use , you must wait for the whole array of strings be returned before you can access the array. Therefore, when you are working with very large files, can be more efficient. - - You can use the method to do the following: - -- Perform [LINQ to Objects](/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) queries on a file to obtain a filtered set of its lines. - -- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. - -- Create an immediately populated instance of a collection that takes an collection of strings for its constructor, such as a or a . - - This method uses for the encoding value. - - - -## Examples - The following example reads the lines of a file to find lines that contain specified strings. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.file.readlines/cs/program.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.readlines/vb/program.vb" id="Snippet1"::: - - The following example uses the method in a LINQ query that enumerates all directories for files that have a .txt extension, reads each line of the file, and displays the line if it contains the string "Microsoft". - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.directory.enumeratefiles/cs/program.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directory.enumeratefiles/vb/program.vb" id="Snippet1"::: - + and methods differ as follows: When you use , you can start enumerating the collection of strings before the whole collection is returned; when you use , you must wait for the whole array of strings be returned before you can access the array. Therefore, when you are working with very large files, can be more efficient. + + You can use the method to do the following: + +- Perform [LINQ to Objects](/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) queries on a file to obtain a filtered set of its lines. + +- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. + +- Create an immediately populated instance of a collection that takes an collection of strings for its constructor, such as a or a . + + This method uses for the encoding value. + + + +## Examples + The following example reads the lines of a file to find lines that contain specified strings. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/ReadLines/program.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.readlines/vb/program.vb" id="Snippet1"::: + + The following example uses the method in a LINQ query that enumerates all directories for files that have a .txt extension, reads each line of the file, and displays the line if it contains the string "Microsoft". + + :::code language="csharp" source="~/snippets/csharp/System.IO/Directory/EnumerateFiles/program.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directory.enumeratefiles/vb/program.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters defined by the method. @@ -4344,18 +4397,18 @@ The following example moves a file. exceeds the system-defined maximum length. The caller does not have the required permission. - specifies a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - is a directory. - - -or- - + specifies a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + is a directory. + + -or- + The caller does not have the required permission. @@ -4390,6 +4443,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -4401,8 +4455,8 @@ The following example moves a file. System.Collections.Generic.IEnumerable<System.String> - - + + The file to read. @@ -4410,21 +4464,21 @@ The following example moves a file. Read the lines of a file that has a specified encoding. All the lines of the file, or the lines that are the result of a query. - and methods differ as follows: When you use , you can start enumerating the collection of strings before the whole collection is returned. When you use , you must wait for the whole array of strings be returned before you can access the array. Therefore, when you are working with very large files, can be more efficient. - - You can use the method to do the following: - -- Perform [LINQ to Objects](/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) queries on a file to obtain a filtered set of its lines. - -- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. - -- Create an immediately populated instance of a collection that takes an collection of strings for its constructor, such as a or a . - + and methods differ as follows: When you use , you can start enumerating the collection of strings before the whole collection is returned. When you use , you must wait for the whole array of strings be returned before you can access the array. Therefore, when you are working with very large files, can be more efficient. + + You can use the method to do the following: + +- Perform [LINQ to Objects](/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) queries on a file to obtain a filtered set of its lines. + +- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. + +- Create an immediately populated instance of a collection that takes an collection of strings for its constructor, such as a or a . + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters as defined by the method. @@ -4438,18 +4492,18 @@ The following example moves a file. exceeds the system-defined maximum length. The caller does not have the required permission. - specifies a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - is a directory. - - -or- - + specifies a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + is a directory. + + -or- + The caller does not have the required permission. @@ -4462,17 +4516,17 @@ The following example moves a file. Replaces the contents of a specified file with the contents of another file, deleting the original file, and creating a backup of the replaced file. - methods replace the contents of a specified file with the contents of another file. They also create a backup of the file that was replaced. - + methods replace the contents of a specified file with the contents of another file. They also create a backup of the file that was replaced. + ]]> - + @@ -4502,14 +4556,15 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 System.Void - - - + + + The name of a file that replaces the file specified by . @@ -4517,65 +4572,63 @@ The following example moves a file. The name of the backup file. Replaces the contents of a specified file with the contents of another file, deleting the original file, and creating a backup of the replaced file. - method replaces the contents of a specified file with the contents of another file. It also creates a backup of the file that was replaced. - - If the `sourceFileName` and `destinationFileName` are on different volumes, this method will raise an exception. If the `destinationBackupFileName` is on a different volume from the source file, the backup file will be deleted. - - Pass `null` to the `destinationBackupFileName` parameter if you do not want to create a backup of the file being replaced. + method replaces the contents of a specified file with the contents of another file. It also creates a backup of the file that was replaced. + + If the `sourceFileName` and `destinationFileName` are on different volumes, this method will raise an exception. If the `destinationBackupFileName` is on a different volume from the source file, the backup file will be deleted. + + Pass `null` to the `destinationBackupFileName` parameter if you do not want to create a backup of the file being replaced. If the `destinationBackupFileName` already exists it will be overwritten with the contents of the `destinationFileName` file. - -## Examples - The following code example uses the method to replace a file with another file and create a backup of the replaced file. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/IO.File.Replace/cpp/sample.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/IO.File.Replace/CS/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.Replace/VB/sample.vb" id="Snippet1"::: - + + + +## Examples + The following code example uses the method to replace a file with another file and create a backup of the replaced file. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.File.Replace/cpp/sample.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/Replace/sample.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.File.Replace/VB/sample.vb" id="Snippet1"::: + ]]> - The path described by the parameter was not of a legal form. - - -or- - + The path described by the parameter was not of a legal form. + + -or- + The path described by the parameter was not of a legal form. The parameter is . An invalid drive was specified. - The file described by the current object could not be found. - - -or- - + The file described by the current object could not be found. + + -or- + The file described by the parameter could not be found. - An I/O error occurred while opening the file. - + An I/O error occurred while opening the file. + -or- - + The and parameters specify the same file. The specified path, file name, or both exceed the system-defined maximum length. - The or parameter specifies a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - Source or destination parameters specify a directory instead of a file. - - -or- - - The caller does not have the required permission. - --or - - and specify the same existing directory. + The or parameter specifies a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + Source or destination parameters specify a directory instead of a file. + + -or- + + The caller does not have the required permission. - + @@ -4605,6 +4658,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -4616,10 +4670,10 @@ The following example moves a file. System.Void - - - - + + + + The name of a file that replaces the file specified by . @@ -4629,61 +4683,59 @@ The following example moves a file. to ignore merge errors (such as attributes and access control lists (ACLs)) from the replaced file to the replacement file; otherwise, . Replaces the contents of a specified file with the contents of another file, deleting the original file, and creating a backup of the replaced file and optionally ignores merge errors. - method replaces the contents of a specified file with the contents of another file. It also creates a backup of the file that was replaced. - - If the `sourceFileName` and `destinationFileName` are on different volumes, this method will raise an exception. If the `destinationBackupFileName` is on a different volume from the source file, the backup file will be deleted. - - Pass `null` to the `destinationBackupFileName` parameter if you do not want to create a backup of the file being replaced. + method replaces the contents of a specified file with the contents of another file. It also creates a backup of the file that was replaced. + + If the `sourceFileName` and `destinationFileName` are on different volumes, this method will raise an exception. If the `destinationBackupFileName` is on a different volume from the source file, the backup file will be deleted. + + Pass `null` to the `destinationBackupFileName` parameter if you do not want to create a backup of the file being replaced. If the `destinationBackupFileName` already exists it will be overwritten with the contents of the `destinationFileName` file. - -## Examples - The following code example uses the method to replace a file with another file and create a backup of the replaced file. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/IO.File.Replace/cpp/sample.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/IO.File.Replace/CS/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.Replace/VB/sample.vb" id="Snippet1"::: - + + + +## Examples + The following code example uses the method to replace a file with another file and create a backup of the replaced file. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.File.Replace/cpp/sample.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/Replace/sample.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.File.Replace/VB/sample.vb" id="Snippet1"::: + ]]> - The path described by the parameter was not of a legal form. - - -or- - + The path described by the parameter was not of a legal form. + + -or- + The path described by the parameter was not of a legal form. The parameter is . An invalid drive was specified. - The file described by the current object could not be found. - - -or- - + The file described by the current object could not be found. + + -or- + The file described by the parameter could not be found. - An I/O error occurred while opening the file. - + An I/O error occurred while opening the file. + -or- - + The and parameters specify the same file. The specified path, file name, or both exceed the system-defined maximum length. - The or parameter specifies a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - Source or destination parameters specify a directory instead of a file. - - -or- - - The caller does not have the required permission. - --or - - and specify the same existing directory. + The or parameter specifies a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + Source or destination parameters specify a directory instead of a file. + + -or- + + The caller does not have the required permission. @@ -4697,6 +4749,7 @@ The following example moves a file. System.Runtime 6.0.0.0 + 7.0.0.0 System.IO.FileSystem @@ -4711,8 +4764,8 @@ The following example moves a file. System.IO.FileSystemInfo - - + + The path of the file link. @@ -4781,58 +4834,58 @@ There are too many levels of symbolic links. A object that describes an ACL entry to apply to the file described by the parameter. Applies access control list (ACL) entries described by a object to the specified file. - method applies access control list (ACL) entries to a file that represents the noninherited ACL list. - + method applies access control list (ACL) entries to a file that represents the noninherited ACL list. + > [!CAUTION] -> The ACL specified for the `fileSecurity` parameter replaces the existing ACL for the file. To add permissions for a new user, use the method to obtain the existing ACL, modify it, and then use to apply it back to the file. - - An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - - The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it is not possible to retrieve a object from one file and reapply the same object to another file. - - To copy ACL information from one file to another: - -1. Use the method to retrieve the object from the source file. - -2. Create a new object for the destination file. - -3. Use the or method of the source object to retrieve the ACL information. - -4. Use the or method to copy the information retrieved in step 3 to the destination object. - -5. Set the destination object to the destination file using the method. - - In NTFS environments, and are granted to the user if the user has rights on the parent folder. To deny and , deny on the parent directory. - - - -## Examples - The following code example uses the and methods to add and then remove an access control list (ACL) entry from a file. You must supply a valid user or group account to run this example. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/cpp/sample.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/CS/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: - +> The ACL specified for the `fileSecurity` parameter replaces the existing ACL for the file. To add permissions for a new user, use the method to obtain the existing ACL, modify it, and then use to apply it back to the file. + + An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). + + The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it is not possible to retrieve a object from one file and reapply the same object to another file. + + To copy ACL information from one file to another: + +1. Use the method to retrieve the object from the source file. + +2. Create a new object for the destination file. + +3. Use the or method of the source object to retrieve the ACL information. + +4. Use the or method to copy the information retrieved in step 3 to the destination object. + +5. Set the destination object to the destination file using the method. + + In NTFS environments, and are granted to the user if the user has rights on the parent folder. To deny and , deny on the parent directory. + + + +## Examples + The following code example uses the and methods to add and then remove an access control list (ACL) entry from a file. You must supply a valid user or group account to run this example. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/cpp/sample.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/GetAccessControl/sample.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.File.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: + ]]> An I/O error occurred while opening the file. The parameter is . The file could not be found. - The parameter specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - The parameter specified a directory. - - -or- - + The parameter specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + The parameter specified a directory. + + -or- + The caller does not have the required permission. The parameter is . @@ -4871,6 +4924,7 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -4890,26 +4944,26 @@ There are too many levels of symbolic links. A bitwise combination of the enumeration values. Sets the specified of the file on the specified path. - . - - Certain file attributes, such as and , can be combined. Other attributes, such as , must be used alone. - - It is not possible to change the compression status of a object using the method. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates the `GetAttributes` and `SetAttributes` methods by applying the `Archive` and `Hidden` attributes to a file. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File GetAttributes/CPP/file getattributes.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File GetAttributes/CS/file getattributes.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File GetAttributes/VB/file getattributes.vb" id="Snippet1"::: - + . + + Certain file attributes, such as and , can be combined. Other attributes, such as , must be used alone. + + It is not possible to change the compression status of a object using the method. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates the `GetAttributes` and `SetAttributes` methods by applying the `Archive` and `Hidden` attributes to a file. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File GetAttributes/CPP/file getattributes.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/GetAttributes/file getattributes.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File GetAttributes/VB/file getattributes.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is empty, contains only white spaces, contains invalid characters, or the file attribute is invalid. @@ -4919,18 +4973,18 @@ There are too many levels of symbolic links. The specified path is invalid, (for example, it is on an unmapped drive). The file cannot be found. - specified a file that is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + specified a file that is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. File and Stream I/O @@ -4971,6 +5025,7 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 System.Void @@ -4984,15 +5039,15 @@ There are too many levels of symbolic links. A containing the value to set for the creation date and time of . This value is expressed in local time. Sets the date and time the file was created. - . - - NTFS-formatted drives may cache file meta-info, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + NTFS-formatted drives may cache file meta-info, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The specified path was not found. @@ -5045,6 +5100,7 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -5064,15 +5120,15 @@ There are too many levels of symbolic links. A containing the value to set for the creation date and time of . This value is expressed in UTC time. Sets the date and time, in coordinated universal time (UTC), that the file was created. - . - - NTFS-formatted drives may cache file meta-info, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + NTFS-formatted drives may cache file meta-info, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The specified path was not found. @@ -5125,6 +5181,7 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 System.Void @@ -5138,22 +5195,22 @@ There are too many levels of symbolic links. A containing the value to set for the last access date and time of . This value is expressed in local time. Sets the date and time the specified file was last accessed. - . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example checks the file system for the specified file, creating it if necessary, and then sets and gets the last access time. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File SetLastAccess/CPP/file setlastaccess.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File SetLastAccess/CS/file setlastaccess.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File SetLastAccess/VB/file setlastaccess.vb" id="Snippet1"::: - + . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example checks the file system for the specified file, creating it if necessary, and then sets and gets the last access time. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File SetLastAccess/CPP/file setlastaccess.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/SetLastAccessTime/file setlastaccess.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File SetLastAccess/VB/file setlastaccess.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -5205,6 +5262,7 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -5224,13 +5282,13 @@ There are too many levels of symbolic links. A containing the value to set for the last access date and time of . This value is expressed in UTC time. Sets the date and time, in coordinated universal time (UTC), that the specified file was last accessed. - . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -5282,6 +5340,7 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 System.Void @@ -5295,22 +5354,22 @@ There are too many levels of symbolic links. A containing the value to set for the last write date and time of . This value is expressed in local time. Sets the date and time that the specified file was last written to. - . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example checks the file system for the specified file, creating the file if necessary, and then sets and gets the last write time of the file. - - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/File SetLastWrite/CPP/file setlastwrite.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/File SetLastWrite/CS/file setlastwrite.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/File SetLastWrite/VB/file setlastwrite.vb" id="Snippet1"::: - + . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example checks the file system for the specified file, creating the file if necessary, and then sets and gets the last write time of the file. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/File SetLastWrite/CPP/file setlastwrite.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/File/SetLastWriteTime/file setlastwrite.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/File SetLastWrite/VB/file setlastwrite.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -5362,6 +5421,7 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -5381,13 +5441,13 @@ There are too many levels of symbolic links. A containing the value to set for the last write date and time of . This value is expressed in UTC time. Sets the date and time, in coordinated universal time (UTC), that the specified file was last written to. - . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -5438,6 +5498,7 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -5449,19 +5510,19 @@ There are too many levels of symbolic links. System.Void - - + + The file to write to. The bytes to write to the file. Creates a new file, writes the specified byte array to the file, and then closes the file. If the target file already exists, it is overwritten. - .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -5472,21 +5533,21 @@ There are too many levels of symbolic links. An I/O error occurred while opening the file. specified a file that is read-only. - - -or- - + + -or- + specified a file that is hidden. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. is in an invalid format. @@ -5518,14 +5579,15 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 System.Threading.Tasks.Task - - - + + + The file to write to. @@ -5577,6 +5639,7 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -5588,31 +5651,31 @@ There are too many levels of symbolic links. System.Void - - + + The file to write to. The lines to write to the file. Creates a new file, writes a collection of strings to the file, and then closes the file. - method is to write out data by using UTF-8 encoding without a byte order mark (BOM). If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. - - If the target file already exists, it is overwritten. - - You can use this method to create the contents for a collection class that takes an in its constructor, such as a , , or a class. - - - -## Examples - The following example writes selected lines from a sample data file to a file. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.file.writeallappendall/cs/program.cs" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.writeallappendall/vb/program.vb" id="Snippet1"::: - + method is to write out data by using UTF-8 encoding without a byte order mark (BOM). If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. + + If the target file already exists, it is overwritten. + + You can use this method to create the contents for a collection class that takes an in its constructor, such as a , , or a class. + + + +## Examples + The following example writes selected lines from a sample data file to a file. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/AppendAllLines/program.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.file.writeallappendall/vb/program.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters defined by the method. @@ -5627,21 +5690,21 @@ There are too many levels of symbolic links. The caller does not have the required permission. specified a file that is read-only. - - -or- - + + -or- + specified a file that is hidden. - - -or- - - This operation is not supported on the current platform. - - -or- - - is a directory. - - -or- - + + -or- + + This operation is not supported on the current platform. + + -or- + + is a directory. + + -or- + The caller does not have the required permission. @@ -5675,6 +5738,7 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -5686,31 +5750,31 @@ There are too many levels of symbolic links. System.Void - - + + The file to write to. The string array to write to the file. Creates a new file, write the specified string array to the file, and then closes the file. - method is to write out data using UTF-8 encoding without a byte order mark (BOM). If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. - - Given a string array and a file path, this method opens the specified file, writes the string array to the file, and then closes the file. - - - -## Examples - The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllLines/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines/vb/AllText.vb" id="Snippet00"::: - + method is to write out data using UTF-8 encoding without a byte order mark (BOM). If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. + + Given a string array and a file path, this method opens the specified file, writes the string array to the file, and then closes the file. + + + +## Examples + The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/ReadAllLines/AllText.cs" id="Snippet00"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -5720,21 +5784,21 @@ There are too many levels of symbolic links. An I/O error occurred while opening the file. specified a file that is read-only. - - -or- - - specified a file that is hidden. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + + -or- + + specified a file that is hidden. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. is in an invalid format. @@ -5772,6 +5836,7 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -5783,9 +5848,9 @@ There are too many levels of symbolic links. System.Void - - - + + + The file to write to. @@ -5793,17 +5858,17 @@ There are too many levels of symbolic links. The character encoding to use. Creates a new file by using the specified encoding, writes a collection of strings to the file, and then closes the file. - method. - -- The contents of a collection that implements an of strings. - + method. + +- The contents of a collection that implements an of strings. + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters defined by the method. @@ -5818,21 +5883,21 @@ There are too many levels of symbolic links. The caller does not have the required permission. specified a file that is read-only. - - -or- - - specified a file that is hidden. - - -or- - - This operation is not supported on the current platform. - - -or- - - is a directory. - - -or- - + + -or- + + specified a file that is hidden. + + -or- + + This operation is not supported on the current platform. + + -or- + + is a directory. + + -or- + The caller does not have the required permission. @@ -5866,6 +5931,7 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -5877,9 +5943,9 @@ There are too many levels of symbolic links. System.Void - - - + + + The file to write to. @@ -5887,21 +5953,21 @@ There are too many levels of symbolic links. An object that represents the character encoding applied to the string array. Creates a new file, writes the specified string array to the file by using the specified encoding, and then closes the file. - method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllLines_Encoding/cs/AllText_Encoding.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines_Encoding/vb/AllText_Encoding.vb" id="Snippet00"::: - + method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/ReadAllLines/AllText_Encoding.cs" id="Snippet00"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllLines_Encoding/vb/AllText_Encoding.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -5911,21 +5977,21 @@ There are too many levels of symbolic links. An I/O error occurred while opening the file. specified a file that is read-only. - - -or- - - specified a file that is hidden. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + + -or- + + specified a file that is hidden. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. is in an invalid format. @@ -5957,14 +6023,15 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 System.Threading.Tasks.Task - - - + + + The file to write to. @@ -6000,15 +6067,16 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 System.Threading.Tasks.Task - - - - + + + + The file to write to. @@ -6037,7 +6105,7 @@ There are too many levels of symbolic links. - + Method System.IO.FileSystem @@ -6063,6 +6131,7 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -6074,29 +6143,29 @@ There are too many levels of symbolic links. System.Void - - + + The file to write to. The string to write to the file. Creates a new file, writes the specified string to the file, and then closes the file. If the target file already exists, it is overwritten. - method will return an empty byte array. If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. - - Given a string and a file path, this method opens the specified file, writes the string to the file, and then closes the file. - - - -## Examples - The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllText/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText/vb/AllText.vb" id="Snippet00"::: - + method will return an empty byte array. If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. + + Given a string and a file path, this method opens the specified file, writes the string to the file, and then closes the file. + + + +## Examples + The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/AppendAllText/AllText.cs" id="Snippet00"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -6107,21 +6176,21 @@ There are too many levels of symbolic links. An I/O error occurred while opening the file. specified a file that is read-only. - - -or- - - specified a file that is hidden. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + + -or- + + specified a file that is hidden. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. is in an invalid format. @@ -6135,7 +6204,7 @@ There are too many levels of symbolic links. - + Method System.IO.FileSystem @@ -6161,6 +6230,7 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 @@ -6172,9 +6242,9 @@ There are too many levels of symbolic links. System.Void - - - + + + The file to write to. @@ -6182,19 +6252,19 @@ There are too many levels of symbolic links. The encoding to apply to the string. Creates a new file, writes the specified string to the file using the specified encoding, and then closes the file. If the target file already exists, it is overwritten. - method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. - - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/cs/AllText.cs" id="Snippet00"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/vb/AllText.vb" id="Snippet00"::: - + method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. + + :::code language="csharp" source="~/snippets/csharp/System.IO/File/AppendAllText/AllText1.cs" id="Snippet00"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.File.AllText_Encoding/vb/AllText.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the method. @@ -6205,21 +6275,21 @@ There are too many levels of symbolic links. An I/O error occurred while opening the file. specified a file that is read-only. - - -or- - - specified a file that is hidden. - - -or- - - This operation is not supported on the current platform. - - -or- - - specified a directory. - - -or- - + + -or- + + specified a file that is hidden. + + -or- + + This operation is not supported on the current platform. + + -or- + + specified a directory. + + -or- + The caller does not have the required permission. is in an invalid format. @@ -6227,7 +6297,7 @@ There are too many levels of symbolic links. - + @@ -6252,14 +6322,15 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 System.Threading.Tasks.Task - - - + + + The file to write to. @@ -6271,7 +6342,7 @@ There are too many levels of symbolic links. - + @@ -6296,15 +6367,16 @@ There are too many levels of symbolic links. System.Runtime 6.0.0.0 + 7.0.0.0 System.Threading.Tasks.Task - - - - + + + + The file to write to. From c1aef318ed7c2ff5e57f4b1114f2bef564f73fda Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 23 Mar 2022 21:28:17 -0700 Subject: [PATCH 3/3] redo changes without whitespace changes --- xml/System.IO/File.xml | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/xml/System.IO/File.xml b/xml/System.IO/File.xml index ac8e432fa61..a40e5464044 100644 --- a/xml/System.IO/File.xml +++ b/xml/System.IO/File.xml @@ -4624,7 +4624,11 @@ The following example moves a file. -or- - The caller does not have the required permission. +The caller does not have the required permission. + +-or + + and specify the same existing directory. @@ -4735,7 +4739,11 @@ The following example moves a file. -or- - The caller does not have the required permission. +The caller does not have the required permission. + +-or + + and specify the same existing directory.