Pixata.AspNetCore 2.0.0

Pixata.AspNetCore

Server-side helpers for ASP.NET Core apps - entity auditing, payload encryption, request logging, endpoint validation, document generation and route dumping.

A Nuget package is available for this project.

Breaking changes in v2.0.0

• No PDF engine. This package no longer references wkhtmltopdf (which was archived in 2023, and is unsafe with user-supplied HTML), so apps that don't generate PDFs no longer deploy its native binary. DocumentTemplateHelper now converts through a PdfConverterInterface, which comes from a separate package. Add Pixata.AspNetCore.Pdf.Telerik and call AddPixataTelerikPdf(), or, if you need to keep wkhtmltopdf for now, add the obsolete Pixata.AspNetCore.Pdf.WkHtmlToPdf and call AddPixataWkHtmlToPdf(). The wkhtmltopdf IConverter is no longer registered, and RegisterPdfConverter is obsolete and does nothing. See generating documents and PDFs.
• DocumentTemplateHelper no longer needs a request. Set the new DocumentBaseUrl option to generate documents from interactive Blazor Server components or background services. Without it, the helper uses the current request as before, and throws a clear InvalidOperationException when there isn't one, rather than a NullReferenceException. Its constructor has changed, which only matters if you construct it yourself.
• Auditing. AddAuditing<TContext>() now takes an Action<AuditingOptions> (which inherits from AuditRetentionOptions, so existing lambdas still compile), and AuditingInterceptor's constructor takes the options and an IServiceProvider. Synchronous SaveChanges() calls are now audited, users in interactive Blazor Server pages are now recorded rather than "System", and added entities are saved in a transaction with their audit rows. See auditing entities.

Important

Everything in this package is designed to be used server-side, and it references EF Core and other server-only libraries. Reference it from a server-side project. If you add it to a WASM project, you will get errors.

The client-side halves of the features that have one live in Pixata.Blazor, and the types that both ends share live in Pixata.Extensions.

Documentation

The documentation is split over the following pages...

Registering services

The code in this package requires certain dependencies to be registered in the DI container. In order to make this easier, there is an extension method to add them all. In Program.cs add this line...

builder.Services.AddPixataAspNetCore<ContactModel>();

...where ContactModel is any type in your project. If you are using the validation filter, then it is used here to point the framework to the assembly containing your models.

This registers everything in the package. If you only want some of it, you can say so...

builder.Services.AddPixataAspNetCore<ContactModel>(o => {
  o.RegisterDocumentTemplateHelper = false;
});

The options are...

RegisterPdfConverter is obsolete as of v2.0.0, and does nothing. This package no longer includes a PDF engine, see breaking changes in v2.0.0.

If you don't use the validation filter, there is a non-generic overload, which registers everything apart from the validation services...

builder.Services.AddPixataAspNetCore(o => o.DocumentBaseUrl = "https://www.example.com");

Note that AddPixataAspNetCore does not register the auditing, encryption or request logging services. Those have their own registration methods, as most apps only want some of them. See the pages listed above.

If you want to use the route dump feature then you'll also need the following...

app.MapPixataAspNetCoreApiEndpoints();