dotnet / dotnet/dotnet-api-docs

Document SaveFileDialog.OpenFile() failure behvaior on various platforms.

Open
#7,935 0 comments 0 reactions 0 assignees View on GitHub
area-WinForms Pri3 untriaged
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

On Mono, [any behavior which would result in an exception returns `null`](https://github.com/mono/mono/blob/4b5e2591eb299eb34d60b5217b14c1ad9f11e238/mcs/class/System.Windows.Forms/System.Windows.Forms/SaveFileDialog.cs#L88), making it [inconsistent with .netfx](https://github.com/mono/mono/issues/21455).

On [.netfx](https://referencesource.microsoft.com/#System.Windows.Forms/winforms/Managed/System/WinForms/SaveFileDialog.cs,66a104767467d192) and [.netcore](https://github.com/dotnet/winforms/blob/c402e2a21cc3d6ab1c3fe6209ff829361aa596b9/src/System.Windows.Forms/src/System/Windows/Forms/SaveFileDialog.cs#L77), it is a thin wrapper around `new FileStream()`, so any exception which that constructor throws may be thrown. A `null` reference cannot be returned.

The [existing documentation](https://docs.microsoft.com/en-us/dotnet/api/system.windows.forms.savefiledialog.openfile?view=netframework-2.0) has no discussion about how errors are handled. It should at least mention:

* If the dialog was not shown with a successful result prior to invocation, the method will throw `ArgumentNullException`.
* If the file cannot be opened (such as if a race condition results in the file being moved), one of the following may happen:
* `IOException` thrown (on .netfx/.netcore).
* `null` may be returned.

Contributor guide

Open the contributing guide

Research direction

Start from the existing SaveFileDialog.OpenFile documentation linked in the issue and inspect the corresponding API documentation source in this repository. Document the behavior when the dialog was not successfully shown and when the file cannot be opened, including the platform-dependent exception or null result; done means the published entry clearly covers these cases.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.