|
| 1 | +--- |
| 2 | +description: 'Oqtane Module patterns' |
| 3 | +applyTo: '**/*.razor, **/*.razor.cs, **/*.razor.css' |
| 4 | +--- |
| 5 | + |
| 6 | +## Blazor Code Style and Structure |
| 7 | + |
| 8 | +- Write idiomatic and efficient Blazor and C# code. |
| 9 | +- Follow .NET and Blazor conventions. |
| 10 | +- Use Razor Components appropriately for component-based UI development. |
| 11 | +- Use Blazor Components appropriately for component-based UI development. |
| 12 | +- Prefer inline functions for smaller components but separate complex logic into code-behind or service classes. |
| 13 | +- Async/await should be used where applicable to ensure non-blocking UI operations. |
| 14 | + |
| 15 | + |
| 16 | +## Naming Conventions |
| 17 | + |
| 18 | +- Follow PascalCase for component names, method names, and public members. |
| 19 | +- Use camelCase for private fields and local variables. |
| 20 | +- Prefix interface names with "I" (e.g., IUserService). |
| 21 | + |
| 22 | +## Blazor and .NET Specific Guidelines |
| 23 | + |
| 24 | +- Utilize Blazor's built-in features for component lifecycle (e.g., OnInitializedAsync, OnParametersSetAsync). |
| 25 | +- Use data binding effectively with @bind. |
| 26 | +- Leverage Dependency Injection for services in Blazor. |
| 27 | +- Structure Blazor components and services following Separation of Concerns. |
| 28 | +- Always use the latest version C#, currently C# 13 features like record types, pattern matching, and global usings. |
| 29 | + |
| 30 | +## Oqtane specific Guidelines |
| 31 | + |
| 32 | +- Follow client server patterns for module development. |
| 33 | +- The Client project has various modules in the modules folder. |
| 34 | +- Each action in the client module is a seperate razor file that inherits from ModuleBase with index.razor being the default action. |
| 35 | +- For complex client processing like getting data, create a service class that inherits from ServiceBase and lives in the services folder. One service class for each module. |
| 36 | +- Client service should call server endpoint using ServiceBase methods |
| 37 | +- Server project contains MVC Controllers, one for each module that match the client service calls. Each controller will call server-side services or repositories managed by DI |
| 38 | +- Server projects use repository patterns for modules, one repository class per module to match the controllers. |
| 39 | + |
| 40 | +## Error Handling and Validation |
| 41 | + |
| 42 | +- Implement proper error handling for Blazor pages and API calls. |
| 43 | +- Use built-in Oqtane logging methods from base classes. |
| 44 | +- Use logging for error tracking in the backend and consider capturing UI-level errors in Blazor with tools like ErrorBoundary. |
| 45 | +- Implement validation using FluentValidation or DataAnnotations in forms. |
| 46 | + |
| 47 | +## Blazor API and Performance Optimization |
| 48 | + |
| 49 | +- Utilize Blazor server-side or WebAssembly optimally based on the project requirements. |
| 50 | +- Use asynchronous methods (async/await) for API calls or UI actions that could block the main thread. |
| 51 | +- Optimize Razor components by reducing unnecessary renders and using StateHasChanged() efficiently. |
| 52 | +- Minimize the component render tree by avoiding re-renders unless necessary, using ShouldRender() where appropriate. |
| 53 | +- Use EventCallbacks for handling user interactions efficiently, passing only minimal data when triggering events. |
| 54 | + |
| 55 | +## Caching Strategies |
| 56 | + |
| 57 | +- Implement in-memory caching for frequently used data, especially for Blazor Server apps. Use IMemoryCache for lightweight caching solutions. |
| 58 | +- For Blazor WebAssembly, utilize localStorage or sessionStorage to cache application state between user sessions. |
| 59 | +- Consider Distributed Cache strategies (like Redis or SQL Server Cache) for larger applications that need shared state across multiple users or clients. |
| 60 | +- Cache API calls by storing responses to avoid redundant calls when data is unlikely to change, thus improving the user experience. |
| 61 | + |
| 62 | +## State Management Libraries |
| 63 | + |
| 64 | +- Use Blazor's built-in Cascading Parameters and EventCallbacks for basic state sharing across components. |
| 65 | +- use built-in Oqtane state management in the base classes like PageState and SiteState when appropriate. |
| 66 | +- Avoid adding extra depenencies like Fluxor or BlazorState when the application grows in complexity. |
| 67 | +- For client-side state persistence in Blazor WebAssembly, consider using Blazored.LocalStorage or Blazored.SessionStorage to maintain state between page reloads. |
| 68 | +- For server-side Blazor, use Scoped Services and the StateContainer pattern to manage state within user sessions while minimizing re-renders. |
| 69 | + |
| 70 | +## API Design and Integration |
| 71 | + |
| 72 | +- Use service base methods to communicate with external APIs or server project backend. |
| 73 | +- Implement error handling for API calls using try-catch and provide proper user feedback in the UI. |
| 74 | + |
| 75 | +## Testing and Debugging in Visual Studio |
| 76 | + |
| 77 | +- All unit testing and integration testing should be done in Visual Studio Enterprise. |
| 78 | +- Test Blazor components and services using xUnit, NUnit, or MSTest. |
| 79 | +- Use Moq or NSubstitute for mocking dependencies during tests. |
| 80 | +- Debug Blazor UI issues using browser developer tools and Visual Studio's debugging tools for backend and server-side issues. |
| 81 | +- For performance profiling and optimization, rely on Visual Studio's diagnostics tools. |
| 82 | + |
| 83 | +## Security and Authentication |
| 84 | + |
| 85 | +- Implement Authentication and Authorization using built-in Oqtane base class members like User.Roles. |
| 86 | +- Use HTTPS for all web communication and ensure proper CORS policies are implemented. |
0 commit comments