Merge pull request #5800 from MicrosoftDocs/main

Auto Publish – main to live - 2025-09-10 16:09 UTC

Author: learn-build-service-prod[bot]

hub/apps/develop/files/dotnet-files.md

@@ -1,15 +1,34 @@
 ---
 ms.assetid: 5931d63c-6b80-4e47-b371-ee299e308b8e
-title: Access files and folders with Windows App SDK and .NET
-description: Packaged Windows App SDK apps can leverage .NET APIs for reading and writing files, working with folders, and reading drive and volume information.
-ms.date: 06/16/2023
+title: Access Files and Folders with Windows App SDK and .NET
+description: Learn how to access files and folders in WinUI apps using .NET APIs. Read and write files, manage directories, work with drives, and handle memory streams with practical code examples.
+ms.date: 08/21/2025
 ms.topic: how-to
 keywords: windows 10, windows 11, windows, winui, windows app sdk, dotnet
 ms.localizationpriority: medium
+# customer intent: As a Windows app developer, I want to learn how to use .NET APIs for file management in my WinUI app.
 ---
+
 # Access files and folders with Windows App SDK and .NET
 
-Packaged Windows App SDK apps can leverage [.NET APIs](/dotnet/) for reading and writing files, working with folders, and reading drive and volume information. Additionally, any packaged desktop app can utilize both WinRT and Win32 APIs in the Windows SDK, as well as the APIs provided in the .NET SDK. This article provides guidance on how to use the .NET [System.IO](/dotnet/api/system.io) APIs to read and write files, manage drives and folders, and work with memory streams to encode or decode string data.
+This article shows you how to access files and folders using .NET APIs in packaged WinUI apps. You'll learn to read and write files, manage directories and drives, and work with memory streams for string encoding and decoding.
+
+WinUI apps can use [.NET APIs](/dotnet/) alongside WinRT and Win32 APIs to provide comprehensive file system access. The examples in this article focus on the [System.IO](/dotnet/api/system.io) namespace, which provides the core functionality for file and directory operations.
+
+## Prerequisites
+
+- Visual Studio 2022 with the **WinUI application development** workload installed
+- A packaged WinUI project
+- Basic familiarity with C# and .NET development
+
+## What you'll learn
+
+In this article, you'll learn how to:
+
+- Read and write files using [FileStream](/dotnet/api/system.io.filestream), [BinaryWriter](/dotnet/api/system.io.binarywriter), and [BinaryReader](/dotnet/api/system.io.binaryreader)
+- Create, delete, and manage directories with [DirectoryInfo](/dotnet/api/system.io.directoryinfo) and [Directory](/dotnet/api/system.io.directory) classes
+- Retrieve drive information using [DriveInfo](/dotnet/api/system.io.driveinfo)
+- Encode and decode strings with [MemoryStream](/dotnet/api/system.io.memorystream) and [StreamReader](/dotnet/api/system.io.streamreader)
 
 ## Read and write files with .NET APIs
 

hub/apps/develop/files/images/picker-folder.png

@@ -1,25 +1,49 @@
 ---
 ms.assetid: 33d8df1e-898d-48b7-9399-1aee673490d9
-title: Files, folders, and libraries with Windows App SDK
-description: Learn about reading and writing app settings, file and folder pickers, and special sand-boxed locations such as the Video/Music library with Windows App SDK apps.
-ms.date: 06/16/2023
-ms.topic: article
+title: Windows App SDK File Management - Read, Write, and Access Files
+description: Learn how to read and write files, use file pickers, and access sandboxed libraries in Windows App SDK apps. Get code examples and best practices for file management.
+ms.date: 09/10/2025
+ms.topic: concept-article
 keywords: windows 10, windows 11, windows, winui, windows app sdk, winrt, dotnet
 ms.localizationpriority: medium
+# customer intent: As a Windows app developer, I want to understand how to manage files and folders in my Windows App SDK app, so that I can read and write data, use file pickers, and access libraries.
 ---
-# Files, folders, and libraries with Windows App SDK
 
-Packaged Windows App SDK apps can leverage the powerful APIs provided by the [Windows.Storage](/uwp/api/Windows.Storage), [Windows.Storage.Streams](/uwp/api/Windows.Storage.Streams), and [Windows.Storage.Pickers](/uwp/api/Windows.Storage.Pickers) namespaces to efficiently read and write various data formats in files, as well as manage files and folders. This section covers essential topics such as reading and writing app settings, file and folder pickers, and accessing special sand-boxed locations like the Video/Music library. Learn how to optimize your app's file management capabilities with the Windows App SDK.
+# Manage files, folders, and libraries with Windows App SDK
 
-Windows 10 and later OS releases provide a wide variety of APIs related to files, folders, libraries, and settings for apps. These features are available via a combination of WinRT and .NET APIs provided by the [Windows SDK](https://developer.microsoft.com/windows/downloads/windows-sdk) and [.NET SDK](https://dotnet.microsoft.com/en-us/download).
+Windows App SDK provides powerful file management capabilities for packaged apps. You can use APIs from the [Windows.Storage](/uwp/api/Windows.Storage), [Windows.Storage.Streams](/uwp/api/Windows.Storage.Streams), and [Microsoft.Windows.Storage.Pickers](/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers) namespaces to efficiently read and write various data formats in files, as well as manage files and folders.
 
-## Read and write data with WinRT storage APIs
+There are a wide variety of APIs related to files, folders, libraries, and settings for Windows desktop apps beginning in Windows 10. These features are available via a combination of Windows App SDK, Windows Runtime (WinRT), and .NET APIs provided by the [Windows App SDK](/windows/apps/windows-app-sdk/downloads), [Windows SDK](https://developer.microsoft.com/windows/downloads/windows-sdk), and [.NET SDK](https://dotnet.microsoft.com/en-us/download).
+
+## Use Windows App SDK pickers to read and write data
+
+There are picker APIs available in the Windows App SDK version 1.8 and later. The following topics provide information about using the picker APIs to let users open and save files and folders in your app:
+
+| Topic | Description |
+|-------|-------------|
+| Open files and folders with pickers in WinUI | Use Windows App SDK file and folder pickers to let users browse and select files or folders in your WinUI app. The picker APIs provide a familiar Windows experience that helps users navigate their device and cloud storage locations. Learn how to let users select a file or folder to open using the [FileOpenPicker](/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.fileopenpicker) and [FolderPicker](/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.folderpicker) classes. |
+| Save a file with Windows App SDK picker in WinUI | When building WinUI apps and other Windows client apps, users often need to save files like documents, images, or other content to specific locations on their device. The Windows App SDK provides the [FileSavePicker](/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.filesavepicker) class to create a consistent, user-friendly interface that lets users choose where to save files and what to name them. |
+
+### Key differences between WinRT and Windows App SDK pickers
+
+Here are some key differences from the WinRT [Windows.Storage.Pickers](/uwp/api/windows.storage.pickers) used by UWP apps:
+
+- Unlike the existing **Windows.Storage.Pickers** API which returns [StorageFile](/uwp/api/windows.storage.storagefile) and [StorageFolder](/uwp/api/windows.storage.storagefolder) objects, this new API returns string-based paths through [PickFileResult](/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.pickfileresult) and [PickFolderResult](/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.pickfolderresult) classes. This simplifies the API and avoids complications with storage capabilities in elevated scenarios.
+- Similarly, the [FileSavePicker.SuggestedSaveFile](/uwp/api/windows.storage.pickers.filesavepicker.suggestedsavefile) property (which returned a **StorageFile**) has been replaced. Its functionality is now covered by two string properties: [SuggestedFolder](/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.filesavepicker.suggestedfolder) and [SuggestedFileName](/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.filesavepicker.suggestedfilename). These allow you to suggest the folder and file name for the save dialog.
+- All new pickers are designed specifically for desktop apps and use a **WindowId** property to link the picker to its host window, replacing the `WinRT.Interop.InitializeWithWindow.Initialize` pattern.
+- The new pickers allow developers to use them without requiring [FileTypeFilter](/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.fileopenpicker.filetypefilter) or [FileTypeChoices](/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.filesavepicker.filetypechoices) to be specified. While UWP pickers throw exceptions when these properties are not set, the new pickers default to showing all files when developers do not explicitly configure these properties.
+- The **HomeGroup** location has been excluded from the new [PickerLocationId](/windows/windows-app-sdk/api/winrt/microsoft.windows.storage.pickers.pickerlocationid) enum as it is no longer supported starting in Windows 10.
+- [FolderPicker.FileTypeFilter](/uwp/api/windows.storage.pickers.folderpicker.filetypefilter) has been excluded as it was not functionally appropriate for folder selection.
+- Excluding methods and properties that are already marked as deprecated or "Do not use". e.g., **PickSingleFileAndContinue**, **ContinuationData**, **ResumePickSingleFileAsync**, etc.
+- Excluding methods and properties for multi-user mode, because the new APIs are currently designed for desktop scenarios where each user has their own interactive session, and each session is completely independent of the other sessions on the device. This is in contrast to Xbox or other multi-user devices.
+
+## Access data with WinRT storage APIs
 
 Packaged apps have access to all the WinRT storage APIs available to UWP apps. Whether you're migrating an existing UWP app or creating a new app, you can use these APIs to read and write data. For examples of using the storage APIs in a WinUI app, see [Access files and folders with Windows App SDK and WinRT APIs](winrt-files.md).
 
-## Read and write data with .NET file APIs
+## Use .NET file APIs for data access
 
-In addition to the WinRT APIs, packaged apps can use the .NET APIs in the [System.IO](/dotnet/api/system.io) namespace to read and write data. When a new WinUI 3 project is created, its `Package.appxmanifest` file contains the following setting:
+In addition to the WinRT APIs, packaged desktop apps can use the .NET APIs in the [System.IO](/dotnet/api/system.io) namespace to read and write data. When a new WinUI 3 project is created, its `Package.appxmanifest` file contains the following setting:
 
 ``` xml
 <Capabilities>
@@ -41,8 +65,6 @@ If you're developing packaged WinUI apps, the WinRT storage APIs can be a powerf
 | [Create, write, and read a file](/windows/uwp/files/quickstart-reading-and-writing-files) | Read and write a file using a [StorageFile](/uwp/api/Windows.Storage.StorageFile) object. |
 | [Best practices for writing to files](/windows/uwp/files/best-practices-for-writing-to-files) | Learn best practices for using various file writing methods of the [FileIO](/uwp/api/windows.storage.fileio) and [PathIO](/uwp/api/windows.storage.pathio) classes. |
 | [Get file properties](/windows/uwp/files/quickstart-getting-file-properties) | Get properties—top-level, basic, and extended—for a file represented by a   [StorageFile](/uwp/api/Windows.Storage.StorageFile) object. |
-| [Open files and folders with a picker](/windows/uwp/files/quickstart-using-file-and-folder-pickers) | Access files and folders by letting the user interact with a picker. You can use the   [FolderPicker](/uwp/api/Windows.Storage.Pickers.FolderPicker) to gain access to a folder.<br/><br/>**NOTE:** In a desktop app (which includes WinUI 3 apps), you can use file and folder pickers from [Windows.Storage.Pickers](/uwp/api/windows.storage.pickers). However, if the desktop app requires elevation to run, you'll need a different approach because these APIs aren't designed to be used in an elevated app. For an example, see [FileSavePicker](/uwp/api/windows.storage.pickers.filesavepicker#in-a-desktop-app-that-requires-elevation). |
-| [Save a file with a picker](/windows/uwp/files/quickstart-save-a-file-with-a-picker) | Use [FileSavePicker](/uwp/api/Windows.Storage.Pickers.FileSavePicker) to let users specify the name and location where they want your app to save a file. |
 | [Accessing HomeGroup content](/windows/uwp/files/quickstart-accessing-homegroup-content) | Access content stored in the user's HomeGroup folder, including pictures, music, and videos. |
 | [Determining availability of Microsoft OneDrive files](/windows/uwp/files/quickstart-determining-availability-of-microsoft-onedrive-files) | Determine if a Microsoft OneDrive file is available using the [StorageFile.IsAvailable](/uwp/api/windows.storage.storagefile.isavailable) property. |
 | [Files and folders in the Music, Pictures, and Videos libraries](/windows/uwp/files/quickstart-managing-folders-in-the-music-pictures-and-videos-libraries) | Add existing folders of music, pictures, or videos to the corresponding libraries. You can also remove folders from libraries, get the list of folders in a library, and discover stored photos, music, and videos. |