IUploadedFile: Improve the public API and document

[HeyJoel]

Document and make the API more discoverable

Ref #471 it's not particularly intuitive to add an asset file, we should improve the API here and document it. XML comments on the API also need to ref the method for creating file sources.

Should IUploadedFile be disposable?

The aim is for the callee to handle disposing, but what if open is never called? If there is an unmanaged stream in there then it will never get disposed.

However implementing IDisposable gives the impression that the container stream would be disposed? Perhaps we should dispose if open is never called in instances that hold a stream.

If we can remove the requirement for fileLength then maybe we don't need the stream. Perhaps make it nullable - supply it if we have it? Would make the embedded resource provider simpler, although then we wouldn't be able to do the exists check first? That's kinda nice to be able to return null if it doesn't exist.

Maybe it's the StreamFileSource that is wrong, and we should be passing in a function rather than instance of stream, so it's up to the constructor to ensure it is dealt with accordingly.

Properties

Looking into it more, I think MimeType/FileLength should be optional (and it probably already is, just not indicated as such).

Renaming

It's not always an "uploaded" file, so I think we should change it to IFileSource instead to match other implementations.

[HeyJoel]

Fixed, will be release in v0.10

Breaking changes:

• IUploadedFile has been renamed IFileSource
• FormFileUploadedFile has been renamed FormFileSource
• IFormFileUploadedFileFactory has been removed and a FormFileSource can be created by simply calling the constructor new FormFileSource(formFile).
• IUploadedFile no longer requires a file size
• IStreamFileSource now requires a factory delegate for creating the stream instead of wrapping an existing stream.