From eef03c152d38b582dc009bb6cbf386f7779ea25a Mon Sep 17 00:00:00 2001 From: Leon Hoppe Date: Thu, 21 Nov 2024 16:55:56 +0100 Subject: [PATCH] finished documentation for installation, database usage and authentication --- docs/Authentication.md | 42 +++++++++++++++++++++++++++++++++++ docs/README.md | 6 ++--- docs/installation/Blazor.md | 37 ++++++++++++++++++++++++++++++ docs/installation/Database.md | 37 ++++++++++++++++++++++++++++++ docs/installation/README.md | 2 ++ docs/installation/WebAPI.md | 17 ++++++++++++++ 6 files changed, 138 insertions(+), 3 deletions(-) create mode 100644 docs/Authentication.md create mode 100644 docs/installation/Blazor.md create mode 100644 docs/installation/Database.md create mode 100644 docs/installation/README.md create mode 100644 docs/installation/WebAPI.md diff --git a/docs/Authentication.md b/docs/Authentication.md new file mode 100644 index 0000000..4f03292 --- /dev/null +++ b/docs/Authentication.md @@ -0,0 +1,42 @@ +# HopFrame Authentication + +With the provided HopFrame services, you can secure your endpoints and blazor pages so that only logged-in users or users with the right permissions can access the endpoint/page + +## Usage +### Secure your endpoints +You can secure your endpoints by adding the `Authorized` attribute. + +```csharp +// Everyone can access this endpoint +[HttpGet("hello")] +public ActionResult HelloWorld() { + return "Hello, World!"; +} + +// Only logged-in users can access this endpoint +[HttpGet("hello"), Authorized] +public ActionResult HelloWorld() { + return "Hello, World!"; +} + +// Only logged-in users with the specified permissions can access this endpoint +[HttpGet("hello"), Authorized("test.permission", "test.permission.another")] +public ActionResult HelloWorld() { + return "Hello, World!"; +} +``` + +### Secure your Blazor pages +You can secure your Blazor pages by using the `AuthorizedView` component. +Everything placed inside this component will only be displayed if the authorization was successful. +You can also redirect the user if the authorization fails by specifying a `RedirectIfUnauthorized` url. + +```htmlinblazor + + +

This paragraph is only visible if the user is logged-in and has the required permission

+ + + + +``` diff --git a/docs/README.md b/docs/README.md index 582a4f0..98a41ca 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,9 @@ # HopFrame Documentation - [x] In code documentation -- [ ] Installation -- [ ] Database usage -- [ ] Authentication usage +- [x] Installation +- [x] Database usage +- [x] Authentication usage - [ ] LogicResult usage - [ ] Repositories usage - [ ] AuthService usage diff --git a/docs/installation/Blazor.md b/docs/installation/Blazor.md new file mode 100644 index 0000000..abbe172 --- /dev/null +++ b/docs/installation/Blazor.md @@ -0,0 +1,37 @@ +## How to use the Blazor API +This Installation adds all HopFrame [pages](../pages) and [services](../services) to the application. + +1. Add the HopFrame.Web library to your project + + ``` + dotnet add package HopFrame.Web + ``` + +2. Create a [DbContext](./Database.md) that inherits the ``HopDbContext`` and add a data source +

 

+ +3. Add the HopFrame services to your application, provide the previously created `DatabaseContext` that inherits from `HopDbContextBase` + + ```csharp + builder.Services.AddHopFrame(); + ``` + +4. **Optional:** You can also add your [AdminContext](../admin) + + ```csharp + builder.Services.AddAdminContext(); + ``` + +5. Add the authentication middleware to your app + + ```csharp + app.UseMiddleware(); + ``` + +6. Add the HopFrame pages to your Razor components + + ```csharp + app.MapRazorComponents() + .AddHopFrameAdminPages() + .AddInteractiveServerRenderMode(); + ``` diff --git a/docs/installation/Database.md b/docs/installation/Database.md new file mode 100644 index 0000000..2ebef13 --- /dev/null +++ b/docs/installation/Database.md @@ -0,0 +1,37 @@ +# Database initialization +You also need to initialize the data source with the tables from HopFrame + +## Create a DbContext + +1. Create a c# class that inherits from the `HopDbContextBase` and add a data source (In the example Sqlite is used) + + ```csharp + public class DatabaseContext : HopDbContextBase { + protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) { + base.OnConfiguring(optionsBuilder); + + optionsBuilder.UseSqlite("..."); + } + } + ``` + + **IMPORTANT:** You need to leave the `base.OnConfiguring(optionsBuilder)` in place so the HopFrame model relations are set correctly. +

 

+ +2. Register the `DatabaseContext` as a service + + ```csharp + builder.Services.AddDbContext(); + ``` + +3. Create a database migration + + ```bash + dotnet ef migrations add Initial + ``` + +4. Apply the migration to the data source + + ```bash + dotnet ef database update + ``` diff --git a/docs/installation/README.md b/docs/installation/README.md new file mode 100644 index 0000000..0f3cda1 --- /dev/null +++ b/docs/installation/README.md @@ -0,0 +1,2 @@ +# HopFrame Usage +There are two different versions of HopFrame, either the [Web API](./WebAPI.md) version or the full [Blazor web version](./Blazor.md). diff --git a/docs/installation/WebAPI.md b/docs/installation/WebAPI.md new file mode 100644 index 0000000..6166db0 --- /dev/null +++ b/docs/installation/WebAPI.md @@ -0,0 +1,17 @@ +# Ho to use the Web API version +This Installation adds all HopFrame [endpoints](../endpoints) and [services](../services) to the application. + +1. Add the HopFrame.Api library to your project: + + ``` + dotnet add package HopFrame.Api + ``` + +2. Create a [DbContext](./Database.md) that inherits the ``HopDbContext`` and add a data source +

 

+ +3. Add the HopFrame services to your application, provide the previously created `DatabaseContext` that inherits from `HopDbContextBase` + + ```csharp + builder.Services.AddHopFrame(); + ```