---
title: "Read-DbaAuditFile"
description: "Parses SQL Server audit files (.sqlaudit) into structured event data for security analysis and compliance reporting."
url: "https://dbatools.io/Read-DbaAuditFile/"
availability: "Windows, Linux, macOS"
tags: ["XE", "Audit", "Security"]
author: "Chrissy LeMaire (@cl), netnerds.net"
source: "https://github.com/dataplat/dbatools/blob/master/public/Read-DbaAuditFile.ps1"
last_updated: "2024-01-01"
---

# Read-DbaAuditFile

## Synopsis

Parses SQL Server audit files (.sqlaudit) into structured event data for security analysis and compliance reporting.

## Description

Reads and parses SQL Server audit files (.sqlaudit) created by SQL Server Audit functionality, converting binary audit data into readable PowerShell objects. Each audit event is returned with its timestamp, event details, fields, and actions in a structured format that's easy to filter, export, or analyze. This is essential for security investigations, compliance reporting, and monitoring database access patterns since SQL Server audit files are stored in a proprietary binary format that can't be read directly. Works with local files, UNC paths, or can be piped from Get-DbaInstanceAudit to automatically locate and read audit files from remote instances.

## Syntax

```powershell
Read-DbaAuditFile
    [-Path] <Object[]>
    [-Raw]
    [-EnableException]
    [<CommonParameters>]

```

## Examples

### Example 1: Returns events from C:\temp\logins.sqlaudit

```powershell
PS C:\> Read-DbaAuditFile -Path C:\temp\logins.sqlaudit
```

### Example 2: Returns events from all .sqlaudit files in C:\temp\audit

```powershell
PS C:\> Get-ChildItem C:\temp\audit\*.sqlaudit | Read-DbaAuditFile
```

### Example 3: Reads remote Audit details by accessing the file over the admin UNC share

```powershell
PS C:\> Get-DbaInstanceAudit -SqlInstance sql2014 -Audit LoginTracker | Read-DbaAuditFile
```

### Required Parameters

##### -Path

Specifies the path to SQL Server audit files (.sqlaudit) to read and parse. Accepts file paths, FileInfo objects from Get-ChildItem, or Audit objects from Get-DbaInstanceAudit.  
Supports UNC paths for reading remote files and automatically expands wildcards to process multiple related audit files. Use this when you need to analyze audit data from specific files or when   
piping from other dbatools audit commands.

| Property | Value |
| --- | --- |
| Alias | FullName |
| Required | True |
| Pipeline | true (ByValue) |
| Default Value |  |

### Optional Parameters

##### -Raw

Returns the unprocessed enumeration object instead of structured PowerShell objects.  
Use this when you need access to the raw audit data structure for custom processing or when working with audit parsing tools that expect the native format.

| Property | Value |
| --- | --- |
| Alias |  |
| Required | False |
| Pipeline | false |
| Default Value | False |

##### -EnableException

By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.  
This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables advanced scripting.  
Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own try/catch.

| Property | Value |
| --- | --- |
| Alias |  |
| Required | False |
| Pipeline | false |
| Default Value | False |

## Outputs

**System.Object (when -Raw is specified)**

Returns the raw enumeration object containing unprocessed audit event data from Read-XEvent. PSCustomObject (default)

**Returns one object per audit event with the following standard properties:**

- name: The name of the audit event (string)
- timestamp: The timestamp when the event occurred (datetime)

**Additional properties are dynamically added based on the audit file contents and include:**

- Fields.*: All field names present in the audit events (properties vary based on audit configuration)
- Actions.*: All action names from the audit events with the action suffix only (e.g., 'session_id' from 'server_principal_name.session_id')
The exact set of additional properties depends on what SQL Server Audit events and fields are present in the .sqlaudit files being read. Use Select-Object * to see all available properties for a given audit file.

---

Part of [dbatools](https://dbatools.io/), a free and open source PowerShell module for SQL Server administration. Full command index: https://dbatools.io/commands/