# 参数和选项

> Convert-DNSDebugLogFile 的每个选项实际改变了什么，何时需要它，以及容易踩的坑。

---

LLMS index: [llms.txt](/llms.txt)

---

本页以通俗语言解释各选项，且按你通常需要的顺序排列。它是指南，不是规范——权威且始终最新的参数列表在[命令参考](../commands/convert-dnsdebuglogfile/)和：

```powershell
Get-Help Convert-DNSDebugLogFile -Full
```

## 简短版

```powershell
Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log"
```

这单行命令已经给你合理的行为：同时生成数据和统计文件，分隔符为分号，使用你机器的日期格式，启用头部验证，源日志不变。以下内容是微调。

| 选项 | 默认值 | 何时更改 |
|---|---|---|
| `-InputFile` | *(必需)* | 始终 |
| `-OutputFile` | 输入路径，扩展名为 `.csv` | 你想输出到其他位置 |
| `-Delimiter` | `;` | 你的消费者期望逗号、制表符或管道符 |
| `-ComputerName` | 空 | 你合并多个服务器的日志 |
| `-OutputType` | `Both` | 你只想要数据，或只要汇总 |
| `-ContextFilter` | `All` | 你只关心实际的 DNS 流量 |
| `-InputCulture` | 当前文化 | 日志来自不同区域设置的服务器 |
| `-OutputCulture` | 当前文化 | 机器将读取 CSV |
| `-NoDetailsParsing` | 关闭 | 吞吐量比数据包内部细节更重要 |
| `-CompressOutput` | 关闭 | 你归档或传输结果 |
| `-RemoveSourceFile` | 关闭 | 定时清理，且你信任输出 |
| `-SkipHeaderValidation` | 关闭 | 文件有效但头部不寻常 |

## 输入和输出

### -InputFile

要转换的日志路径。接受数组，也接受管道输入——这就是为什么下面这样写有效：

```powershell
Get-ChildItem "C:\Administration\Logs\DNSServer\*.log" | Convert-DNSDebugLogFile
```

`Get-ChildItem` 输出带有 `FullName` 属性的对象，`-InputFile` 通过属性名接受它（别名包括 `FullName`、`Path`、`FilePath`）。无需 `ForEach-Object`。

本地路径和 SMB/UNC 路径都支持：

```powershell
Convert-DNSDebugLogFile -InputFile "\\dc01\C$\Administration\Logs\DNSServer\dns.log"
```

命令还能打开 DNS 服务器当前打开的日志。使用前请参阅下面的[活动日志](#活动日志)。

### -OutputFile

不指定时，CSV 文件会放在输入文件旁，基名相同，扩展名为 `.csv`。指定后，你控制目标位置。

<div class="alert alert-warning" role="alert"><div class="h4 alert-heading" role="heading">必须是文件路径，不能是文件夹</div>


`-OutputFile "D:\Processed\"` 并不意味着“写入此文件夹”。请给出包含文件名的完整路径：`-OutputFile "D:\Processed\dns_data.csv"`。

这也意味着当你管道传入多个文件时，`-OutputFile` 不合适——每次转换都会写入同一个目标。批量运行时，省略它，让每个日志生成自己的 CSV。
</div>


### -Delimiter

默认是分号，因为在逗号是小数点分隔符的地区，Excel 期望使用分号。对于假定经典逗号分隔值的工具和数据库，使用 `-Delimiter ","`；制表符用 `` -Delimiter "`t" ``。

无论选什么，导入时用*相同*的值。不匹配是“所有内容都挤到一列”的头号原因。

## 标记和过滤

### -ComputerName

填充 `ComputerName` 列。该列无论如何都会存在；此选项只是赋值。

```powershell
Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -ComputerName $env:COMPUTERNAME
```

<div class="alert alert-warning" role="alert"><div class="h4 alert-heading" role="heading">这不是远程参数</div>


尽管名字（以及别名 `-Server` / `-DNSServer` / `-HostName`）如此，`-ComputerName` **不**连接任何东西。没有 WinRM，没有远程执行。它只是写入输出中的标签。要读取远程日志，请将 `-InputFile` 指向 UNC 路径。
</div>


当多个服务器合并到一个数据集时，务必设置它——否则事后无法区分哪行来自哪个 DC。

### -OutputType

- `CSV` — 仅数据文件
- `Statistic` — 仅两个汇总文件，无行级数据
- `Both` — 三个文件都生成 *(默认)*

当只需每日趋势时，`Statistic` 是快速且小巧的选项。下游系统自行聚合时，选 `CSV`。

### -ContextFilter

DNS 调试日志混合了实际查询流量和服务器内部通信。`-ContextFilter` 决定哪些内容保留到输出。

```powershell
# 仅真实 DNS 流量
Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -ContextFilter Packet

# 流量加服务器事件，但无诊断注释
Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -ContextFilter Packet, Event
```

| 值 | 包含内容 |
|---|---|
| `All` | 全部 *(默认)* |
| `Packet` | DNS 查询和响应——大多数分析需要的数据 |
| `Event` | 服务器事件，如“DNS 服务器已启动” |
| `Note` | 诊断注释和警告，如套接字错误 |

其他上下文类型（`DSPoll`、`Init`、`Lookup`、`Recurse`、`Remote`、`Tombstone`）包含在 `All` 中。

过滤为仅 `Event` 或 `Note` 时，仅填充 `DateTime`、`ThreadId`、`Context` 和 `Information`——协议列为空，因为这些条目不携带该信息。

`-ContextFilter Packet` 是安全和报告管道的常用选择：它去除噪声，显著缩小输出。

## 国际日志

DNS 服务器以其运行机器的 Windows 区域设置写时间戳。德国 DC 写 `20.01.2026 23:00:16`；美国服务器写 `1/20/2026 11:00:16 PM`。如果工作站区域设置与服务器不同，解析会出错——更糟的是，日期和月份会被悄悄交换。

### -InputCulture

告诉解析器*源日志*使用的区域设置：

```powershell
Convert-DNSDebugLogFile -InputFile "C:\Logs\dns-berlin.log" -InputCulture 'de-DE'
```

| 文化 | 日志时间戳格式 |
|---|---|
| `de-DE` | `DD.MM.YYYY HH:MM:SS` |
| `en-US` | `M/D/YYYY H:MM:SS AM/PM` |
| `en-GB` | `DD/MM/YYYY HH:MM:SS` |
| `sv-SE` | `YYYY-MM-DD HH:MM:SS` |

默认是运行命令的会话文化。在混合区域环境中，显式设置它而非依赖默认——且记住以 `SYSTEM` 运行的计划任务可能没有你交互测试时的文化。

### -OutputCulture

控制时间戳*写入* CSV 的格式：

```powershell
# 类 ISO 输出，SQL Server、Power BI 和 pandas 都能理解
Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -OutputCulture 'sv-SE'

# 同效果，显式不变文化
Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" `
    -OutputCulture ([System.Globalization.CultureInfo]::InvariantCulture)
```

经验法则：如果人用 Excel 打开文件，匹配本地文化；机器读取时，使用 `sv-SE` 或不变文化，别担心导入端的区域设置。

这两个参数独立——你可以读取瑞典日志，写出美式格式。

## 速度和存储

### -NoDetailsParsing

如果 DNS 服务器记录完整数据包细节，解析器会把每个细节块转成 `Details` 列的 JSON。这有用，但也是运行中最耗时的部分，且膨胀 CSV。

```powershell
Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -NoDetailsParsing
```

该列仍存在但为空；TCP/UDP 细节头行仍在 `Information` 中。细节块丰富的日志可节省 30–50% 处理时间。只要查询级信息够用，就用它。

### -CompressOutput

压缩生成的 CSV 文件，删除未压缩文件。`dns.log` 生成 `dns.zip` 替代 `dns.csv`。

```powershell
Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -CompressOutput
```

此类 CSV 通常压缩率 90% 以上，归档和网络传输几乎免费节省存储。

### -RemoveSourceFile

成功转换后删除源 `.log` 文件——仅当所有输出文件都创建成功时才删除。

```powershell
Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -CompressOutput -RemoveSourceFile
```

<div class="alert alert-warning" role="alert"><div class="h4 alert-heading" role="heading">删除是永久的</div>


这里没有回收站。启用此选项前，请在真实日志上验证输出，且绝不要指向活动日志文件。

命令故意拒绝将 `-RemoveSourceFile` 与 `-SkipHeaderValidation` 结合使用，防止删除未确认是 DNS 日志的文件。
</div>


## 保护措施

### -SkipHeaderValidation

默认命令会检查文件是否真的是 DNS 服务器调试日志，才开始解析。这样能捕获指向错误文件夹的经典错误。

仅对真正不寻常的情况关闭：手工编辑日志、预过滤提取、自定义格式。其他情况保持开启——它开销小，是防止拼写错误导致垃圾行的屏障。

### -WhatIf 和 -Confirm

命令支持两者。`-WhatIf` 是查看新批处理会影响哪些文件的正确方式：

```powershell
Get-ChildItem "C:\Administration\Logs\DNSServer\*.log" |
    Convert-DNSDebugLogFile -RemoveSourceFile -WhatIf
```

`-Confirm` 在处理每个文件、删除源文件和覆盖现有输出前都会提示。

## 活动日志

`Convert-DNSDebugLogFile` 可以读取 DNS 服务器当前打开的文件。方便临时查看当前情况。

<div class="alert alert-warning" role="alert"><div class="h4 alert-heading" role="heading">不适合定时或生产运行</div>


活动日志在读取时会变化。输出可能漏掉转换期间写入的条目，且最后一条记录可能被截断。重复运行结果不同。

要获得可复现输出，请在 DNS 服务器启用日志轮换，仅转换已关闭、已轮换的文件——例如跳过最新文件：

```powershell
Get-ChildItem "C:\Administration\Logs\DNSServer\*.log" |
    Sort-Object LastWriteTime -Descending |
    Select-Object -Skip 1 |
    Convert-DNSDebugLogFile -ComputerName $env:COMPUTERNAME
```
</div>


## 综合示例

域控制器上的典型生产调用：

```powershell
Get-ChildItem "C:\Administration\Logs\DNSServer\*.log" |
    Sort-Object LastWriteTime -Descending |
    Select-Object -Skip 1 |
    Convert-DNSDebugLogFile `
        -ComputerName $env:COMPUTERNAME `
        -Delimiter ';' `
        -OutputType Both `
        -ContextFilter Packet `
        -OutputCulture 'sv-SE' `
        -CompressOutput
```

意思是：取除活动日志外的所有轮换日志，仅保留 DNS 流量，用服务器名标记每行，写机器可读时间戳，留下压缩档案。完整的计划任务和组策略版本见[GPO 驱动的收集示例](../examples/gpo-driven-collection/)。