CreateSafeFileHandle not documented

[JeremyKuhne]

System.IO.WindowsRuntimeStorageExtensions (from the System.Runtime.WindowsRuntime library) had APIs added for converting from Windows.Storage.IStorageFile and Windows.Storage.IStorageFolder to Microsoft.Win32.SafeHandles.SafeFileHandle. These don't appear to be documented anywhere.

The key usage scenario is taking a WinRT IStorageFile and constructing a System.IO.FileStream around it. This allows synchronous access to IStorageFile/IStorageFolder objects.

The reference definitions:
/runtime/src/libraries/System.Runtime.WindowsRuntime/ref/System.Runtime.WindowsRuntime.cs#L41-L46 [edited to point to dotnet/runtime]:

        public static SafeFileHandle CreateSafeFileHandle(
            this IStorageFile windowsRuntimeFile,
            FileAccess access = FileAccess.ReadWrite,
            FileShare share = FileShare.Read,
            FileOptions options = FileOptions.None)

        public static SafeFileHandle CreateSafeFileHandle(
            this IStorageFolder rootDirectory,
            string relativePath,
            FileMode mode)

        public static SafeFileHandle CreateSafeFileHandle(
            this IStorageFolder rootDirectory,
            string relativePath,
            FileMode mode,
            FileAccess access,
            FileShare share = FileShare.Read,
            FileOptions options = FileOptions.None)

Arguments work the same as FileStream constructor arguments, with the obvious exception that you can provide a root directory and a relative path.

The API is present in 2.0 releases of System.IO.WindowsRuntime` for .NET 4.6.1, .NET Core 2.0, and Universal Windows Platform 10.0.16299.

[mairaw]

Hi @JeremyKuhne! The page you link from MSDN is not hooked up to the TOC, which means at some point reflection stopped picking up that API as part of the product.
For .NET Framework for example, I don't see System.Runtime.WindowsRuntime.dll as part of the reference assemblies set we reflect against.

Do you know if this is shipped separately?

[JeremyKuhne]

It was a separate package, but I also mistakenly thought we shipped an updated standalone package for this. The update was only was published as part of Microsoft.NETCore.UniversalWindowsPlatform and you have to target Fall Creator's Update or higher for the APIs I have listed above. That gets you the following version of the assembly (4.0.3.0 is the latest standalone):

System.Runtime.WindowsRuntime, Version=4.0.14.0, Culture=neutral, PublicKeyToken=b77a5c561934e089

So scratch .NET 4.6.1 and .NET Core 2.0- only Universal Windows Platform 10.0.16299 for now.

[mairaw]

Ok, that makes sense then. We haven't onboarded UWP to the .NET API reference yet as one of the selections in docs.microsoft.com. @dend might have some details on when that's coming.

There's also a discussion on how we show APIs that we ship on NuGet packages, which could apply here too.

[JKennedy24]

@JeremyKuhne Any chance of packaging up `System.Runtime.WindowsRuntime, Version=4.0.14.0 as a standalone package.

Otherwise it means I am forced to make my target version and min version to Fall Creators Update which not everyone is updated to.
(see linked issue for more details)

[JeremyKuhne]

@JKennedy24 Are you using the CreateSafeFileHandle API? If not you can use the older versions of this package- nothing else has changed. Note that if you are targeting .NET Standard 2.0 you have to target the Fall Creators Update for UWP.

If you want a stand-alone package published we should open an issue in CoreFX to track.

[EmilAlipiev]

@JeremyKuhne why there is such restriction to use latest version as min version? it is potential user lose for developers

[JKennedy24]

@JeremyKuhne the reason I ask is because of a third party plugin I use which required version System.Runtime.WindowsRuntime, Version=4.0.14.0 and threw an exception on running on UWP. (rotorgames/Rg.Plugins.Popup#217)

The only way to get that specific version was to upgrade my UWP min/target version to Fall Creators update.

my current project is a .Net Standard 1.4 UWP project.

I cant see why the third party control would use CreateSafeFileHandle API (and infact searching for that word on the repository returns nothing: https://github.com/rotorgames/Rg.Plugins.Popup/search?utf8=%E2%9C%93&q=createsafehandle&type=) but I may be wrong.

[JeremyKuhne]

@JKennedy24
I'm not sure why rotorgames has a dependency on it- if they aren't using this API then the reference might be a mistake? Or are they referencing 2.0?

@EmilAlipiev
I personally have no objections to there being an updated stand-alone package for this. Please open an issue in CoreFX if you want this. Note, however, that the APIs that these use (IStorageFolderHandleAccess::Create, etc.) aren't in all versions of Windows 10. If I recall correctly they showed up in RS1 (Anniversary Update)? Our API was written to fall over gracefully, however, so the standalone package doesn't need to target the fall update, you'd just need to check if you got a valid handle back (e.g. not null or .IsInvalid).

[JeremyKuhne]

@mairaw Can we up the priority on this? Apparently all of the WindowsRuntimeStorageExtensions documentation is now missing with the switch to docs.

[mairaw]

@dend @sudeepku please take a look at this. Another set of APIs that were just redirected to their parent.