ファイルの操作

このトピックでは、ユニバーサル Windows プラットフォーム (UWP) アプリでファイルに対する読み取りと書き込みを始めるために知っておく必要があることについて説明します。 主な API と型を紹介し、詳細情報を確認できるリンクを提供します。

これはチュートリアルではありません。 チュートリアルが必要な場合は、「ファイルの作成、書き込み、および読み取り」を参照してください。このチュートリアルでは、ファイルの作成、書き込み、および読み取り方法だけでなく、バッファーとストリームの使用方法を示しています。 また、「ファイル アクセスのサンプル」を参照することもできます。このドキュメントでは、ファイルの作成、読み取り、書き込み、コピー、削除方法に加え、ファイル プロパティを取得し、ファイルやフォルダーを記憶して、アプリが再び簡単にアクセスできるようにする方法を示しています。

ファイルからのテキストの書き込みと読み取りを行うためのコード、およびアプリのローカル フォルダー、移動フォルダー、一時フォルダーにアクセスする方法について説明します。

理解しておく必要があること

ファイルに対してテキストの読み取りや書き込みを行うために知っておく必要がある主な型を次に示します。

• Windows.Storage.StorageFile はファイルを表します。 このクラスには、ファイルに関する情報を提供するプロパティ、およびファイルを作成、開く、コピー、削除、名前変更するためのメソッドがあります。 文字列パスの処理には慣れているかもしれません。 文字列パスを指定する Windows ランタイム API もありますが、ファイルを表すのにより多く使用されるのが StorageFile です。これは、UWP を使用して操作するファイルの場合、パスがなかったり、パスの扱いが難しかったりすることがあるためです。 StorageFile.GetFileFromPathAsync() を使用して文字列パスを StorageFile に変換します。

• FileIO クラスを使用すると、テキストの読み取りと書き込みを簡単に行うことができます。 また、このクラスは、バイトの配列またはバッファーの内容の読み取り/書き込みを行うことができます。 このクラスは PathIO クラスとよく似ています。 主な違いは、PathIO が行うように文字列パスを指定する代わりに、StorageFile を指定する点です。

• Windows.Storage.StorageFolder はフォルダー (ディレクトリ) を表します。 このクラスには、ファイルの作成、フォルダーの内容の照会、フォルダーの作成、名前変更、削除を行うためのメソッド、およびフォルダーに関する情報を提供するプロパティがあります。

StorageFolder を取得する一般的な方法には次のものがあります。

• ユーザーが使用するフォルダーに移動できるようにする Windows.Storage.Pickers.FolderPicker。
• ローカル フォルダー、移動フォルダー、一時フォルダーのようなアプリに対してローカルであるいずれかのフォルダーに固有の StorageFolder を提供する Windows.Storage.ApplicationData.Current。
• ミュージック ライブラリまたは画像ライブラリのような既知のライブラリに StorageFolder を提供する Windows.Storage.KnownFolders。

ファイルへのテキストの書き込み

この概要では、テキストの読み取りと書き込みという単純なシナリオを中心に説明します。 まず、FileIO クラスを使用してファイルにテキストを書き込む一部のコードを見てみましょう。

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() は、文字列のコレクションをファイルに追加します。1 つの文字列が 1 行に書き込まれます。

ファイルからのテキストの読み取り

ファイルの書き込みと同様に、ファイルの読み取りは、ファイルの場所を指定することから始めます。 上の例と同じ場所を使用します。 次に、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<user name>\AppData\Local\Packages<app package identifier>\ に作成されます。 アプリは、これらのフォルダーにアクセスするためにすべての機能を宣言する必要はありません。また、これらのフォルダーは他のアプリがアクセスすることはできません。 アプリがアンインストールされると、これらのフォルダーも削除されます。

よく使用されるアプリ フォルダーをいくつか次に示します。

• 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、TimeSpans などの読み取りと書き込みを行います。
Windows.Storage.ApplicationData.Current	ローカル フォルダー、移動フォルダー、一時ファイル フォルダーなど、アプリ用に作成されたフォルダーへのアクセスを提供します。
Windows.Storage.Pickers.FolderPicker	ユーザーがフォルダーを選択できるようにし、そのフォルダーの StorageFolder を返します。 このようにして、既定ではアプリがアクセスできない場所にアクセスします。
Windows.Storage.Pickers.FileOpenPicker	ユーザーが開くファイルを選択できるようにし、そのファイルの StorageFile を返します。 このようにして、既定ではアプリがアクセスできないファイルにアクセスします。
Windows.Storage.Pickers.FileSavePicker	ユーザーがファイルのファイル名、拡張子、および記憶域の場所を選択できるようにします。 StorageFile を返します。 このようにして、既定ではアプリがアクセスできない場所にファイルを保存します。
Windows.Storage.Streams namespace	ストリームの読み取りと書き込みについて説明します。 特に、DataReader クラスと DataWriter クラスに注目します。これらのクラスはバッファー、バイト、整数、GUID、TimeSpans などの読み取りと書き込みを行います。

役立つドキュメント

トピック	説明
Windows.Storage Namespace	API リファレンス ドキュメントです。
ファイル、フォルダー、およびライブラリ	概念に関するドキュメントです。
ファイルの作成、書き込み、および読み取り	テキスト、バイナリ データ、およびストリームの作成、読み取り、書き込みについて説明します。
アプリ データのローカルへの保存に関する概要	ローカル データを保存するためのベスト プラクティスだけでなく、LocalSettings および LocalCache フォルダーの目的について説明します。
設定と他のアプリ データを保存して取得する	ローカル フォルダー、移動フォルダー、および一時フォルダーなど、さまざまなアプリのデータ ストアの概要を示します。
ファイル アクセス許可	アプリでアクセスできるファイル システムの場所に関する情報です。
ピッカーでファイルやフォルダーを開く	ピッカーの UI を介してユーザーが決定できるようにすることでファイルやフォルダーにアクセスする方法を示します。
Windows.Storage.Streams	ストリームの読み取りと書き込みに使用される型です。
ミュージック、画像、およびビデオ ライブラリのファイルとフォルダー	ライブラリからフォルダーを削除したり、ライブラリ内のフォルダーの一覧を取得したり、保存した写真、音楽、ビデオを検索したりする方法について説明します。

役立つコード サンプル

コード サンプル	説明
アプリケーション データ サンプル	アプリケーション データ API を使って、ユーザーごとに特有のデータを保存、取得する方法を示します。
ファイル アクセスのサンプル	ファイルを作成、読み取り、書き込み、コピー、および削除する方法を示します。
ファイル ピッカーのサンプル	ユーザーが UI で選択できるようにしてファイルやフォルダーにアクセスする方法、ユーザーが保存するファイルの名前、ファイルの種類、場所を指定できるようにファイルを保存する方法を示します。
JSON サンプル	Windows.Data.Json namespace を使用して、JavaScript Object Notation (JSON) オブジェクト、配列、文字列、数値、ブール値をエンコードおよびデコードする方法を示します。
その他のコード サンプル	[カテゴリ] ドロップダウン リストで、 [Files, folder, and libraries] (ファイル、フォルダー、およびライブラリ) を選択します。