集中文件存储

集中文件存储系统（CFS）是一种特殊的进程 API，用于协调 Limyee 电商平台内的所有文件管理。插件和外部应用程序使用它，与一个或多个存储文件（创建，更新，删除，检索和列表等）进行交互，这些文件通过特定提供程序存储在一个或多个物理位置

我什么时候会使用 CFS？

通常，与 CFS 的互动是间接的。例如，将文件上载到媒体库中是与媒体库 CFS 交互的抽象。Limyee 电商平台的自定义集成扩展可能需要一个位置来直接存储文件，作为其实现的一部分，可以通过定义新的文件存储更直接地与 CFS 进行交互。还可以通过实现自定义文件存储提供程序来更改 CFS 物理存储文件的位置。

创建新的文件存储

新的文件存储是通过实现 ICentralizedFileStore 插件类来创建的。有关更多详细信息和扩展，请参阅教程。通常，插件或插件集应仅与它们自行定义的文件存储进行交互，并且任何常规用途的访问都应作为新的 API 公开。

创建新的文件存储提供程序

默认情况下，CFS 可以配置为将文件物理存储在文件系统（本地或 UNC 共享）或云储存上。可以定义新的提供程序，使用其他服务以物理方式存储文件。有关更多详细信息和扩展，请参阅教程。

CFS 概念

文件存储

文件存储是服务于共同目的的文件集合。文件存储的示例包括用户头像、媒体库文件或小组件源文件。文件存储是通过实现 ICentralizedFileStore 及其扩展创建的，并通过其文件存储密钥（唯一标识文件存储的字符串名称）在 CFS API 中标识。

在文件存储中，使用路径和文件名存储文件。

路径可以有多个组件，以点分隔。路径必须介于 0 到 769 个字符之间，并且不能包含 Windows 文件系统上无效的字符。路径在使用之前不得存在（与 Windows 文件系统不同），并且当它不包含任何文件时，CFS 通常会删除对空路径的所有引用。

文件名唯一标识文件存储的同一路径文件。文件名必须介于 1 到 255 个字符之间，并且不能包含对 Windows 文件系统无效的字符。

文件存储提供程序

文件存储提供程序使 CFS 能够在新的物理位置存储一个或多个文件。默认情况下，Limyee 电商平台支持本地文件系统存储和一些云储存。如果需要，可以创建新的文件存储提供程序以支持将文件存储在其他位置。

提供程序与一个或多个文件存储的关联在 limyee.config 文件中定义。

与文件交互

在插件中，CFS 由 CentralizedFileStorage API 公开。此 API 提供事件、属性和方法，以便：

验证路径、文件名和文件访问
检索文件存储
设置路径格式
处理与文件相关的事件
生成文件的 URL 并确定由 URL 标识的文件

添加、更新、删除和检索文件通过特定的文件存储公开，该文件存储使用为文件存储配置的 CFS 提供程序表示。从 CFS 检索到的文件是 ICentralizedFile 的实现，它提供文件详细信息，如名称、URL、Stream和长度。

添加文件

通常，除非您的代码定义了文件存储，否则不会将文件直接添加到 CFS 文件存储中。通常，特定用途的 API 公开在文件存储的顶部。如果要使用定义的文件存储，则可以使用如下所示的代码：

ICentralizedFileStorageProvider fileStore = CentralizedFileStorage.GetFileStore("myfilestorekey");
ICentralizedFile file = null;
if (fileStore != null)
    file = fileStore.AddUpdateFile("path.to.file", "fileName.txt", new MemoryStream(System.Text.Encoding.UTF8.GetBytes("Content of the file")));

首先，我们按名称检索文件存储实现（我们首先创建了一个名为“myfilestorekey”的文件存储）。如果可以检索文件存储，则结果将是 ICentralizedFileStorageProvider 实例。使用该实例，我们可以使用路径（“path.to.file”）、文件名（“fileName.txt”）和内容（表示“文件内容”的 UTF8 字节的 Stream）调用 AddUpdateFile。

列出文件

与添加文件一样，列出文件是文件存储实现的一项功能。要列出我们添加的文件（以及同一路径中的任何其他文件）：请执行以下操作：

ICentralizedFileStorageProvider fileStore = CentralizedFileStorage.GetFileStore("myfilestorekey");
IEnumerable<ICentralizedFile> files = null;
if (fileStore != null)
    files = fileStore.GetFiles("path.to.file", PathSearchOption.TopLevelPathOnly);

列出文件时，GetFiles 方法支持筛选到特定路径，并仅将文件直接包含在该路径中（PathSearchOption.TopLevelPathOnly）或该路径子路径中的所有文件（PathSearchOption.AllPaths）。

删除文件

要删除文件，我们再次使用文件存储实例：

ICentralizedFileStorageProvider fileStore = CentralizedFileStorage.GetFileStore("myfilestorekey");
if (fileStore != null)
    fileStore.Delete("path.to.file", "fileName.txt");

请注意，如果文件不存在，则不会引发任何异常。如果该文件存在，则将其删除。如果它不存在，则该方法正常返回。Delete 方法还具有一个不带任何参数或路径的重写。删除时不带参数，整个文件存储将被清空。删除路径时，将删除与该路径匹配的任何文件作为前缀（例如，删除路径“path.t”将删除路径“path.to”和“path.two”（如果两者都存在）。

生成文件的 URL

生成文件的 URL 时，应考虑 URL 的使用和持续时间。可以通过以下三种方式之一检索 URL：

通用网址

通用 URL 适合在内容中长时间保留（例如，保存到数据库），并且与当前配置的文件存储提供程序没有直接关系。这些 URL 引用 CFS，如果访问用户有权访问该文件，则这些 URL 将（在内部或通过 HTTP）重定向到与文件关联的当前配置文件存储提供程序。要获取通用网址，请执行以下操作：

ICentralizedFileStorageProvider fileStore = CentralizedFileStorage.GetFileStore("myfilestorekey");
ICentralizedFile file = null;
string genericUrl = null;

if (fileStore != null)
    file = fileStore.GetFiles("path.to.file", "fileName.txt");
    
if (file != null)
    genericUrl = CentralizedFileStorage.GetGenericDownloadUrl(file);

持久网址

持久性 URL 适用于在动态内容中持久保存（例如，呈现在 UI、存储在生成的文件中、通过电子邮件发送等）。这些 URL 引用 CFS 提供程序（因此，如果提供程序更改，它们将不再有效），但也会绕过通用 URL 发生的处理重定向。要获取永久网址，请执行以下操作：

ICentralizedFileStorageProvider fileStore = CentralizedFileStorage.GetFileStore("myfilestorekey");
ICentralizedFile file = null;
string persistentUrl = null;

if (fileStore != null)
    file = fileStore.GetFiles("path.to.file", "fileName.txt");
    
if (file != null)
    persistentUrl = CentralizedFileStorage.GetPersistentDownloadUrl(file);

直接网址

直接 URL 仅适用于即时呈现。也就是说，当 URL 将很快被访问时。直接 URL 可以包含时间戳，这些时间戳将仅在有限的时间内授权对文件的访问（例如，当使用位于 Amazon S3 上的文件存储时，生成的 URL 仅在 30 分钟内有效）。动态 UI 呈现可能使用直接 URL，但否则应避免使用直接 URL。可以直接从 ICentralizedFile 中检索直接 URL：

ICentralizedFileStorageProvider fileStore = CentralizedFileStorage.GetFileStore("myfilestorekey");
ICentralizedFile file = null;
string directUrl = null;

if (fileStore != null)
    file = fileStore.GetFiles("path.to.file", "fileName.txt");
    
if (file != null)
    directUrl = file.GetDownloadUrl();

使用文件的 URL 检索文件

当您有一个 URL 并希望检查它是否存储在 CFS 中时，IsCentralizedFile 和 GetCentralizedFileByUrl 方法很有用：

string url = "http://example.com/cfs-file/myfilestorekey/path-to-file/fileName.txt";
ICentralizedFile file = null;

if (CentralizedFileStorage.IsCentralizedFileUrl(url))
    file = CentralizedFileStorage.GetCentralizedFileByUrl(url);

请注意，这些方法仅在 URL 为通用格式时才有效（请参阅上面的生成文件的 URL）。