The FileSystemInfo.Exists anomaly; File.Exists() has no use

[jhudsoncedaron]

This bug is mostly in the documentation.

File.Exists() returns false if an I/O error or permission error causes it to be impossible to determine if the file exists or not. To get the error, call LastWriteTimeUTC() and throw away the result. If LastWriteTimeUTC() returns, the file doesn't exist. If it throws, you don't know if the file exists or not and the exception is the reason you don't know.

This behavior is not documented. The apparent behavior from the documentation is FileInfo.Exists throws if an I/O error or permission error happens.

Not writing the extra call to check if FileSystemInfo.Exists() is reliable on returning false causes corner case bugs to exist in the code that cause incorrect behavior on transient network drops rather than detect and retry.

Due to this behavior, no correct code can ever call File.Exists() or Directory.Exists() even assuming static filesystems; should be tagged obsolete.

[danmoseley]

File.Exists does document that failure and "does not exist" cannot be distinguished:
https://docs.microsoft.com/en-us/dotnet/api/system.io.file.exists?view=netcore-2.0
"The Exists 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."

However FileSystemInfo.Exists does not document this:
https://docs.microsoft.com/en-us/dotnet/api/system.io.filesysteminfo.exists?view=netcore-2.0

It seems to me it should @JeremyKuhne do you agree?

@jhudsoncedaron does that address your concern?

[jhudsoncedaron]

@danmosemsft: Mostly. File.Exists's documentation should have "The Exists method returns false if any error occurs while trying to determine if the specified file exists." in the returns section instead of the long enumeration of only some of the cases where it returns false. Most people would otherwise go "I not passing null. I don't care about invalid path. I don't care about no permission to directory. Therefore I'm fine." and never reach the remarks section where I/O error is finally mentioned.

In typing this up the first time I only looked at FileSystemInfo.Exists's documentation where it's nowhere to be found.

[danmoseley]

@jhudsoncedaron makes sense. Do you want to open an issue or PR in the docs repo and close this?

[jhudsoncedaron]

Are the XML comments in the corefx repo or the docs repo?

[danmoseley]

I am not sure whether the XML comments in the code end up in the docs or the docs repo is separate. @karelz do you know?

[karelz]

Changes to XML comments are not reflected in any docs. If you want to change docs, please change them on dotnet/docs repo.

[JeremyKuhne]

Yes, the docs should be updated to be very clear. The results are really "yes" and "we don't know". "CouldReach" is probably a better term than Exists. You're welcome to make an issue/PR in the docs repository, let me know if you aren't interested and I'll create one. We should also call out the common error where people assume Exists == true means that the file will still be there when they try and access it.

[jhudsoncedaron]

I'll make the issue soon enough. The only hope I had of a PR was if the docs came from the XML comments, which they don't.

[jhudsoncedaron]

https://github.com/dotnet/docs/issues/4343

[danmoseley]

Thanks @jhudsoncedaron !