WindowsRuntimeStorageExtensions.xml

<TypeName="WindowsRuntimeStorageExtensions"FullName="System.IO.WindowsRuntimeStorageExtensions">
 <TypeSignatureLanguage="C#"Value="public static class WindowsRuntimeStorageExtensions" />
 <TypeSignatureLanguage="ILAsm"Value=".class public auto ansi abstract sealed beforefieldinit WindowsRuntimeStorageExtensions extends System.Object" />
 <TypeSignatureLanguage="DocId"Value="T:System.IO.WindowsRuntimeStorageExtensions" />
 <TypeSignatureLanguage="VB.NET"Value="Public Module WindowsRuntimeStorageExtensions" />
 <TypeSignatureLanguage="F#"Value="type WindowsRuntimeStorageExtensions = class" />
 <TypeSignatureLanguage="C++ CLI"Value="public ref class WindowsRuntimeStorageExtensions abstract sealed" />
 <AssemblyInfo>
 <AssemblyName>System.Runtime.WindowsRuntime</AssemblyName>
 <AssemblyVersion>4.0.10.0</AssemblyVersion>
 <AssemblyVersion>4.0.14.0</AssemblyVersion>
 <AssemblyVersion>4.0.15.0</AssemblyVersion>
 </AssemblyInfo>
 <Base>
 <BaseTypeName>System.Object</BaseTypeName>
 </Base>
 <Interfaces />
 <Attributes>
 <Attribute>
 <AttributeNameLanguage="C#">[System.Security.SecurityCritical]</AttributeName>
 <AttributeNameLanguage="F#">[&lt;System.Security.SecurityCritical&gt;]</AttributeName>
 </Attribute>
 </Attributes>
 <Docs>
 <summary>Contains extension methods for the <seecref="T:Windows.Storage.IStorageFile" /> and <seecref="T:Windows.Storage.IStorageFolder" /> interfaces in the Windows Runtime when developing Windows Store apps.</summary>
 <remarks>
 <formattype="text/markdown"><![CDATA[

## Remarks

These extension methods are available only when you develop Windows Store apps. The methods provide convenient ways of opening files for reading or writing in Windows Store apps. You do not create an instance of the `WindowsRuntimeStorageExtensions` class; instead, you use these methods from instances of the <xref:Windows.Storage.IStorageFile> and <xref:Windows.Storage.IStorageFolder> interfaces.

The `WindowsRuntimeStorageExtensions` class contains two methods that extend <xref:Windows.Storage.IStorageFile> for reading or writing:

 - <xref:System.IO.WindowsRuntimeStorageExtensions.OpenStreamForReadAsync(Windows.Storage.IStorageFile)>
 - <xref:System.IO.WindowsRuntimeStorageExtensions.OpenStreamForWriteAsync(Windows.Storage.IStorageFile)>

The WindowsRuntimeStorageExtensions class contains two methods that extend <xref:Windows.Storage.IStorageFolder> for reading and writing:
 - <xref:System.IO.WindowsRuntimeStorageExtensions.OpenStreamForReadAsync(Windows.Storage.IStorageFolder,System.String)>
 - <xref:System.IO.WindowsRuntimeStorageExtensions.OpenStreamForWriteAsync(Windows.Storage.IStorageFolder,System.String,Windows.Storage.CreationCollisionOption)>

## Examples

The following example shows how to open a file in the application data as a <xref:System.IO.Stream> in a Windows Store app, and write to it by using an instance of the <xref:System.IO.StreamWriter> class. It then reads the contents for the file by using an instance of the <xref:System.IO.StreamReader> class.

:::code language="csharp" source="~/snippets/csharp/System.IO/WindowsRuntimeStorageExtensions/Overview/blankpage4.xaml.cs" id="Snippet8":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.windowsruntimestorageextensions/vb/blankpage4.xaml.vb" id="Snippet8":::

The next example shows the XAML code that is associated with the previous example. 

:::code language="xaml" source="~/snippets/csharp/System.IO/WindowsRuntimeStorageExtensions/Overview/blankpage4.xaml" id="Snippet7":::

]]></format>
 </remarks>
 </Docs>
 <Members>
 <MemberGroupMemberName="CreateSafeFileHandle">
 <AssemblyInfo>
 <AssemblyName>System.Runtime.WindowsRuntime</AssemblyName>
 <AssemblyVersion>4.0.14.0</AssemblyVersion>
 </AssemblyInfo>
 <Docs>
 <summary>Creates and returns a reference to a safe file handle for the IStorage instance that is being extended.</summary>
 <remarks>
 <formattype="text/markdown"><![CDATA[

## Remarks

With the Windows 10 Anniversary Update, new interfaces were added to <xref:Windows.Storage.IStorageFolder> and <xref:Windows.Storage.IStorageFile> that allow creating a standard Win32 file handle: `IStorageFolderHandleAccess` and `IStorageItemHandleAccess`. The `CreateSafeFileHandle` group of extension methods take advantage of the `Create` methods of these interfaces.

The key benefit of the API is access to a brokered `SafeFileHandle`. This is critically important if you want to create a <xref:System.IO.FileStream> around an <xref:Windows.Storage.IStorageItem> or <xref:Windows.Storage.IStorageFolder> when you are running in an [AppContainer](https://learn.microsoft.com/windows/win32/secauthz/appcontainer-isolation). When running in an AppContainer, the application has very limited file access rights. Things like picture and document folders require the native file handle to be proxied via `RuntimeBroker.exe`, as the application process itself doesn't have rights to most files. This API gets the proxied handle. If accessing user data folders or using a file picker, this API should always be used to create <xref:System.IO.FileStream>. Using a path will often throw <xref:System.AccessViolationException> in these cases.

]]></format>
 </remarks>
 </Docs>
 </MemberGroup>
 <MemberMemberName="OpenStreamForReadAsync">
 <MemberSignatureLanguage="C#"Value="public static System.Threading.Tasks.Task&lt;System.IO.Stream&gt; OpenStreamForReadAsync (this Windows.Storage.IStorageFile windowsRuntimeFile);" />
 <MemberSignatureLanguage="ILAsm"Value=".method public static hidebysig class System.Threading.Tasks.Task`1&lt;class System.IO.Stream&gt; OpenStreamForReadAsync(class Windows.Storage.IStorageFile windowsRuntimeFile) cil managed" />
 <MemberSignatureLanguage="DocId"Value="M:System.IO.WindowsRuntimeStorageExtensions.OpenStreamForReadAsync(Windows.Storage.IStorageFile)" />
 <MemberSignatureLanguage="VB.NET"Value="&lt;Extension()&gt;&#xA;Public Function OpenStreamForReadAsync (windowsRuntimeFile As IStorageFile) As Task(Of Stream)" />
 <MemberSignatureLanguage="F#"Value="static member OpenStreamForReadAsync : Windows.Storage.IStorageFile -&gt; System.Threading.Tasks.Task&lt;System.IO.Stream&gt;"Usage="System.IO.WindowsRuntimeStorageExtensions.OpenStreamForReadAsync windowsRuntimeFile" />
 <MemberSignatureLanguage="C++ CLI"Value="public:&#xA;[System::Runtime::CompilerServices::Extension]&#xA; static System::Threading::Tasks::Task&lt;System::IO::Stream ^&gt; ^ OpenStreamForReadAsync(Windows::Storage::IStorageFile ^ windowsRuntimeFile);" />
 <MemberType>Method</MemberType>
 <AssemblyInfo>
 <AssemblyName>System.Runtime.WindowsRuntime</AssemblyName>
 <AssemblyVersion>4.0.10.0</AssemblyVersion>
 </AssemblyInfo>
 <Attributes>
 <Attribute>
 <AttributeNameLanguage="C#">[System.CLSCompliant(false)]</AttributeName>
 <AttributeNameLanguage="F#">[&lt;System.CLSCompliant(false)&gt;]</AttributeName>
 </Attribute>
 </Attributes>
 <ReturnValue>
 <ReturnType>System.Threading.Tasks.Task&lt;System.IO.Stream&gt;</ReturnType>
 </ReturnValue>
 <Parameters>
 <ParameterName="windowsRuntimeFile"Type="Windows.Storage.IStorageFile"RefType="this" />
 </Parameters>
 <Docs>
 <paramname="windowsRuntimeFile">The Windows Runtime <seecref="T:Windows.Storage.IStorageFile" /> object to read from.</param>
 <summary>Retrieves a stream for reading from a specified file.</summary>
 <returns>A task that represents the asynchronous read operation.</returns>
 <remarks>
 <formattype="text/markdown"><![CDATA[
## Remarks

> [!NOTE]
> In Visual Basic and C#, you can call this method as an instance method on any object of type <xref:Windows.Storage.IStorageFile>. When you use instance method syntax to call this method, omit the first parameter. For more information, see [Extension Methods (Visual Basic)](/dotnet/visual-basic/programming-guide/language-features/procedures/extension-methods) or [Extension Methods (C# Programming Guide)](/dotnet/csharp/programming-guide/classes-and-structs/extension-methods).

## Examples

The following example shows how to open a file as a <xref:System.IO.Stream> in a Windows Store app, and read its contents by using an instance of the <xref:System.IO.StreamReader> class.

:::code language="csharp" source="~/snippets/csharp/System.IO/WindowsRuntimeStorageExtensions/Overview/blankpage.xaml.cs" id="Snippet2":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.windowsruntimestorageextensions/vb/blankpage.xaml.vb" id="Snippet2":::

The next example shows the XAML code that is associated with the previous example. 

:::code language="xaml" source="~/snippets/csharp/System.IO/WindowsRuntimeStorageExtensions/Overview/blankpage.xaml" id="Snippet1":::

]]></format>
 </remarks>
 <exceptioncref="T:System.ArgumentNullException">
 <paramrefname="windowsRuntimeFile" /> is <seelangword="null" />.</exception>
 <exceptioncref="T:System.IO.IOException">The file could not be opened or retrieved as a stream.</exception>
 </Docs>
 </Member>
 <MemberMemberName="OpenStreamForReadAsync">
 <MemberSignatureLanguage="C#"Value="public static System.Threading.Tasks.Task&lt;System.IO.Stream&gt; OpenStreamForReadAsync (this Windows.Storage.IStorageFolder rootDirectory, string relativePath);" />
 <MemberSignatureLanguage="ILAsm"Value=".method public static hidebysig class System.Threading.Tasks.Task`1&lt;class System.IO.Stream&gt; OpenStreamForReadAsync(class Windows.Storage.IStorageFolder rootDirectory, string relativePath) cil managed" />
 <MemberSignatureLanguage="DocId"Value="M:System.IO.WindowsRuntimeStorageExtensions.OpenStreamForReadAsync(Windows.Storage.IStorageFolder,System.String)" />
 <MemberSignatureLanguage="VB.NET"Value="&lt;Extension()&gt;&#xA;Public Function OpenStreamForReadAsync (rootDirectory As IStorageFolder, relativePath As String) As Task(Of Stream)" />
 <MemberSignatureLanguage="F#"Value="static member OpenStreamForReadAsync : Windows.Storage.IStorageFolder * string -&gt; System.Threading.Tasks.Task&lt;System.IO.Stream&gt;"Usage="System.IO.WindowsRuntimeStorageExtensions.OpenStreamForReadAsync (rootDirectory, relativePath)" />
 <MemberSignatureLanguage="C++ CLI"Value="public:&#xA;[System::Runtime::CompilerServices::Extension]&#xA; static System::Threading::Tasks::Task&lt;System::IO::Stream ^&gt; ^ OpenStreamForReadAsync(Windows::Storage::IStorageFolder ^ rootDirectory, System::String ^ relativePath);" />
 <MemberType>Method</MemberType>
 <AssemblyInfo>
 <AssemblyName>System.Runtime.WindowsRuntime</AssemblyName>
 <AssemblyVersion>4.0.10.0</AssemblyVersion>
 </AssemblyInfo>
 <Attributes>
 <Attribute>
 <AttributeNameLanguage="C#">[System.CLSCompliant(false)]</AttributeName>
 <AttributeNameLanguage="F#">[&lt;System.CLSCompliant(false)&gt;]</AttributeName>
 </Attribute>
 </Attributes>
 <ReturnValue>
 <ReturnType>System.Threading.Tasks.Task&lt;System.IO.Stream&gt;</ReturnType>
 </ReturnValue>
 <Parameters>
 <ParameterName="rootDirectory"Type="Windows.Storage.IStorageFolder"RefType="this" />
 <ParameterName="relativePath"Type="System.String" />
 </Parameters>
 <Docs>
 <paramname="rootDirectory">The Windows Runtime <seecref="T:Windows.Storage.IStorageFile" /> object that contains the file to read from.</param>
 <paramname="relativePath">The path, relative to the root folder, to the file to read from.</param>
 <summary>Retrieves a stream for reading from a file in the specified parent folder.</summary>
 <returns>A task that represents the asynchronous read operation.</returns>
 <remarks>
 <formattype="text/markdown"><![CDATA[

## Remarks

> [!NOTE]
> In Visual Basic and C#, you can call this method as an instance method on any object of type IStorageFolder. When you use instance method syntax to call this method, omit the first parameter. For more information, see [Extension Methods (Visual Basic)](/dotnet/visual-basic/programming-guide/language-features/procedures/extension-methods) or [Extension Methods (C# Programming Guide)](/dotnet/csharp/programming-guide/classes-and-structs/extension-methods).

## Examples

The following example shows how to open a file as a <xref:System.IO.Stream> in a Windows Store app, and read its contents by using an instance of the <xref:System.IO.StreamReader> class.

:::code language="csharp" source="~/snippets/csharp/System.IO/WindowsRuntimeStorageExtensions/Overview/blankpage2.xaml.cs" id="Snippet4":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.windowsruntimestorageextensions/vb/blankpage2.xaml.vb" id="Snippet4":::

The next example shows the XAML code that is associated with the previous example. 

:::code language="xaml" source="~/snippets/csharp/System.IO/WindowsRuntimeStorageExtensions/Overview/blankpage2.xaml" id="Snippet3":::

]]></format>
 </remarks>
 <exceptioncref="T:System.ArgumentNullException">
 <paramrefname="rootDirectory" /> or <paramrefname="relativePath" /> is <seelangword="null" />.</exception>
 <exceptioncref="T:System.ArgumentException">
 <paramrefname="relativePath" /> is empty or contains only white-space characters.</exception>
 <exceptioncref="T:System.IO.IOException">The file could not be opened or retrieved as a stream.</exception>
 </Docs>
 </Member>
 <MemberMemberName="OpenStreamForWriteAsync">
 <MemberSignatureLanguage="C#"Value="public static System.Threading.Tasks.Task&lt;System.IO.Stream&gt; OpenStreamForWriteAsync (this Windows.Storage.IStorageFile windowsRuntimeFile);" />
 <MemberSignatureLanguage="ILAsm"Value=".method public static hidebysig class System.Threading.Tasks.Task`1&lt;class System.IO.Stream&gt; OpenStreamForWriteAsync(class Windows.Storage.IStorageFile windowsRuntimeFile) cil managed" />
 <MemberSignatureLanguage="DocId"Value="M:System.IO.WindowsRuntimeStorageExtensions.OpenStreamForWriteAsync(Windows.Storage.IStorageFile)" />
 <MemberSignatureLanguage="VB.NET"Value="&lt;Extension()&gt;&#xA;Public Function OpenStreamForWriteAsync (windowsRuntimeFile As IStorageFile) As Task(Of Stream)" />
 <MemberSignatureLanguage="F#"Value="static member OpenStreamForWriteAsync : Windows.Storage.IStorageFile -&gt; System.Threading.Tasks.Task&lt;System.IO.Stream&gt;"Usage="System.IO.WindowsRuntimeStorageExtensions.OpenStreamForWriteAsync windowsRuntimeFile" />
 <MemberSignatureLanguage="C++ CLI"Value="public:&#xA;[System::Runtime::CompilerServices::Extension]&#xA; static System::Threading::Tasks::Task&lt;System::IO::Stream ^&gt; ^ OpenStreamForWriteAsync(Windows::Storage::IStorageFile ^ windowsRuntimeFile);" />
 <MemberType>Method</MemberType>
 <AssemblyInfo>
 <AssemblyName>System.Runtime.WindowsRuntime</AssemblyName>
 <AssemblyVersion>4.0.10.0</AssemblyVersion>
 </AssemblyInfo>
 <Attributes>
 <Attribute>
 <AttributeNameLanguage="C#">[System.CLSCompliant(false)]</AttributeName>
 <AttributeNameLanguage="F#">[&lt;System.CLSCompliant(false)&gt;]</AttributeName>
 </Attribute>
 </Attributes>
 <ReturnValue>
 <ReturnType>System.Threading.Tasks.Task&lt;System.IO.Stream&gt;</ReturnType>
 </ReturnValue>
 <Parameters>
 <ParameterName="windowsRuntimeFile"Type="Windows.Storage.IStorageFile"RefType="this" />
 </Parameters>
 <Docs>
 <paramname="windowsRuntimeFile">The Windows Runtime <seecref="T:Windows.Storage.IStorageFile" /> object to write to.</param>
 <summary>Retrieves a stream for writing to a specified file.</summary>
 <returns>A task that represents the asynchronous write operation.</returns>
 <remarks>
 <formattype="text/markdown"><![CDATA[
## Remarks

> [!NOTE]
> In Visual Basic and C#, you can call this method as an instance method on any object of type <xref:Windows.Storage.IStorageFile>. When you use instance method syntax to call this method, omit the first parameter. For more information, see [Extension Methods (Visual Basic)](/dotnet/visual-basic/programming-guide/language-features/procedures/extension-methods) or [Extension Methods (C# Programming Guide)](/dotnet/csharp/programming-guide/classes-and-structs/extension-methods).

## Examples

The following example shows how to open a file as a <xref:System.IO.Stream> in a Windows Store app, and write to it by using an instance of the <xref:System.IO.StreamReader> class.

:::code language="csharp" source="~/snippets/csharp/System.IO/WindowsRuntimeStorageExtensions/Overview/blankpage3.xaml.cs" id="Snippet6":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.windowsruntimestorageextensions/vb/blankpage3.xaml.vb" id="Snippet6":::

The next example shows the XAML code that is associated with the previous example. 

:::code language="xaml" source="~/snippets/csharp/System.IO/WindowsRuntimeStorageExtensions/Overview/blankpage3.xaml" id="Snippet5":::

]]></format>
 </remarks>
 <exceptioncref="T:System.ArgumentNullException">
 <paramrefname="windowsRuntimeFile" /> is <seelangword="null" />.</exception>
 <exceptioncref="T:System.IO.IOException">The file could not be opened or retrieved as a stream.</exception>
 </Docs>
 </Member>
 <MemberMemberName="OpenStreamForWriteAsync">
 <MemberSignatureLanguage="C#"Value="public static System.Threading.Tasks.Task&lt;System.IO.Stream&gt; OpenStreamForWriteAsync (this Windows.Storage.IStorageFolder rootDirectory, string relativePath, Windows.Storage.CreationCollisionOption creationCollisionOption);" />
 <MemberSignatureLanguage="ILAsm"Value=".method public static hidebysig class System.Threading.Tasks.Task`1&lt;class System.IO.Stream&gt; OpenStreamForWriteAsync(class Windows.Storage.IStorageFolder rootDirectory, string relativePath, valuetype Windows.Storage.CreationCollisionOption creationCollisionOption) cil managed" />
 <MemberSignatureLanguage="DocId"Value="M:System.IO.WindowsRuntimeStorageExtensions.OpenStreamForWriteAsync(Windows.Storage.IStorageFolder,System.String,Windows.Storage.CreationCollisionOption)" />
 <MemberSignatureLanguage="VB.NET"Value="&lt;Extension()&gt;&#xA;Public Function OpenStreamForWriteAsync (rootDirectory As IStorageFolder, relativePath As String, creationCollisionOption As CreationCollisionOption) As Task(Of Stream)" />
 <MemberSignatureLanguage="F#"Value="static member OpenStreamForWriteAsync : Windows.Storage.IStorageFolder * string * Windows.Storage.CreationCollisionOption -&gt; System.Threading.Tasks.Task&lt;System.IO.Stream&gt;"Usage="System.IO.WindowsRuntimeStorageExtensions.OpenStreamForWriteAsync (rootDirectory, relativePath, creationCollisionOption)" />
 <MemberSignatureLanguage="C++ CLI"Value="public:&#xA;[System::Runtime::CompilerServices::Extension]&#xA; static System::Threading::Tasks::Task&lt;System::IO::Stream ^&gt; ^ OpenStreamForWriteAsync(Windows::Storage::IStorageFolder ^ rootDirectory, System::String ^ relativePath, Windows::Storage::CreationCollisionOption creationCollisionOption);" />
 <MemberType>Method</MemberType>
 <AssemblyInfo>
 <AssemblyName>System.Runtime.WindowsRuntime</AssemblyName>
 <AssemblyVersion>4.0.10.0</AssemblyVersion>
 </AssemblyInfo>
 <Attributes>
 <Attribute>
 <AttributeNameLanguage="C#">[System.CLSCompliant(false)]</AttributeName>
 <AttributeNameLanguage="F#">[&lt;System.CLSCompliant(false)&gt;]</AttributeName>
 </Attribute>
 </Attributes>
 <ReturnValue>
 <ReturnType>System.Threading.Tasks.Task&lt;System.IO.Stream&gt;</ReturnType>
 </ReturnValue>
 <Parameters>
 <ParameterName="rootDirectory"Type="Windows.Storage.IStorageFolder"RefType="this" />
 <ParameterName="relativePath"Type="System.String" />
 <ParameterName="creationCollisionOption"Type="Windows.Storage.CreationCollisionOption" />
 </Parameters>
 <Docs>
 <paramname="rootDirectory">The Windows Runtime <seecref="T:Windows.Storage.IStorageFile" /> object that contains the file to write to.</param>
 <paramname="relativePath">The path, relative to the root folder, to the file to write to.</param>
 <paramname="creationCollisionOption">The Windows Runtime <seecref="T:Windows.Storage.CreationCollisionOption" /> enumeration value that specifies the behavior to use when the name of the file to create is the same as the name of an existing file.</param>
 <summary>Retrieves a stream for writing to a file in the specified parent folder.</summary>
 <returns>A task that represents the asynchronous write operation.</returns>
 <remarks>
 <formattype="text/markdown"><![CDATA[

## Remarks

> [!NOTE]
> In Visual Basic and C#, you can call this method as an instance method on any object of type <xref:Windows.Storage.IStorageFolder>. When you use instance method syntax to call this method, omit the first parameter. For more information, see [Extension Methods (Visual Basic)](/dotnet/visual-basic/programming-guide/language-features/procedures/extension-methods) or [Extension Methods (C# Programming Guide)](/dotnet/csharp/programming-guide/classes-and-structs/extension-methods).

## Examples

The following example shows how to open a file as a <xref:System.IO.Stream> in a Windows Store app, and write to it by using an instance of the <xref:System.IO.StreamReader> class.

:::code language="csharp" source="~/snippets/csharp/System.IO/WindowsRuntimeStorageExtensions/Overview/blankpage4.xaml.cs" id="Snippet8":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.windowsruntimestorageextensions/vb/blankpage4.xaml.vb" id="Snippet8":::

The next example shows the XAML code that is associated with the previous example. 

:::code language="xaml" source="~/snippets/csharp/System.IO/WindowsRuntimeStorageExtensions/Overview/blankpage4.xaml" id="Snippet7":::

]]></format>
 </remarks>
 <exceptioncref="T:System.ArgumentNullException">
 <paramrefname="rootDirectory" /> or <paramrefname="relativePath" /> is <seelangword="null" />.</exception>
 <exceptioncref="T:System.ArgumentException">
 <paramrefname="relativePath" /> is empty or contains only white-space characters.</exception>
 <exceptioncref="T:System.IO.IOException">The file could not be opened or retrieved as a stream.</exception>
 </Docs>
 </Member>
 </Members>
</Type>