# Convert-DNSDebugLogFile

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

---

## SYNOPSIS

将 Windows DNS 服务器调试日志转换为结构化的 CSV 格式，便于分析和报告。

## SYNTAX

### __AllParameterSets

```
Convert-DNSDebugLogFile [-InputFile] <string[]> [[-OutputFile] <string>] [[-Delimiter] <string>]
 [[-ComputerName] <string>] [[-OutputType] <string>] [[-ContextFilter] <string[]>]
 [[-InputCulture] <cultureinfo>] [[-OutputCulture] <cultureinfo>] [-SkipHeaderValidation]
 [-RemoveSourceFile] [-CompressOutput] [-NoDetailsParsing] [-WhatIf] [-Confirm] [<CommonParameters>]
```

## ALIASES

此 cmdlet 具有以下别名，

## DESCRIPTION

将 Windows DNS 服务器调试日志文件转换为结构化的 CSV 数据，可在 Excel、Power BI、SQL 数据库或 SIEM 工具中进行分析。  
设计用于安全分析、性能监控、故障排除和合规报告。

该 cmdlet 解析 DNS 调试日志并输出一致的 CSV 格式以供分析。  
CSV 输出包含 18 列，包括用于事件/诊断文本的 `Information` 列、可选的用于数据包详细信息块的 JSON 格式 `Details` 列，以及始终存在的 `ComputerName` 列（除非指定，否则为空）。

主要特性：  
- 流式处理，避免将整个文件加载到内存（适合超大日志）  
- 针对大文件（100MB+）优化的高性能解析  
- 可自定义 CSV 分隔符（默认分号）  
- 可选的统计汇总，包含聚合指标  
- 上下文过滤（数据包、事件、注释及其他上下文），聚焦特定日志条目类型  
- 支持文化感知的日期解析和格式化，适用于国际服务器  
- 支持管道批量处理多个文件  
- 可选输出文件压缩（ZIP 格式）  
- 可选处理后自动删除源文件  
- 头部验证确保数据完整性

输出格式：  
`ComputerName` 列始终包含在每条记录末尾。  
如果未指定 -ComputerName 参数，该列为空。  
确保多服务器合并场景下输出结构一致。

性能：  
使用 StreamReader/StreamWriter 64KB 缓冲区优化，流式处理实现内存高效，使用字符串操作替代正则表达式，手动生成 CSV，基于哈希表高效收集统计数据。

兼容性：  
- PowerShell 5.1+（桌面版和核心版）  
- Windows Server 2016+  
- 支持 DNS Server 2012 R2 至 2025 日志格式

## EXAMPLES

### 示例 1

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

使用默认设置转换 DNS 调试日志（数据文件和统计文件均用分号分隔符）。  
输出：  
- C:\Logs\dns.csv  
- C:\Logs\dns_Statistic.csv  
- C:\Logs\dns_PacketStatistic.csv

### 示例 2

```powershell
PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -OutputType CSV
```

仅生成数据文件，不生成统计文件。  
输出：C:\Logs\dns.csv

### 示例 3

```powershell
PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -OutputType Statistic
```

仅生成带聚合指标的统计文件。  
输出：  
- C:\Logs\dns_Statistic.csv  
- C:\Logs\dns_PacketStatistic.csv

### 示例 4

```powershell
PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -OutputFile "C:\Output\parsed.csv"
```

将日志转换到自定义输出位置。  
输出：C:\Output\parsed.csv

### 示例 5

```powershell
PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -Delimiter "," -ComputerName "DNS01" -OutputType Both
```

使用逗号分隔符转换，并添加值为 "DNS01" 的 ComputerName 列。  
输出：  
- C:\Logs\dns.csv  
- C:\Logs\dns_Statistic.csv  
- C:\Logs\dns_PacketStatistic.csv

### 示例 6

```powershell
PS C:\> Get-ChildItem "C:\Logs\*.log" | Convert-DNSDebugLogFile -OutputType Both
```

通过管道批量处理多个 DNS 调试日志文件。  
输出：每个 .log 文件生成对应的 .csv 和 _statistic.csv 文件

### 示例 7

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

转换并压缩输出为 ZIP 归档。  
输出：C:\Logs\dns.zip（包含 dns.csv 及统计文件）

### 示例 8

```powershell
PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -RemoveSourceFile -Verbose
```

转换日志并在成功处理后删除源文件。  
详细输出确认文件已删除。

### 示例 9

```powershell
PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -InputCulture 'de-DE' -OutputCulture 'en-US'
```

解析德国日期格式（DD.MM.YYYY），输出为美国格式（MM/DD/YYYY）。  
适用于处理来自不同区域设置服务器的日志。

### 示例 10

```powershell
PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -ContextFilter 'Packet'
```

仅转换 DNS 查询/响应数据包条目，排除 EVENT 和 Note 条目。  
用于聚焦实际 DNS 流量分析。

### 示例 11

```powershell
PS C:\> Convert-DNSDebugLogFile -InputFile "C:\Logs\dns.log" -ContextFilter 'Packet','Event'
```

转换 DNS 查询/响应数据包和服务器事件，排除 Note 及其他条目。  
用于分析 DNS 流量及服务器事件上下文。

### 示例 12

```powershell
PS C:\> Get-ChildItem "C:\Logs\*.log" | Convert-DNSDebugLogFile -RemoveSourceFile -CompressOutput
```

自动化日志归档：处理所有日志，压缩输出，并删除源文件。  
适合计划任务的日志处理流水线。

### 示例 13

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

处理大型日志文件，禁用详细解析以获得最大性能。  
跳过 PACKET 详细块，Details 列保持为空。  
适用于处理非常大文件且不需要详细数据包结构的场景。

## PARAMETERS

### -CompressOutput

在创建后将输出的 CSV 文件压缩为 ZIP 归档。

创建一个包含生成的 CSV 文件的 .zip 文件，然后删除未压缩的 CSV 文件。  
ZIP 文件与输出 CSV 位于同一目录，使用相同的基本文件名。

优点：  
- 显著减少磁盘空间（CSV 文件通常压缩率超过 90%）  
- 简化文件管理和归档  
- 适合长期存储

示例：输入 'dns.log' 生成 'dns.csv'，压缩为 'dns.zip'，然后删除 'dns.csv'。

```yaml
Type: SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```

### -ComputerName

指定 CSV 输出中 ComputerName 列的值。  
ComputerName 列始终存在于输出中——如果未指定此参数，该列为空。

合并来自多个 DNS 服务器的日志时，使用此参数标识源服务器。

注意：这不是远程参数。  
它仅用于标记输出。  
如果 -InputFile 指向 UNC 路径，文件将直接从该路径读取（不执行 WinRM/远程操作）。

```yaml
Type: String
DefaultValue: ''
SupportsWildcards: false
Aliases:
- Server
- DNSServer
- HostName
ParameterSets:
- Name: (All)
  Position: 3
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```

### -Confirm

在运行 cmdlet 前提示确认。

指定后，会在以下操作前提示确认：  
- 处理每个 DNS 调试日志文件  
- 删除源文件（当指定 -RemoveSourceFile 时）  
- 覆盖已存在的输出文件

适合交互式处理时控制处理文件。

```yaml
Type: SwitchParameter
DefaultValue: ''
SupportsWildcards: false
Aliases:
- cf
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```

### -ContextFilter

过滤输出中包含的日志条目类型。  
支持单个或多个值。

DNS 调试日志包含不同上下文类型：  
- PACKET：DNS 查询和响应数据包信息（主要数据）  
- EVENT：DNS 服务器事件（例如，“DNS 服务器已启动。”）  
- Note：诊断注释和警告（例如，套接字错误、内部状态）  
- DSPoll、Init、Lookup、Recurse、Remote、Tombstone：其他上下文类型

有效值：  
- 'All'：包含所有上下文类型（默认）  
- 'Packet'：仅包含 PACKET 条目（DNS 查询/响应）  
- 'Event'：仅包含 EVENT 条目（服务器事件）  
- 'Note'：仅包含 Note 条目（诊断信息）  
- 任意组合：指定多个值以包含特定上下文类型

默认：All

示例：  
- 'Packet' 仅过滤 DNS 流量  
- 'Packet','Event' 包含 DNS 流量和服务器事件  
- 'Note','Event' 包含诊断注释和服务器事件

注意：过滤为 'Event' 或 'Note' 时，仅 DateTime、ThreadId、Context 和 Information 列有数据，其他列（Protocol、ClientIP 等）为空。

```yaml
Type: String[]
DefaultValue: "@('All')"
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 5
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```

### -Delimiter

指定 CSV 输出的分隔符字符。

默认：分号（;）

常用替代：逗号（,）、制表符（`t）、管道符（|）

在使用逗号作为小数点分隔符的地区（欧洲）使用分号。  
对于标准 CSV 工具和数据库，使用逗号分隔。

```yaml
Type: String
DefaultValue: ;
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 2
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```

### -InputCulture

指定用于解析 DNS 调试日志中日期/时间值的文化/区域设置。

DNS 服务器调试日志使用生成日志的服务器 Windows 区域设置的日期格式。  
处理来自不同区域设置服务器的日志时使用此参数。

默认：当前文化

常见示例：  
- 'de-DE' 或 'de-AT'：德国格式（DD.MM.YYYY 或 DD/MM/YYYY）  
- 'en-US'：美国格式（MM/DD/YYYY，含 AM/PM）  
- 'en-GB'：英国格式（DD/MM/YYYY，24 小时制）  
- 'sv-SE'：瑞典/ISO 格式（YYYY-MM-DD）

```yaml
Type: CultureInfo
DefaultValue: '[System.Globalization.CultureInfo]::CurrentCulture'
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 6
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```

### -InputFile

指定要解析的 DNS 调试日志文件路径。  
支持数组以处理多个文件。

支持从 Get-ChildItem 或其他生成文件的 cmdlet 管道输入。

```yaml
Type: String[]
DefaultValue: ''
SupportsWildcards: false
Aliases:
- FullName
- FilePath
- InputPath
- File
- Path
ParameterSets:
- Name: (All)
  Position: 0
  IsRequired: true
  ValueFromPipeline: true
  ValueFromPipelineByPropertyName: true
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```

### -NoDetailsParsing

跳过将 PACKET 详细块解析为结构化 JSON 格式。

指定后，包含详细块的 PACKET 记录将在 Information 列显示 TCP/UDP 信息行，但 Details 列保持为空。  
这显著提升处理大型日志文件时的性能，适用于不需要详细数据包结构分析的场景。

使用场景：  
- 处理非常大（100MB+）日志文件，只需基本查询信息  
- 不需要详细结构（消息标志、DNS 区段）分析  
- 优先提升解析速度而非数据完整性

性能影响：对于包含大量 PACKET 详细块的日志，处理速度可提升 30-50%。

```yaml
Type: SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```

### -OutputCulture

指定用于格式化输出 CSV 文件中日期/时间值的文化/区域设置。

控制 DateTime 值写入 CSV 的格式。  
当 CSV 文件将被特定区域设置的应用程序或系统使用时，使用此参数。

默认：当前文化

常见示例：  
- 'en-US'：美国格式（MM/DD/YYYY）  
- 'de-DE'：德国格式（DD.MM.YYYY）  
- 'sv-SE' 或 InvariantCulture：ISO 格式（YYYY-MM-DD），兼容性最佳

```yaml
Type: CultureInfo
DefaultValue: '[System.Globalization.CultureInfo]::CurrentCulture'
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 7
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```

### -OutputFile

指定输出 CSV 文件的路径。  
如果未指定，使用输入文件名并替换为 .csv 扩展名，输出到输入文件所在目录。

重要：必须是文件路径，不能是目录。  
如果想使用输入文件目录但自定义文件名，请指定包含文件名的完整路径。

```yaml
Type: String
DefaultValue: ''
SupportsWildcards: false
Aliases:
- Output
- Destination
- OutFile
- OutputPath
ParameterSets:
- Name: (All)
  Position: 1
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```

### -OutputType

指定生成的输出类型。

有效值：  
- 'CSV'：仅生成包含所有解析日志条目的数据文件  
- 'Statistic'：仅生成包含聚合指标的统计文件  
- 'Both'：同时生成数据文件和统计文件（默认）

默认：Both

生成统计时，会创建两个独立文件：  
- '_Statistic.csv'：按日期和上下文类型的汇总计数（日期、上下文、计数、计算机名）  
- '_PacketStatistic.csv'：按日期、客户端 IP、协议、方向和查询类型的详细 PACKET 计数（日期、客户端 IP、协议、方向、查询类型、计数、计算机名）

```yaml
Type: String
DefaultValue: Both
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 4
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```

### -RemoveSourceFile

成功处理后删除源 DNS 调试日志文件。

适用于自动化日志处理流水线或磁盘空间管理。  
仅当处理成功且所有输出文件生成后才删除源文件。

安全性：不能与 -SkipHeaderValidation 一起使用，以防意外删除无效文件。

警告：源文件将被永久删除。  
使用此选项前请确保输出文件有效。

```yaml
Type: SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```

### -SkipHeaderValidation

跳过 DNS 调试日志头部验证检查。

默认情况下，cmdlet 会验证输入文件是否具有有效的 DNS 服务器调试日志头部。  
使用此开关可处理无验证的文件，适用于：  
- 修改或自定义日志格式  
- 解决验证问题  
- 非标准或预处理日志

警告：如果文件不是有效的 DNS 日志，可能导致处理错误。

```yaml
Type: SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```

### -WhatIf

显示如果运行 cmdlet 会发生什么。  
cmdlet 不会实际运行。

指定后，显示将执行的操作详细信息，但不执行。  
适用于：  
- 预览将处理哪些文件  
- 验证输出文件路径  
- 在生产环境运行前测试脚本

```yaml
Type: SwitchParameter
DefaultValue: ''
SupportsWildcards: false
Aliases:
- wi
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```

### CommonParameters

此 cmdlet 支持常用参数：-Debug、-ErrorAction、-ErrorVariable、  
-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、  
-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。  
更多信息请参见 [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216)。

## INPUTS

### System.String[]

## NOTES

版本  : 1.7.1.1  
作者  : Andi Bellstedt, Copilot  
日期  : 2026-01-26  
关键词: Microsoft Windows Server, DNSServer, DNS, DebugLog, LogParser

## RELATED LINKS

- [github.com/AndiBellstedt/DNSServer.DebugLogParser](https://github.com/AndiBellstedt/DNSServer.DebugLogParser)