處理檔案

本主題涵蓋在通用 Windows 平臺 （UWP） 應用程式中開始讀取和寫入檔案所需的內容。 引進主要 API 和類型，並提供連結以協助您深入瞭解。

這不是教學課程。 如果您想要教學課程，請參閱 建立、寫入和讀取檔案 ，除了示範如何建立、讀取和寫入檔案之外，也會示範如何使用緩衝區和數據流。 您可能也對檔案 存取範例 感興趣，該範例示範如何建立、讀取、寫入、複製和刪除檔案，以及如何擷取檔案屬性並記住檔案或資料夾，讓您的應用程式能夠再次輕鬆存取檔案。

我們將查看程式代碼，以從檔案撰寫和讀取文字，以及如何存取應用程式的本機、漫遊和暫存資料夾。

您需要知道什麼

以下是您需要知道的讀取或寫入檔案文字的主要類型：

• Windows.Storage.StorageFile 代表檔案。 這個類別的屬性提供檔案的相關信息，以及建立、開啟、複製、刪除和重新命名檔案的方法。 您可能習慣處理字串路徑。 有一些 Windows 執行階段 API 會接收字串路徑，但您更常會使用 StorageFile 來表示檔案，因為您在 UWP 中使用的某些檔案可能沒有路徑，或可能有一條笨拙的路徑。 使用 StorageFile.GetFileFromPathAsync（） 將字串路徑轉換為 StorageFile。

• FileIO 類別可讓您輕鬆讀取和寫入文字。 這個類別也可以讀取/寫入位元組數位列，或緩衝區的內容。 這個類別非常類似於 PathIO 類別。 主要差異在於，它是採用 StorageFile，而非像 PathIO 那樣採用字串路徑。

• Windows.Storage.StorageFolder 代表資料夾（目錄）。 這個類別具有建立檔案、查詢資料夾內容、建立、重新命名和刪除資料夾，以及提供資料夾相關信息的屬性的方法。

取得 StorageFolder 的常見方法包括：

• Windows.Storage.Pickers.FolderPicker 可讓使用者瀏覽至他們要使用的資料夾。
• Windows.Storage.ApplicationData.Current，提供與應用程式相關的本機、漫遊和暫存資料夾之一專屬的 StorageFolder。
• Windows.Storage.KnownFolders，它為音樂或圖片資料夾等已知媒體資料夾提供 StorageFolder。

將文字寫入檔案

在此簡介中，我們將著重於簡單的案例：讀取和寫入文字。 讓我們從查看一些使用 file IO 類別將文字寫入檔案的程式代碼開始。

Windows.Storage.StorageFolder storageFolder = Windows.Storage.ApplicationData.Current.LocalFolder;
Windows.Storage.StorageFile file = await storageFolder.CreateFileAsync("test.txt",
        Windows.Storage.CreationCollisionOption.OpenIfExists);

await Windows.Storage.FileIO.WriteTextAsync(file, "Example of writing a string\r\n");

// Append a list of strings, one per line, to the file
var listOfStrings = new List<string> { "line1", "line2", "line3" };
await Windows.Storage.FileIO.AppendLinesAsync(file, listOfStrings); // each entry in the list is written to the file on its own line.

我們會先識別檔案應位於何處。 Windows.Storage.ApplicationData.Current.LocalFolder 提供本機數據資料夾的存取權，這是在安裝應用程式時建立的。 如需應用程式可存取之資料夾的詳細資訊，請參閱 存取檔案系統 。

然後，我們會使用 StorageFolder 來建立檔案（如果檔案已經存在，請加以開啟）。

FileIO 類別提供將文字寫入檔案的便利方式。 FileIO.WriteTextAsync() 會以提供的文字取代檔案的整個內容。 FileIO.AppendLinesAsync() 將一個字串集合附加至檔案中，每行寫入一個字串。

從檔案讀取文字

如同寫入檔案，讀取檔案的開頭是指定檔案所在的位置。 我們將使用與上述範例相同的位置。 然後，我們將使用 FileIO 類別來讀取其內容。

Windows.Storage.StorageFolder storageFolder = Windows.Storage.ApplicationData.Current.LocalFolder;
Windows.Storage.StorageFile file = await storageFolder.GetFileAsync("test.txt");

string text = await Windows.Storage.FileIO.ReadTextAsync(file);

您也可以使用IList<string> contents = await Windows.Storage.FileIO.ReadLinesAsync(sampleFile);將檔案的每一行讀入集合中的個別字串.

存取檔案系統

在UWP平臺中，資料夾存取僅限於確保用戶數據的完整性和隱私權。

應用程式資料夾

安裝UWP應用程式時，會在 c：\users<使用者名稱>\AppData\Local\Packages<應用程式套件識別符>下建立數個資料夾，以儲存應用程式本機、漫遊和暫存盤等。 應用程式不需要宣告任何功能即可存取這些資料夾，而且其他應用程式無法存取這些資料夾。 卸載應用程式時，也會移除這些資料夾。

以下是一些您通常會使用的應用程式資料夾：

• LocalState：針對目前裝置的數據。 備份裝置時，此目錄中的數據會儲存在 OneDrive 的備份映射中。 如果使用者重設或取代裝置，將會還原數據。 使用 Windows.Storage.ApplicationData.Current.LocalFolder. 存取此資料夾。儲存不希望備份至 OneDrive 的本機數據到 LocalCacheFolder ，您可以使用 Windows.Storage.ApplicationData.Current.LocalCacheFolder存取此資料夾。

• RoamingState：儲存在這裡的數據不再漫遊（從 Windows 11 開始），但資料夾仍可供使用。 使用 Windows.Storage.ApplicationData.Current.RoamingFolder存取漫遊資料夾。 建議使用 Azure App Service作為替代。 Azure App Service 受到廣泛支援、記載良好、可靠，並支援 iOS、Android 和 Web 等跨平臺/跨生態系統案例。

• TempState：針對應用程式未執行時可能會刪除的數據。 使用 Windows.Storage.ApplicationData.Current.TemporaryFolder存取此資料夾。

存取檔案系統的其餘部分

UWP 應用程式必須將對應的功能新增至其資訊清單，以宣告其存取特定使用者程式庫的意圖。 然後，當應用程式安裝時，系統會提示使用者確認他們是否授權存取指定的連結庫。 如果沒有，則不會安裝應用程式。 有功能可以存取圖片、影片和音樂媒體櫃。 如需完整清單 ，請參閱應用程式功能宣告 。 若要取得這些連結庫的 StorageFolder，請使用 Windows.Storage.KnownFolders 類別。

文件庫

雖然可以存取使用者的文件庫，但此功能受到限制，這表示宣告該功能的應用程式將會被 Microsoft Store 拒絕，除非遵循程序以取得特別核准。 它不適用於一般用途。 請改用檔案或資料夾選擇器（請參閱 使用選擇器開啟檔案和資料夾、使用選擇器儲存檔案），讓使用者瀏覽至資料夾或檔案。 當使用者流覽至資料夾或檔案時，他們已隱含授與應用程式存取它的許可權，而且系統允許存取。

一般存取

或者，您的應用程式可以在其指令清單中宣告受限制的 broadFileSystem 功能，這也需要Microsoft Store 核准。 然後，應用程式可以存取使用者可存取的任何檔案，而不需要介入檔案或資料夾選擇器。

如需應用程式可存取之位置的完整清單，請參閱 檔案訪問許可權。

有用的 API 和檔

以下是 API 和其他實用檔的快速摘要，可協助您開始使用檔案和資料夾。

有用的 API

API（應用程式介面）	說明
Windows.Storage.StorageFile	提供檔案的相關信息，以及建立、開啟、複製、刪除和重新命名檔案的方法。
Windows.Storage.StorageFolder	提供資料夾的相關信息、建立檔案的方法，以及建立、重新命名和刪除資料夾的方法。
FileIO	提供簡單的方式來讀取和寫入文字。 這個類別也可以讀取/寫入位元組數位或緩衝區的內容。
PathIO	提供一個簡單的方式來讀取/寫入檔案中的文字，並提供檔案的字串路徑。 這個類別也可以讀取/寫入位元組數位或緩衝區的內容。
DataReader 和 DataWriter	從數據流中讀取和寫入緩衝區、位元組、整數、GUID、時間跨度等。
Windows.Storage.ApplicationData.Current	提供針對應用程式所建立資料夾的存取權，例如本機資料夾、漫遊資料夾和暫存盤資料夾。
Windows.Storage.Pickers.FolderPicker	讓使用者選擇資料夾，併為其傳回 StorageFolder 。 這是您存取應用程式預設無法存取的位置的方式。
Windows.Storage.Pickers.FileOpenPicker	讓使用者選擇要開啟的檔案，併為其傳回 StorageFile 。 這是您存取應用程式預設無法存取的檔案的方式。
Windows.Storage.Pickers.FileSavePicker	讓使用者選擇檔案的檔名、擴展名和儲存位置。 傳回 StorageFile。 應用程式預設無法存取的位置，這就是您將檔案儲存至該位置的方式。
Windows.Storage.Streams 命名空間	涵蓋讀取和寫入數據流。 特別是，請查看讀取和寫入緩衝區、位元組、整數、GUID、時間跨度等等的 DataReader 和 DataWriter 類別。

有用的檔

主題	說明
Windows.Storage 命名空間	API 參考文件。
檔案、資料夾和連結庫	概念文件。
建立、寫入和讀取檔案	涵蓋建立、讀取和寫入文字、二進位數據和數據流。
開始儲存應用程式資料於本機	除了涵蓋儲存本機數據的最佳做法之外，還涵蓋 LocalSettings 和 LocalCache 資料夾的用途。
儲存和擷取設定和其他應用程式數據	提供各種應用程式資料存放區的概觀，例如本機、漫遊和暫存資料夾。
檔案訪問許可權	應用程式可存取之檔案系統位置的相關信息。
使用選擇器開啟檔案和資料夾	示範如何讓使用者透過選擇器 UI 來決定檔案和資料夾。
Windows.Storage.Streams	用來讀取和寫入數據流的類型。
音樂、圖片和影片媒體櫃中的檔案和資料夾	涵蓋如何從文檔庫移除資料夾、取得文件庫中的資料夾清單，以及探索儲存的相片、音樂和影片。

實用的程式代碼範例

程式代碼範例	說明
應用程式數據範例	示範如何使用應用程式數據 API 來儲存和擷取每個使用者特有的數據。
檔案存取範例	示範如何建立、讀取、寫入、複製和刪除檔案。
檔案選擇器範例	示範如何讓使用者使用UI來選擇檔案和資料夾，以及如何儲存盤案，讓使用者可以指定要儲存之檔案的名稱、檔類型和位置。
JSON 範例	示範如何使用 Windows.Data.Json 命名空間來編碼和譯碼 JavaScript 物件表示法 （JSON） 對象、陣列、字串、數位和布爾值。
其他程式代碼範例	在類別下拉式清單中，選擇 [檔案]、[資料夾] 和 [資料庫]。