From 5f0f0d8dbc946fab00e54e80319d96978598d596 Mon Sep 17 00:00:00 2001 From: Israel Date: Tue, 29 Aug 2017 11:58:39 -0500 Subject: [PATCH] Updated documentation using cases --- README.md | 123 +++++++++++++++++------------------------------------- 1 file changed, 39 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index f586e79..ab9717f 100644 --- a/README.md +++ b/README.md @@ -2,16 +2,11 @@ [![Build status](https://ci.appveyor.com/api/projects/status/q408tg5jd9bm0jak/branch/master?svg=true)](https://ci.appveyor.com/project/geoperez/swan-aspnetcore/branch/master) [![Coverage Status](https://coveralls.io/repos/github/unosquare/swan-aspnetcore/badge.svg?branch=master)](https://coveralls.io/github/unosquare/swan-aspnetcore?branch=master) -# SWAN: Stuff We All Need - *:star: Please star this project if you find it useful!* -SWAN stands for Stuff We All Need +# Swan ASP.NET Core 2 -Repeating code and reinventing the wheel is generally considered bad practice. At Unosquare we are committed to beautiful code and great software. -Swan is a collection of classes and extension methods that we and other good developers have developed and evolved over the years. We found ourselves copying and pasting -the same code for every project every time we started it. We decide to kill that cycle once and for all. This is the result of that idea. -Our philosophy is that SWAN should have no external dependencies, it should be cross-platform, and it should be useful. +A set of libraries to use with ASP.NET Core 2.0 applications. Also, includes a configure middleware and extension to setup your project. ASP.NET Core 2.0 came with a lot of changes, including authentication and authorization, here with Swan ASP.NET Core 2.0 is easy to configure and start working on your project. NuGet Installation: ------------------- @@ -22,94 +17,31 @@ NuGet Installation: PM> Install-Package Unosquare.Swan.AspNetCore ``` -# Swan ASP.NET Core 2 - -A set of libraries to use with Net Core 2 applications. Also, includes a configure middleware and extension to setup your project. Net core 2 came with a lot of changes, including authentication and authorization, here with Swan Asp Net Core 2 is easy to configure and start working on your project. - -## The `Extension` class +## Use Cases Here we can find very useful code to use in our project configuration. All of this you can use it in your Startup.cs file, see our [Sample Project](https://github.com/unosquare/swan-aspnetcore/tree/master/src/Unosquare.Swan.AspNetCore.Sample) for more reference. -#### Example 0: Validation Parameters +### Case 1: Add BearerTokenAuthentication and Use BearerTokenAuthentication -It's use to verify the parameters of the authentication. Is use in the `UseBearerTokenAuthentication` and `AddBearerTokenAuthentication` +Add BearerTokenAuthentication this only adds services to your project. -```csharp -ValidationParameters = new TokenValidationParameters() -{ - ValidateIssuerSigningKey = true, - // You can modify this key in the appsettings.json - IssuerSigningKey = new SymmetricSecurityKey(Encoding.ASCII.GetBytes(Configuration["SymmetricSecurityKey"])), +Use BearerTokenAuthentication is important because it gives the application the requirements to use authentication and authorization with JWT (JSON Web tokens). - ValidateIssuer = true, - ValidIssuer = "ValidIssuer", +With this configuration, you just need to add the data annotation [Authorize] to your API to say that the user needs to be authorized to access that part of your project. - ValidateAudience = true, - ValidAudience = "ValidAudience", - - ValidateLifetime = true, - - ClockSkew = TimeSpan.Zero -}; -``` -### In your `ConfigureServices` method - -In this method, you can configure the services of your application. +This two are used together because you need to add the bearer token authentication to the services to use the bearer token authentication. You just need to added in your `ConfigureServices` and your `Configure`. ```csharp // This method gets called by the runtime. Use this method to add services to the container public void ConfigureServices(IServiceCollection services) { - ... -} -``` - -#### Example 1: The `AddBearerTokenAuthentication` - -This is required to use the Authentication that comes with core 2 applications. - -```csharp // Extension method to add Bearer authentication services.AddBearerTokenAuthentication(ValidationParameters); -``` - -### In your `Configure` method - -Here is where you configure your app - -```csharp - // This method gets called by the runtime. Use this method to configure the HTTP request pipeline -public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory) -{ - ... } -``` - -#### Example 1: The `AddEntityFramework` - -Adds an entity framework logger. This logger is used in the `Configure` method of your Startup.cs file. - -```csharp -// you need to declare as parameter of type ILoggerFactory -loggerFactory.AddEntityFramework(app.ApplicationServices); -``` - -#### Example 2: The `UseJsonExceptionHandler` - -Is very useful to see exceptions in JSON format. -```csharp -// Response an exception as JSON at error -app.UseJsonExceptionHandler(); -``` - -#### Example 3: The `UseBearerTokenAuthentication` - -This is important because it gives the application to use authentication and authorization with JWT (JSON Web tokens). See Example 0 for the ValidationParameters. - -With this configuration you just need to add the data annotation [Authorize] to your API to say that the user needs to be authorized to access that part of your project. - -```csharp +// This method gets called by the runtime. Use this method to configure the HTTP request pipeline +public void Configure(IApplicationBuilder app) +{ // Use the bearer token provider and check Admin and Pass.word as valid credentials app.UseBearerTokenAuthentication( ValidationParameters, @@ -128,21 +60,44 @@ app.UseBearerTokenAuthentication( obj["test"] = "OK"; return Task.FromResult(obj); }); +} ``` -#### Example 4: The `UseFallback` +### Case 2: EntityFrameworkLogger -Uses the fallback to redirect everything without extension. +Represents a Logger using EntityFramework + +#### Example 1: AddEntityFramework + +Adds an entity framework logger. This logger is used in the `Configure` method of your Startup.cs file. ```csharp -// Redirect anything without extension to index.html -app.UseFallback(); +// you need to declare as parameter of type ILoggerFactory +loggerFactory.AddEntityFramework(app.ApplicationServices); ``` -#### Example 5: The `UseAuditTrail` +### Case 3: AuditTrail This is an extension method to add AuditTrail to a DbContext. ```csharp // TODO: Example +``` + +### Case 4: UseJsonExceptionHandler + +It's very useful to see exceptions in JSON format. + +```csharp +// Response an exception as JSON at error +app.UseJsonExceptionHandler(); +``` + +### Case 5: UseFallback + +Uses the fallback to redirect everything without extension. + +```csharp +// Redirect anything without extension to index.html +app.UseFallback(); ``` \ No newline at end of file