how to hydrate a projected file system file (Projfs)

Question

how to hydrate a projected file system file (Projfs)

Pribele, Joe 0

I have a implementation of a projfs provider but i am trying to implement a hydrate function that converts a placeholder to the a Hydrated placeholder.
https://learn.microsoft.com/en-us/windows/win32/projfs/projfs-functions

There does not appear to be any api to do this. Best I can come up with is to open the file and perform a read, which round trips through the system to retrieve the data from the projfs provider.

0 comments

2 answers

Your answer

Answer 1

ProjFS does not expose a separate hydrate API like the Cloud Files API does.

In ProjFS, a file becomes a hydrated placeholder when its data is requested through the provider callback flow:

An app opens the projected file.
ProjFS invokes PRJ_GET_FILE_DATA_CB for the requested byte range.
The provider returns the data by calling PrjWriteFileData.
After ProjFS receives the data, it writes it to disk and converts the file into a hydrated placeholder.

So for ProjFS, reading the file is the documented way to cause hydration. The callback documentation explicitly states that when ProjFS receives the data, it writes it to the file to convert it into a hydrated placeholder.

Also note the distinction between a hydrated placeholder and a full file:

Hydrated placeholder: file content has been cached locally, but it is still a placeholder.
Full file: the file’s primary data stream has been modified locally, or the file was created locally and does not exist in the provider store.

A hydrated placeholder does not become a full file just because it was recalled. Based on the documented state model, it becomes a full file when local modification occurs, such as opening it for write access.

If the requirement is an explicit hydrate API, that exists in the Cloud Files API as CfHydratePlaceholder, not in ProjFS. The ProjFS documentation also says that for scenarios needing features such as progress reporting or online/offline indication, the Cloud Files API should be considered instead.

Answer 2

Taki Ly (WICLOUD CORPORATION) 4,615 Microsoft External Staff Moderator

Hello @Pribele, Joe ,

ProjFS does not expose a dedicated "hydrate" API that converts a placeholder into a hydrated placeholder. Opening the file and reading its content is the documented path to trigger hydration, so the approach you described is consistent with how ProjFS is designed to work.

The flow is:

An app opens the projected file and reads the requested byte range.
ProjFS invokes the provider's PRJ_GET_FILE_DATA_CB callback.
The provider returns the data by calling PrjWriteFileData.
ProjFS writes that data to disk and converts the file into a hydrated placeholder.

This is stated in the callback reference. The Remarks for PRJ_GET_FILE_DATA_CB say: "When ProjFS receives the data it will write it to the file to convert it into a hydrated placeholder." The cache-state documentation walks through the same sequence, where the step "the app reads the content of the file" is what turns it into a hydrated placeholder:

A few additional points:

There is no explicit hydrate function in the ProjFS function list, so causing a read is the intended way to force the content to be cached. In practice, opening the file and reading at least one byte (or the full range) will drive the callback.
A hydrated placeholder does not automatically become a full file when it is read. Based on the documented state model, it becomes a full file only when the primary data stream is modified locally, for example when it is opened for write access.

If an explicit hydrate call is a hard requirement, it may be worth evaluating the Cloud Files API instead of ProjFS. The trade-offs are roughly:

ProjFS: simpler to implement, but no explicit hydrate API, no progress reporting, and no online/offline state indication. Hydration is driven by reading the file.
Cloud Files API: provides an explicit hydrate call (CfHydratePlaceholder) along with hydration policies, progress reporting, and online/offline indication in File Explorer, at the cost of a more complex implementation. The ProjFS documentation itself points to the Cloud Files API for scenarios that need these features.

So if reading the file to hydrate is sufficient for the scenario, staying on ProjFS is reasonable. If explicit hydration control and richer sync/UI behavior are needed, the Cloud Files API is the better fit.

Let me know if it would help to go deeper on either option. If you found my response helpful or informative, I would greatly appreciate it if you could follow this guide for your confirmation.Thank you.

Taki Ly (WICLOUD CORPORATION) 4,615 Reputation points Microsoft External Staff Moderator

2026-08-26T10:29:53.57+00:00

Hi @Pribele, Joe ,

Have you seen my answer in this post? If you have any question, feel free to reach out. I'm happy to support you.
Taki Ly (WICLOUD CORPORATION) 4,615 Reputation points Microsoft External Staff Moderator

2026-08-28T02:49:51.38+00:00

Hi @Pribele, Joe ,

As we haven’t heard back from you for a while, we’ll go ahead and close this thread for now. If you still need assistance later, feel free to reach out.

Thank you for your understanding.
Pribele, Joe 0 Reputation points

2026-09-14T23:13:35.5066667+00:00

Yes thanks that answers my question.
The cloud api doesn't work for me as it requires creating file on disk to which is very costly.
The next question would is there a way to avoid hydration of file when inspecting the file properties in windows explorer?
Taki Ly (WICLOUD CORPORATION) 4,615 Reputation points Microsoft External Staff Moderator

2026-09-16T03:34:29.9633333+00:00
Hi @Pribele, Joe ,

Thanks for confirming, and good follow up.

ProjFS has no per-open "inspect without hydrate" switch. Hydration is tied to a read of the file's primary data stream, which is what invokes PRJ_GET_FILE_DATA_CB and converts the placeholder into a hydrated placeholder. Inspecting basic properties does not do this: per the cache-state model, a placeholder already has name, size, timestamps, and attributes cached on disk, so the General tab is served from that metadata without hydrating.

If hydration happens during property inspection, a shell component is actually reading the content stream. In Explorer that is almost always a thumbnail provider, a property handler populating the Details tab or tooltips, or a preview handler. These run per file extension and are independent of ProjFS. You can confirm which one by checking TriggeringProcessImageFileName in your PRJ_GET_FILE_DATA_CB callback, or with Process Monitor.

So the way to avoid the hydration without leaving ProjFS is to stop those handlers from reading:

If it is the thumbnail, set Explorer to "Always show icons, never thumbnails" (Folder Options > View), or enforce the "Turn off the display of thumbnails and only display icons" policy.

Turn off the Preview pane, Details pane, and folder tooltips, since those also trigger property and preview reads.

If your provider owns the file type, avoid registering a content-reading property or thumbnail handler for it.

The model where Explorer knowingly avoids hydrating an online-only file for thumbnails and properties is the Cloud Files API design, which you have ruled out. Within ProjFS the shell treats a placeholder like a regular local file, so controlling which handlers read the content is the durable approach. If a native ProjFS "peek without hydrating" capability would help, that is a feature request for Feedback Hub.

References:

Cache State in the Virtualization Root

PRJ_GET_FILE_DATA_CB callback

PRJ_CALLBACK_DATA structure

If you found my response helpful or informative, I would greatly appreciate it if you could follow this guide for your confirmation.

Thank you.