> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WdCopySearchOptions

> WdCopySearchOptions

# WdCopySearchOptions

指定複製作業的檔案和目錄篩選模式。

**推出版本：** [RIT 0.0.8-Preview](/zh-TW/reference/remoting/release-versions#release-versions)。成員類型和可用性因版本而異；請參閱[變更歷程記錄](#change-history)。

<Warning>對於 `CopyFrom`，名稱模式只會影響本機差異列舉；不會限制遠端檔案的選取。</Warning>

## 語法

```cpp theme={null}
struct WdCopySearchOptions 
{ 
    const char* includeFilePattern;
    const char* excludeFilePattern;
    const char* excludeDirPattern;
    uint32_t includeFileAttributes;
    uint32_t excludeFileAttributes;
    uint32_t includeDirectoryAttributes;
    uint32_t excludeDirectoryAttributes;
};
```

### 成員

`_In_z_ includeFilePattern`\
類型：**const char\***

指定要包含在複製作業中之檔案的 Glob 模式 (例如，`"*"` 包含所有檔案，或 `"*.exe;*.dll"` 只包含可執行檔和 DLL)。

`_In_z_ excludeFilePattern`\
類型：**const char\***

指定要從複製作業中排除之檔案的 Glob 模式 (例如，`"*.pdb"` 排除偵錯符號)。

`_In_z_ excludeDirPattern`\
類型：**const char\***

指定要從複製作業中排除之目錄名稱 (而非路徑) 的 Glob 模式 (例如，`".vs;obj"` 排除 Visual Studio 和組建輸出目錄)。

`includeFileAttributes`\
類型：**uint32\_t**

檔案屬性的位元遮罩。具有任一指定屬性的檔案會包含在複製中。設定為 `0` 表示不依屬性篩選。如需檔案屬性的其他資訊，請參閱[檔案屬性常數](https://learn.microsoft.com/windows/win32/fileio/file-attribute-constants)。

`excludeFileAttributes`\
類型：**uint32\_t**

會使檔案從複製中排除的檔案屬性位元遮罩。設定為 `0` 表示不依屬性篩選。如需檔案屬性的其他資訊，請參閱[檔案屬性常數](https://learn.microsoft.com/windows/win32/fileio/file-attribute-constants)。

`includeDirectoryAttributes`\
類型：**uint32\_t**

**推出版本：** [RIT 0.0.13-preview](/zh-TW/reference/remoting/release-versions#release-versions)。

目錄屬性的位元遮罩。具有任一指定屬性的目錄會包含在複製中。這等同於將 `includeFileAttributes` 套用至目錄。設定為 `0` 表示不依屬性篩選。

`excludeDirectoryAttributes`\
類型：**uint32\_t**

**推出版本：** [RIT 0.0.13-preview](/zh-TW/reference/remoting/release-versions#release-versions)。

會使目錄從複製中排除的目錄屬性位元遮罩。這等同於將 `excludeFileAttributes` 套用至目錄。設定為 `0` 表示不依屬性篩選。

## 範例

下列名稱模式範例使用 `CopyTo`。

**只複製 `.exe` 和 `.dll` 檔案：**

```cpp theme={null}
WdCopySearchOptions searchOptions = {
    .includeFilePattern = "*.exe;*.dll",
    .excludeFilePattern = nullptr,
    .excludeDirPattern = nullptr,
    .includeFileAttributes = 0,
    .excludeFileAttributes = 0,
    .includeDirectoryAttributes = 0,
    .excludeDirectoryAttributes = 0
};
```

**從複製中排除名為 `temp` 的目錄：**

```cpp theme={null}
WdCopySearchOptions searchOptions = {
    .includeFilePattern = nullptr,
    .excludeFilePattern = nullptr,
    .excludeDirPattern = "temp",
    .includeFileAttributes = 0,
    .excludeFileAttributes = 0,
    .includeDirectoryAttributes = 0,
    .excludeDirectoryAttributes = 0
};
```

**只複製唯讀或系統檔案，並排除隱藏檔案：**

```cpp theme={null}
WdCopySearchOptions searchOptions = {
    .includeFilePattern = nullptr,
    .excludeFilePattern = nullptr,
    .excludeDirPattern = nullptr,
    .includeFileAttributes = FILE_ATTRIBUTE_READONLY | FILE_ATTRIBUTE_SYSTEM,
    .excludeFileAttributes = FILE_ATTRIBUTE_HIDDEN,
    .includeDirectoryAttributes = 0,
    .excludeDirectoryAttributes = 0
};
```

**只忽略隱藏目錄：**

```cpp theme={null}
WdCopySearchOptions searchOptions = {
    .includeFilePattern = nullptr,
    .excludeFilePattern = nullptr,
    .excludeDirPattern = nullptr,
    .includeFileAttributes = 0,
    .excludeFileAttributes = 0,
    .includeDirectoryAttributes = 0,
    .excludeDirectoryAttributes = FILE_ATTRIBUTE_HIDDEN
};
```

<Note>當包含模式與排除模式衝突時，排除模式優先，檔案將不會被複製。  </Note>

## 備註

透過 `searchOptions` 參數將此結構傳遞給 [WdRemoteCopy](/zh-TW/reference/remoting/functions/wdremotecopy)，以篩選要包含在複製作業中的檔案和目錄。如果為 `searchOptions` 傳遞 `nullptr`，則會複製所有檔案，不進行篩選。

## 變更歷程記錄

| 版本 | 變更 |
| - | - |
| [RIT 0.0.13-preview](/zh-TW/reference/remoting/release-versions#release-versions) | 將 `includeFileAttributes` 和 `excludeFileAttributes` 從 `uint64_t` 變更為 `uint32_t`。新增 `includeDirectoryAttributes` 和 `excludeDirectoryAttributes`，兩者皆為 `uint32_t`。 |
| [RIT 0.0.8-Preview](/zh-TW/reference/remoting/release-versions#release-versions) | 推出三個名稱模式欄位和兩個 `uint64_t` 檔案屬性遮罩。 |

RIT 0.0.13-preview 的變更改變了結構配置。請使用相符 API NuGet 套件中的標頭和程式庫重新建置原生呼叫端；請勿將舊的結構配置傳遞給較新的 API DLL。

## 需求

| 需求 | 值 |
| - | - |
| **標頭** | WdRemoteIteration.h |
| **程式庫** | wdremoteapi.lib |
| **支援的作業系統** | Windows 11 及更新版本 |
| **支援的架構** | x64, ARM64 |

## 另請參閱

* [WdRemoteCopy](/zh-TW/reference/remoting/functions/wdremotecopy)
* [XBOX PC Remote Iteration API](/zh-TW/reference/remoting/remoteiteration_members)


## Related topics

- [WdCopySearchOptions](/reference/remoting/structs/wdcopysearchoptions.md)
- [WdRemoteCopy](/ko/reference/remoting/functions/wdremotecopy.md)