MVC Actions Audit Extension for Audit.NET library. (An extensible framework to audit executing operations in .NET).
Generate Audit Trails for MVC actions. Supporting AspNetCore Mvc.
Audit.Mvc provides the infrastructure to log interactions with MVC applications.
It can record action methods calls to controllers and razor pages.
Install
NuGet Package
To install the package run the following command on the Package Manager Console:
PM> Install-Package Audit.Mvc
IMPORTANT NOTE
If your project targets the full .NET framework, but you are using AspNet Core (Microsoft.AspNetCore.Mvc.*)
you should install and reference the Audit.Mvc.Core package instead, otherwise it will assume you are targeting
the old generation of ASP.NET:
PM> Install-Package Audit.Mvc.Core
If your project targets the NET Core framework (NetStandard >= 1.6), there is no difference between using Audit.Mvc or Audit.Mvc.Core
since both assumes AspNet Core.
Usage
MVC Controllers
Decorate the MVC Actions or Controllers you want to audit with [Audit] action filter.
For example:
public class HomeController : Controller
{
[Audit]
public ActionResult Index(int id, string name)
{
//...
return View(new SomeViewModel() { Id = id, Name = name });
}
[Audit(EventType = "InsertOrderAction", IncludeHeaders = true, IncludeModel = true)]
[HttpPost]
public ActionResult TestPost(SomeViewModel model)
{
//...
}
}
Or you can apply the filter only to certain pages, for example for pages under /Movies path:
public void ConfigureServices(IServiceCollection services)
{
services.AddRazorPages(options =>
{
options.Conventions.AddFolderApplicationModelConvention("/Movies", model => model.Filters.Add(new AuditPageFilter()
{
IncludeResponseBody = true
}));
});
}
Alternatively, if you want to setup the audit on a particular page and/or don't want to add the filter as a global filter,
you can override the OnPageHandlerExecutionAsync on your page model and manually call the same method
on an AuditPageFilter instance:
public class YourPageModel : PageModel
{
private readonly AuditPageFilter _pageFilter = new AuditPageFilter() { IncludeHeaders = true };
public override async Task OnPageHandlerExecutionAsync(PageHandlerExecutingContext context, PageHandlerExecutionDelegate next)
{
await _pageFilter.OnPageHandlerExecutionAsync(context, next);
}
// ...
}
Configuration
Output
The MVC audit events are stored using a Data Provider. You can use one of the available data providers or implement your own. Please refer to the data providers section on Audit.NET documentation.
Settings
The AuditAttribute can be configured with the following properties:
EventType: A string that identifies the event type. Can contain the following placeholders:
{controller}: replaced with the controller name (only for MVC).
{action}: replaced with the action method name (or the display name for razor pages).
{verb}: replaced with the HTTP verb used (GET, POST, etc).
{area}: replaced with the area name (only for razor pages).
{path}: replaced with the view path (only for razor pages).
IncludeHeaders: Boolean to indicate whether to include the Http Request Headers or not.
IncludeModel: Boolean to indicate whether to include the View Model or not.
IncludeRequestBody: Boolean to indicate whether to include or exclude the request body from the logs. Default is false. (Check following note)
IncludeResponseBody: Boolean to indicate whether to include response body or not. Default is false.
SerializeActionParameters: Boolean to indicate whether the action arguments should be pre-serialized to the audit event. Default is false.
When IncludeRequestBody is set to true you may need to enable rewind on the request body stream, otherwise the controller won't be able to read
the request body more than once (by default it's a forwand-only stream that can be read only once). You can enable rewind on your startup logic with the following startup code:
To selectively exclude certain controllers, action methods, action parameters or return values, you can decorate them with AuditIgnore attribute.
For example:
[Audit(IncludeHeaders = true, IncludeModel = true)]
public class AccountController : Controller
{
[HttpGet]
[AuditIgnore]
public IEnumerable<string> GetAccounts()
{
// this action will not be audited
}
[HttpPost]
public IEnumerable<string> PostAccount(string user, [AuditIgnore]string password)
{
// password argument will not be audited
}
[HttpGet]
[return:AuditIgnore]
public IEnumerable<string> GetSecrets(string user)
{
// the response body of this action will not be audited
}
}
You can also decorate the razor pages classes, methods or arguments to be ignored on the audits:
public class IndexModel : PageModel
{
[return:AuditIgnore]
public IActionResult OnGet(string user)
{
// the response of this action will not be audited
}
[AuditIgnore]
public void OnDelete(string user)
{
// this action will not be audited
}
public async Task<IActionResult> OnPostAsync([AuditIgnore]string password)
{
// password argument will not be audited
}
}
Output details
The following table describes the Audit.Mvc output fields:
If you are creating an ASP.NET Core MVC project from scratch, you can use the
dotnet new template provided on the library Audit.Mvc.Template.
This allows to quickly generate an audit-enabled MVC project that can be used as a starting point for your project or as a working example.
To install the template on your system, just type:
dotnet new -i Audit.Mvc.Template
Once you install the template, you should see it on the dotnet new templates list with the name mvcaudit as follows:
You can now create a new project on the current folder by running:
dotnet new mvcaudit
This will create a new Asp.NET Core 2.1 project.
To get help about the options:
dotnet new mvcaudit -h
Contribute
If you like this project please contribute in any of the following ways:
Spread the word by blogging about it, or sharing it on social networks:
<p class="share-buttons">
<a href="https://www.facebook.com/sharer/sharer.php?u=https://nuget.org/packages/Audit.NET/&t=Check+out+Audit.NET" target="_blank">
<img width="24" height="24" alt="Share this package on Facebook" src="https://nuget.org/Content/gallery/img/facebook.svg" / >
</a>
<a href="https://twitter.com/intent/tweet?url=https://nuget.org/packages/Audit.NET/&text=Check+out+Audit.NET" target="_blank">
<img width="24" height="24" alt="Tweet this package" src="https://nuget.org/Content/gallery/img/twitter.svg" />
</a>
</p>
