.cursorrules for csharp.md

Every time you choose to apply a rule(s), explicitly state the rule(s) in the output. You can abbreviate the rule description to a single word or phrase.

Code Style and Structure

• Write concise, idiomatic C# code with accurate examples.
• Follow .NET, ASP.NET Core, XAF, and Blazor conventions and best practices.
• Use object-oriented programming patterns for XAF business objects and functional programming where appropriate.
• Leverage LINQ and lambda expressions for collection operations.
• Use descriptive variable and method names (e.g., CalculateTotal, IsUserSignedIn).

---

Naming Conventions

• Use PascalCase for class names, component names, method names, and public members.
• Use camelCase for private fields and local variables.
• Use UPPERCASE for constants.
• Prefix interface names with "I" (e.g., IUserService).
• Use meaningful names for XAF entities and properties to improve auto-generated UI readability.

---

Workflow and Development Environment

• Perform all running, debugging, and testing in Visual Studio Enterprise.
• Use Cursor AI for code editing, AI suggestions, and refactoring.
• Ensure Visual Studio Enterprise is used for compiling and launching the application.

---

C# and .NET Usage

• Use C# 10+ features (e.g., record types, pattern matching, global usings).
• Use Entity Framework Core as the ORM for database operations.
• Use XAF-specific annotations like [DefaultClassOptions] and [NavigationItem] for persistent entities.
• Follow Blazor's lifecycle conventions (OnInitializedAsync, OnParametersSetAsync) for Razor components.

---

Syntax and Formatting

• Follow C# Coding Conventions.
• Use null-conditional operators and string interpolation for concise expressions.
• Use var for implicit typing when the type is obvious.
• Apply XAF-specific attributes like [Appearance] for dynamic UI formatting.
• Use Razor Components appropriately in Blazor, preferring code-behind for complex logic.

---

Error Handling and Validation

• Implement proper error handling for Blazor pages, XAF, and API calls.
• Log errors using built-in .NET logging or third-party solutions.
• Use XAF validation attributes like [RuleRequiredField] and [RuleUniqueValue].
• Capture UI-level errors in Blazor using tools like ErrorBoundary.
• Use FluentValidation or DataAnnotations for forms and model validation.

---

Blazor Code Style and Performance Optimization

• Optimize Razor components by minimizing unnecessary re-renders, using ShouldRender() or StateHasChanged() efficiently.
• Use asynchronous programming (async/await) for API calls and non-blocking UI operations.
• Utilize EventCallback for efficient user interaction handling.
• Cache frequently used data using IMemoryCache for server apps or localStorage/sessionStorage for WebAssembly apps.
• Structure Blazor components and services following Separation of Concerns.

---

Business Object Design

• Inherit persistent entities from DevExpress.Persistent.BaseImpl.EF.BaseObject.
• Initialize navigation properties with ObservableCollection<T>.
• Use [NotMapped] for non-persistent properties.
• Define calculated fields with ObjectFormatter.Format for display purposes.
• Use XAF attributes like [Association] and [Aggregated] for relationships and collections.

---

API Design and Integration

• Follow RESTful principles for API endpoints and Blazor server communication.
• Use HttpClient for external and internal API integration in Blazor.
• Implement API versioning for backward compatibility.
• Use try-catch for API error handling and provide meaningful UI feedback.

---

Security

• Implement authentication and authorization using ASP.NET Identity or JWT tokens.
• Secure sensitive data in XAF using the Security System Module.
• Use HTTPS for all web communication and enforce SSL.
• Ensure proper CORS policies are implemented for cross-origin communication.

---

State Management

• Use Blazor's Cascading Parameters and EventCallback for state sharing in simple applications.
• Leverage Fluxor or BlazorState libraries for advanced state management in Blazor.
• For Blazor WebAssembly, use Blazored.LocalStorage or Blazored.SessionStorage for client-side persistence.
• Use Scoped Services and the StateContainer pattern for state management in Blazor Server apps.

---

Testing and Debugging

• Write unit and integration tests using xUnit, NUnit, or MSTest.
• Mock dependencies with Moq or NSubstitute during testing.
• Debug Blazor UI issues with browser developer tools and Visual Studio’s debugging features.
• Test XAF-specific logic in controlled test environments or modules.
• Profile and optimize performance using Visual Studio's diagnostic tools.

---

API Documentation

• Use Swagger/OpenAPI for backend API documentation.
• Ensure XML documentation for all public models, controllers, and business objects to enhance Swagger output.
• Document Blazor-specific API and component usage within your codebase for easier team collaboration.