如何用C#实现类似OneDrive的文件按需下载功能？

要实现这种「本地显示文件占位符、双击才实际下载」的功能，核心是用Windows原生的云文件API（Cloud Files API）——这正是OneDrive背后的技术，它允许你创建仅包含元数据的占位文件，直到用户触发打开操作时才下载实际内容。

实现步骤 #

1. 注册同步根目录 #

首先需要把你的C盘目标文件夹注册为「云同步根目录」，让Windows识别这个文件夹是和云端关联的。需要用到CfRegisterSyncRoot这个Win32 API，C#里要通过P/Invoke调用：

using System;
using System.Runtime.InteropServices;

public static class CloudFilesApi
{
    [DllImport("cfapi.dll", CharSet = CharSet.Unicode, SetLastError = true)]
    public static extern int CfRegisterSyncRoot(
        string syncRootPath,
        ref CF_SYNC_REGISTRATION registration,
        out Guid syncRootId);

    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
    public struct CF_SYNC_REGISTRATION
    {
        public uint StructSize;
        public Guid ProviderId;
        public string ProviderName;
        public string SyncRootIdentity;
        public CF_REGISTRATION_FLAGS Flags;
        public IntPtr Callback; // 后续回调函数的指针
        public IntPtr CallbackContext;
        public uint Version;
    }

    [Flags]
    public enum CF_REGISTRATION_FLAGS : uint
    {
        None = 0,
        AllowPinning = 1,
        AllowHydration = 2,
        AllowDehydration = 4,
        AllowSync = 8
    }
}

注册时要指定你的同步根路径（比如C:\MyCloudFiles），以及自定义的Provider ID和名称，同时注册回调函数用于处理文件打开事件。

2. 创建占位符文件 #

注册同步根后，就可以在里面创建占位符文件了。用CfCreatePlaceholder创建仅含元数据的文件，设置云端文件的大小、修改时间等信息：

[DllImport("cfapi.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern int CfCreatePlaceholder(
    string placeholderPath,
    ref CF_PLACEHOLDER_CREATE_INFO createInfo);

[StructLayout(LayoutKind.Sequential)]
public struct CF_PLACEHOLDER_CREATE_INFO
{
    public uint StructSize;
    public long FileSize;
    public long CreationTime;
    public long LastWriteTime;
    public long LastAccessTime;
    public long ChangeTime;
    public IntPtr FileId; // 关联你的云端文件ID
    public CF_PLACEHOLDER_CREATE_FLAGS Flags;
}

[Flags]
public enum CF_PLACEHOLDER_CREATE_FLAGS : uint
{
    None = 0,
    MarkFull = 1,
    MarkDeleted = 2,
    MarkTombstone = 4
}

// 示例：创建一个占位符
public static void CreateCloudPlaceholder(string localPath, long fileSize, DateTime lastWriteTime, string cloudFileId)
{
    var createInfo = new CF_PLACEHOLDER_CREATE_INFO
    {
        StructSize = (uint)Marshal.SizeOf<CF_PLACEHOLDER_CREATE_INFO>(),
        FileSize = fileSize,
        LastWriteTime = lastWriteTime.ToFileTimeUtc(),
        Flags = CF_PLACEHOLDER_CREATE_FLAGS.None
    };

    // 这里可以把cloudFileId存入FileId，后续下载时用
    IntPtr fileIdPtr = Marshal.StringToHGlobalUni(cloudFileId);
    createInfo.FileId = fileIdPtr;

    int result = CloudFilesApi.CfCreatePlaceholder(localPath, ref createInfo);
    Marshal.FreeHGlobal(fileIdPtr);

    if (result != 0)
    {
        throw new System.ComponentModel.Win32Exception(result);
    }
}

3. 处理文件打开回调（触发下载） #

当用户双击占位符文件时，Windows会触发CF_CALLBACK_TYPE.FILE_OPEN回调，你需要在回调里执行下载逻辑：

首先声明回调函数的委托：

public delegate int CfCallback(
    IntPtr callbackContext,
    CF_CALLBACK_TYPE callbackType,
    ref CF_CALLBACK_INFO callbackInfo,
    ref CF_CALLBACK_RESULT callbackResult);

public enum CF_CALLBACK_TYPE : uint
{
    FileOpen = 1,
    FetchData = 2,
    // 其他回调类型...
}

[StructLayout(LayoutKind.Sequential)]
public struct CF_CALLBACK_INFO
{
    public uint StructSize;
    public Guid SyncRootId;
    public string FilePath;
    public IntPtr FileId;
    // 其他字段...
}

[StructLayout(LayoutKind.Sequential)]
public struct CF_CALLBACK_RESULT
{
    public uint StructSize;
    public CF_CALLBACK_STATUS Status;
    // 其他字段...
}

public enum CF_CALLBACK_STATUS : uint
{
    Success = 0,
    Failed = 1,
    Pending = 2
}

在回调函数里，当收到FileOpen或FetchData事件时，从你的上传站点下载文件内容，写入占位符，然后通知Windows完成同步：

public static int CloudFileCallback(IntPtr context, CF_CALLBACK_TYPE type, ref CF_CALLBACK_INFO info, ref CF_CALLBACK_RESULT result)
{
    if (type == CF_CALLBACK_TYPE.FetchData)
    {
        string localPath = info.FilePath;
        string cloudFileId = Marshal.PtrToStringUni(info.FileId);

        // 1. 从你的上传站点下载文件内容
        byte[] fileContent = DownloadFileFromCloud(cloudFileId); // 你自己的下载逻辑

        // 2. 写入占位符文件
        System.IO.File.WriteAllBytes(localPath, fileContent);

        // 3. 通知Windows文件已完成同步
        int syncResult = CfStartSync(localPath, CF_START_SYNC_FLAGS.None);
        if (syncResult == 0)
        {
            CfCompleteSync(localPath, CF_COMPLETE_SYNC_FLAGS.None);
        }

        result.Status = CF_CALLBACK_STATUS.Success;
    }
    return 0;
}

[DllImport("cfapi.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern int CfStartSync(string filePath, CF_START_SYNC_FLAGS flags);

[DllImport("cfapi.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern int CfCompleteSync(string filePath, CF_COMPLETE_SYNC_FLAGS flags);

[Flags]
public enum CF_START_SYNC_FLAGS : uint { None = 0 }
[Flags]
public enum CF_COMPLETE_SYNC_FLAGS : uint { None = 0 }

注意事项 #

• 运行程序需要管理员权限，因为注册同步根需要系统级权限。
• 要处理各种错误场景：比如下载失败时，要将占位符标记为错误状态，避免用户重复触发失败操作。
• 测试时确保同步根目录是空的，或者已正确注册，否则占位符创建会失败。
• Windows 10 1709及以上版本才完全支持云文件API，低版本系统可能无法正常工作。

内容的提问来源于stack exchange，提问作者Hamed Hajiloo