Xeku.Core 0.0.0.4

Xeku.Core

Core XAF module providing essential utilities, attributes, and file storage.

繁體中文文檔

Features

• DataAdapters: Base classes for non-persistent object adapters supporting external data sources.
• Business Objects: Standard XAF implementations for common needs:
  • ApplicationUser: Extends PermissionPolicyUser with DisplayName, Email, and Photo.
  • ApplicationUserLoginInfo: Support for external authentication providers (OIDC, Keycloak).
• FileStorage: Compatible external file storage (stores files on disk instead of DB BLOB).
• Attributes: Powerful custom attributes for XAF model automation:
  • [CloneView]: Automatically creates a copy of a ListView or DetailView in the model.
  • [XpandNavigationItem]: Easily define complex navigation structures directly on business classes.
  • DetailView Layout: Automatic localization of layout group captions based on class names.
  • Validation: Pre-styled validation rules for CRON, Email, IP, Phone, URL, and ZipCode.

Architecture

graph TB
    subgraph "Core Utilities"
        Attributes["Custom Attributes"]
        Layout["Layout Logic"]
        Validation["Validation Rules"]
    end
    
    subgraph "Business Framework"
        BOs["Standard BOs (User, LoginInfo)"]
        FileStorage["File Storage Backend"]
        DataAdapters["Data Adapters"]
    end
    
    FileStorage --> LocalDisk["Local Disk"]
    
    style Attributes fill:#fff4e1
    style BOs fill:#fff4e1
    style LocalDisk fill:#fce4ec

Standard Business Objects

ApplicationUser

A base user class that inherits from PermissionPolicyUser and includes common fields:

• DisplayName: Ful name of the user (defaults to UserName on save).
• Email: Contact email address.
• Photo: Byte array for profile pictures.
• LoginInfo: Collection of external login details.

ApplicationUserLoginInfo

Stores link between a user and an OAuth/OpenID provider.

Installation

1. NuGet Package

dotnet add package Xeku.Core

2. Add Module Reference

// In your module constructor
RequiredModuleTypes.Add(typeof(Xeku.Core.CoreModule));

Custom Attributes

CloneView

Automatically generates a copy of a View in the XAF Model.

[CloneView(CloneViewType.ListView, "MyCustomListView")]
public class MyBusinessObject : BaseObject { ... }

XpandNavigationItem

Defines navigation paths directly on the business class.

[XpandNavigationItem("MasterData/Customers", "Customer_ListView")]
public class Customer : BaseObject { ... }

Validation Attributes

Ready-to-use validation rules based on regular expressions.

public class Contact : BaseObject {
    [EmailAddressValidation]
    public string Email { get; set; }

    [UrlValidation]
    public string Website { get; set; }
}

Layout Group Title Localization

Automatically localizes layout group captions when they match the class name. This ensures that UI groups remain consistent with domain object translations.

This feature is active by default once the module is registered.

MessageService

A utility service for displaying toast messages in XAF applications across both Blazor and WinForms.

Usage

using Xeku.Core.Services;

// Show success message (green)
MessageService.Success(Application, "Operation completed!");

// Show info message (blue)
MessageService.Info(Application, "Additional information here.");

// Show warning message (yellow)
MessageService.Warning(Application, "Please verify your input.");

// Show error message (red)
MessageService.Error(Application, "Something went wrong.");

All messages auto-dismiss after 5 seconds. Position is Top for Web and Toast for Win.

SecurityHelper

A platform-agnostic utility for retrieving the current logged-in user, solving issues where SecuritySystem.CurrentUserId may fail in Web API environments.

Background

In XAF Blazor and WinForms, you can directly use the static SecuritySystem.CurrentUserId to get the current user. However, in Web API (ASP.NET Core) environments, due to multi-threaded async processing, this static property may not return the correct value within XPO's OnSaving.

Usage

using Xeku.Core.Helpers;
using Xeku.Core.BusinessObjects;

public class MyBusinessObject : BaseObject
{
    // ...

    public override void AfterConstruction()
    {
        base.AfterConstruction();
        
        // Use SecurityHelper instead of static SecuritySystem.CurrentUserId
        Owner = SecurityHelper.GetCurrentUser(Session);
    }
}

How It Works

SecurityHelper.GetCurrentUser() tries in order:

1. DI method: Get ISecurityStrategyBase from Session.ServiceProvider (Web API compatible)
2. Static method: Fall back to SecuritySystem.CurrentUserId (Blazor/WinForms)

This ensures the current user is correctly retrieved regardless of platform.

Serilog Tracing

Replaces the default XAF eXpressAppFramework.log with Serilog-based file logging featuring:

• Daily rolling files: One log file per day
• 90-day retention: Configurable retention period
• Cross-platform: Works on Blazor, WebApi, and WinForms

Default Log Location

{ApplicationDirectory}/logs/log-YYYYMMDD.txt

Usage

Initialize at the very beginning of your application entry point:

using Xeku.Core.Services;

public static int Main(string[] args)
{
    SerilogTracingSetup.Initialize();
    // ... rest of your application startup
}

Disabling XAF Default Log Files

To ensure only Serilog generates logs and avoid creating duplicate eXpressAppFramework.log files, apply the following configurations based on your project type:

WinForms (App.config)

Add TraceLogLocation to the appSettings section:

<appSettings>
  <add key="eXpressAppFrameworkTraceLevel" value="3" />
  <add key="TraceLogLocation" value="None" />
</appSettings>

ASP.NET Core / WebApi (appsettings.json)

Add TraceLogLocation to the DevExpress:ExpressApp section:

{
  "DevExpress": {
    "ExpressApp": {
      "TraceLogLocation": "None"
    }
  }
}

Custom Configuration

// Custom log directory and retention
SerilogTracingSetup.Initialize(
    logDirectory: @"D:\Logs\MyApp",
    retainedFileCountLimit: 30,  // Keep 30 days
    fileNamePrefix: "myapp"      // Results in myapp-YYYYMMDD.txt
);

Shutdown

Call on application exit to ensure all logs are flushed:

SerilogTracingSetup.Close();

Log Viewer

Provides an in-app read-only log viewer accessible under Administration menu.

Features

• View log files directly in XAF UI (supports Blazor and WinForms)
• Lazy Loading: ListView only loads metadata, content is loaded when DetailView opens
• Live Refresh: Click "Refresh Log" button to reload latest content
• Admin-only: Updater.cs automatically configures Navigation Permission, non-admin roles cannot access Administration menu
• Located at: Administration > Log Viewer

Architecture

graph LR
    ListView[ListView<br/>Metadata Only] --> DetailView[DetailView<br/>Lazy Load Content]
    DetailView --> RefreshLog[Refresh Log<br/>Reload from Disk]

WebApi Endpoint

The log viewer also exposes authenticated API endpoints:

GET /api/logs           # List all log files
GET /api/logs/{fileName} # Get log file content

FileStorage (External File Storage)

Provides XAF-compatible external file storage. Files are stored on disk instead of database BLOB.

Default Storage Location

Files are stored by default in:

{ApplicationDirectory}/FileStorage/{Oid}-{FileName}

For example, Blazor Server apps store files in:

bin/Debug/net8.0/FileStorage/

Usage

Create a BusinessObject with an ExternalFileData property:

using DevExpress.Persistent.Base;
using DevExpress.Persistent.BaseImpl;
using DevExpress.Xpo;
using Xeku.Core.FileStorage;

[DefaultClassOptions]
public class CustomerDocument : BaseObject
{
    public CustomerDocument(Session session) : base(session) { }
    
    public string Title { get; set; }
    
    [Aggregated]
    [ExpandObjectMembers(ExpandObjectMembers.Never)]
    public ExternalFileData? Attachment { get; set; }
}

Custom Storage Path

// Set at application startup (Startup.cs or Program.cs)
ExternalFileData.DefaultBackend = new LocalStorageBackend("D:\\AppFiles");

Custom Storage Backend

Implement IStorageBackend to support other storage (Azure Blob, S3, etc.):

public class AzureBlobStorageBackend : IStorageBackend
{
    // Implement Save, Load, Delete, Exists, GetStoragePath
}

ExternalFileData.DefaultBackend = new AzureBlobStorageBackend();

Related Packages

• Xeku.Core.WebApi - WebApi
• Xeku.Core.Win - WinForms platform integration
• Xeku.Core.Blazor - Blazor Server integration

License

MIT License