Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 2236c0c

Browse files
Update README.md
1 parent 65e1c9e commit 2236c0c

File tree

1 file changed

+346
-0
lines changed

1 file changed

+346
-0
lines changed

‎README.md

Lines changed: 346 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,349 @@ It will include;
2323
* Event Sourcing
2424
* Implementation of MediatR, Autofac, FluentValidator, AutoMapper
2525
* swagger
26+
27+
28+
# What is AspnetRun ?
29+
A **starter kit** for your next **ASP.NET Core** web application. Boilerplate for **ASP.NET Core reference application** with **Entity Framework Core**, demonstrating a layered application architecture with DDD best practices. Implements NLayer **Hexagonal architecture** (Core, Application, Infrastructure and Presentation Layers) and **Domain Driven Design** (Entities, Repositories, Domain/Application Services, DTO's...)
30+
and aimed to be a **Clean Architecture**, with applying **SOLID principles** in order to use for a project template.
31+
Also implements **best practices** like **loosely-coupled, dependency-inverted** architecture and using **design patterns** such as **Dependency Injection**, logging, validation, exception handling, localization and so on.
32+
33+
You can check full repository documentations and step by step development of **[100+ page eBook PDF](http://www.aspnetrun.com/Book)** from here - **http://www.aspnetrun.com/Book**. Also detail introduction of book and project structure exists on **[50+ page of github wiki](https://github.com/aspnetrun/run-core/wiki)**.
34+
35+
# AspnetRun Repositories
36+
There are **2 types** of aspnetrun repositories;
37+
* **[run-aspnetcore](https://github.com/aspnetrun/run-aspnetcore)** - intented to building traditional Multi-Page Web Applications(MPA) using ASP.NET Core & EF.Core and **Razor Pages** templates with default aspnet core server-side rendering approach. **YOU ARE HERE.**
38+
* **[run-angular](https://github.com/aspnetrun/run-angular)** - intented to building Single-Page Web Applications(SPA) using ASP.NET Core & EF.Core, Web API Project and **Angular** for frontend framework.
39+
40+
And there are 2 sample repositories which are implemented base repository and **applying real-world examples** with developing new features for example Identity, Localization etc..
41+
* **[run-aspnetcore-realworld](https://github.com/aspnetrun/run-aspnetcore-realworld)** - implemented this repository and build **sample of eCommerce reference application** on Multi-Page Web Applications(MPA) using ASP.NET Core Razor Pages templates.
42+
* **[run-angular-realworld](https://github.com/aspnetrun/run-angular-realworld)** - implemented run-angular repository and build **sample of eCommerce reference application** on Single Page Web Application(SPA) architecture using **ASP.NET Core + Angular**.
43+
44+
# run-aspnetcore
45+
Here is CRUD operations of aspnetrun-core template project;
46+
47+
![Recordit GIF](http://g.recordit.co/LJCyYfQEpX.gif)
48+
49+
**run-aspnetcore** is a general purpose to implement the **Default Web Application template of .Net** with **layered architecture** for building modern web applications with latest ASP.NET Core & Web API & EF Core technologies. These repositories is **updated regularly**. So one of the new approach of Microsoft is SPA with only Asp.Net Core framework without any frontend framework. This is **[Blazor](https://blazor.net/)** and it will be avaible soon, so we have another repository for implementing **Single Page Web Applcation over the Web Assembly** with using **Blazor** as below;
50+
* **[run-aspnetcore-spa](https://github.com/aspnetrun/run-aspnetcore-spa)** - intented to building Single-Page Web Applications(SPA) using only ASP.NET Core **without any frontend framework**.This comes with **Blazor** framework from Microsoft which basically using **Razor Components** templates.
51+
52+
We are following Microsoft Web Technologies very closely so we will update all these repositories accordingly with **Microsoft Web Application stacks**.
53+
54+
## Give a Star! :star:
55+
If you liked the project or if AspnetRun helped you, please **give a star**. And also please **fork** this repository and send us **pull-requests**. If you find any problem please open **issue**.
56+
57+
## Getting Started
58+
Use these instructions to get the project up and running.
59+
60+
### Prerequisites
61+
You will need the following tools:
62+
63+
* [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/)
64+
* [.Net Core 2.2 or later](https://dotnet.microsoft.com/download/dotnet-core/2.2)
65+
* EF Core 2.2 or later
66+
67+
### Installing
68+
Follow these steps to get your development environment set up:
69+
1. Clone the repository
70+
2. At the root directory, restore required packages by running:
71+
```csharp
72+
dotnet restore
73+
```
74+
3. Next, build the solution by running:
75+
```csharp
76+
dotnet build
77+
```
78+
4. Next, within the AspnetRun.Web directory, launch the back end by running:
79+
```csharp
80+
dotnet run
81+
```
82+
5. Launch http://localhost:5400/ in your browser to view the Web UI.
83+
84+
If you have **Visual Studio** after cloning Open solution with your IDE, AspnetRun.Web should be the start-up project. Directly run this project on Visual Studio with **F5 or Ctrl+F5**. You will see index page of project, you can navigate product and category pages and you can perform crud operations on your browser.
85+
86+
### Usage
87+
After cloning or downloading the sample you should be able to run it using an In Memory database immediately. The default configuration of Entity Framework Database is **"InMemoryDatabase"**.
88+
If you wish to use the project with a persistent database, you will need to run its Entity Framework Core **migrations** before you will be able to run the app, and update the ConfigureDatabases method in **Startup.cs** (see below).
89+
90+
```csharp
91+
public void ConfigureDatabases(IServiceCollection services)
92+
{
93+
// use in-memory database
94+
services.AddDbContext<AspnetRunContext>(c =>
95+
c.UseInMemoryDatabase("AspnetRunConnection")
96+
.UseQueryTrackingBehavior(QueryTrackingBehavior.NoTracking));
97+
98+
//// use real database
99+
//services.AddDbContext<AspnetRunContext>(c =>
100+
// c.UseSqlServer(Configuration.GetConnectionString("AspnetRunConnection"))
101+
// .UseQueryTrackingBehavior(QueryTrackingBehavior.NoTracking));
102+
}
103+
```
104+
105+
1. Ensure your connection strings in ```appsettings.json``` point to a local SQL Server instance.
106+
107+
2. Open a command prompt in the Web folder and execute the following commands:
108+
109+
```csharp
110+
dotnet restore
111+
dotnet ef database update -c AspnetRunContext -p ../AspnetRun.Infrastructure/AspnetRun.Infrastructure.csproj -s AspnetRun.Web.csproj
112+
```
113+
Or you can direct call ef commands from Visual Studio **Package Manager Console**. Open Package Manager Console, set default project to AspnetRun.Infrastructure and run below command;
114+
```csharp
115+
update-database
116+
```
117+
These commands will create aspnetrun database which include Product and Category table. You can see from **AspnetRunContext.cs**.
118+
1. Run the application.
119+
The first time you run the application, it will seed aspnetrun sql server database with a few data such that you should see products and categories.
120+
121+
If you modify-change or add new some of entities to Core project, you should run ef migrate commands in order to update your database as the same way but below commands;
122+
```csharp
123+
add migration YourCustomEntityChanges
124+
update-database
125+
```
126+
127+
## Layered Architecture
128+
AspnetRun implements NLayer **Hexagonal architecture** (Core, Application, Infrastructure and Presentation Layers) and **Domain Driven Design** (Entities, Repositories, Domain/Application Services, DTO's...). Also implements and provides a good infrastructure to implement **best practices** such as Dependency Injection, logging, validation, exception handling, localization and so on.
129+
Aimed to be a **Clean Architecture** also called **Onion Architecture**, with applying **SOLID principles** in order to use for a project template. Also implements and provides a good infrastructure to implement **best practices** like **loosely-coupled, dependency-inverted** architecture
130+
The below image represents aspnetrun approach of development architecture of run repository series;
131+
132+
![DDD_png_pure](https://user-images.githubusercontent.com/1147445/54773098-e1efe700-4c19-11e9-9150-74f7e770de42.png)
133+
134+
### Structure of Project
135+
Repository include layers divided by **4 project**;
136+
* Core
137+
* Entities
138+
* Interfaces
139+
* Specifications
140+
* ValueObjects
141+
* Exceptions
142+
* Application
143+
* Interfaces
144+
* Services
145+
* Dtos
146+
* Mapper
147+
* Exceptions
148+
* Infrastructure
149+
* Data
150+
* Repository
151+
* Services
152+
* Migrations
153+
* Logging
154+
* Exceptions
155+
* Web
156+
* Interfaces
157+
* Services
158+
* Pages
159+
* ViewModels
160+
* Extensions
161+
* Mapper
162+
163+
### Core Layer
164+
Development of Domain Logic with abstraction. Interfaces drives business requirements with light implementation. The Core project is the **center of the Clean Architecture** design, and all other project dependencies should point toward it.
165+
166+
#### Entities
167+
Includes Entity Framework Core Entities which creates sql table with **Entity Framework Core Code First Aproach**. Some Aggregate folders holds entity and aggregates.
168+
You can see example of **code-first** Entity definition as below;
169+
170+
```csharp
171+
public class Product : BaseEntity
172+
{
173+
public string ProductName { get; set; }
174+
public string QuantityPerUnit { get; set; }
175+
public decimal? UnitPrice { get; set; }
176+
public short? UnitsInStock { get; set; }
177+
public short? UnitsOnOrder { get; set; }
178+
public short? ReorderLevel { get; set; }
179+
public bool Discontinued { get; set; }
180+
public int CategoryId { get; set; }
181+
public Category Category { get; set; }
182+
183+
public static Product Create(int productId, int categoryId, string name, decimal? unitPrice = null, short? unitsInStock = null, short? unitsOnOrder = null, short? reorderLevel = null, bool discontinued = false)
184+
{
185+
var product = new Product
186+
{
187+
Id = productId,
188+
CategoryId = categoryId,
189+
ProductName = name,
190+
UnitPrice = unitPrice,
191+
UnitsInStock = unitsInStock,
192+
UnitsOnOrder = unitsOnOrder,
193+
ReorderLevel = reorderLevel,
194+
Discontinued = discontinued
195+
};
196+
return product;
197+
}
198+
}
199+
```
200+
Applying domain driven approach, Product class responsible to create Product instance.
201+
202+
#### Interfaces
203+
Abstraction of Repository - Domain repositories (IAsyncRepository - IProductRepository) - Specifications etc.. This interfaces include database operations without any application and ui responsibilities.
204+
205+
#### Specifications
206+
This folder is implementation of **[specification pattern](https://en.wikipedia.org/wiki/Specification_pattern)**. Creates custom scripts with using **ISpecification** interface. Using BaseSpecification managing Criteria, Includes, OrderBy, Paging.
207+
This specs runs when EF commands working with passing spec. This specs implemented SpecificationEvaluator.cs and creates query to AspnetRunRepository.cs in ApplySpecification method.This helps create custom queries.
208+
209+
### Infrastructure Layer
210+
Implementation of Core interfaces in this project with **Entity Framework Core** and other dependencies.
211+
Most of your application's dependence on external resources should be implemented in classes defined in the Infrastructure project. These classes must implement the interfaces defined in Core. If you have a very large project with many dependencies, it may make sense to have more than one Infrastructure project (eg Infrastructure.Data), but in most projects one Infrastructure project that contains folders works well.
212+
This could be includes, for example, **e-mail providers, file access, web api clients**, etc. For now this repository only dependend sample data access and basic domain actions, by this way there will be no direct links to your Core or UI projects.
213+
214+
#### Data
215+
Includes **Entity Framework Core Context** and tables in this folder. When new entity created, it should add to context and configure in context.
216+
The Infrastructure project depends on Microsoft.**EntityFrameworkCore.SqlServer** and EF.Core related nuget packages, you can check nuget packages of Infrastructure layer. If you want to change your data access layer, it can easily be replaced with a lighter-weight ORM like Dapper.
217+
218+
#### Migrations
219+
EF add-migration classes.
220+
#### Repository
221+
EF Repository and Specification implementation. This class responsible to create queries, includes, where conditions etc..
222+
#### Services
223+
Custom services implementation, like email, cron jobs etc.
224+
225+
### Application Layer
226+
Development of **Domain Logic with implementation**. Interfaces drives business requirements and implementations in this layer.
227+
Application layer defines that user required actions in app services classes as below way;
228+
229+
```csharp
230+
public interface IProductAppService
231+
{
232+
Task<IEnumerable<ProductDto>> GetProductList();
233+
Task<ProductDto> GetProductById(int productId);
234+
Task<IEnumerable<ProductDto>> GetProductByName(string productName);
235+
Task<IEnumerable<ProductDto>> GetProductByCategory(int categoryId);
236+
Task<ProductDto> Create(ProductDto entityDto);
237+
Task Update(ProductDto entityDto);
238+
Task Delete(ProductDto entityDto);
239+
}
240+
```
241+
Also implementation located same places in order to choose different implementation at runtime when DI bootstrapped.
242+
```csharp
243+
public class ProductAppService : IProductAppService
244+
{
245+
private readonly IProductRepository _productRepository;
246+
private readonly IAppLogger<ProductAppService> _logger;
247+
248+
public ProductAppService(IProductRepository productRepository, IAppLogger<ProductAppService> logger)
249+
{
250+
_productRepository = productRepository ?? throw new ArgumentNullException(nameof(productRepository));
251+
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
252+
}
253+
254+
public async Task<IEnumerable<ProductDto>> GetProductList()
255+
{
256+
var productList = await _productRepository.GetProductListAsync();
257+
var mapped = ObjectMapper.Mapper.Map<IEnumerable<ProductDto>>(productList);
258+
return mapped;
259+
}
260+
}
261+
```
262+
In this layer we can add validation , authorization, logging, exception handling etc. -- cross cutting activities should be handled in here.
263+
264+
### Web Layer
265+
Development of UI Logic with implementation. Interfaces drives business requirements and implementations in this layer.
266+
The application's main **starting point** is the ASP.NET Core web project. This is a classical console application, with a public static void Main method in Program.cs. It currently uses the default **ASP.NET Core project template** which based on **Razor Pages** templates. This includes appsettings.json file plus environment variables in order to stored configuration parameters, and is configured in Startup.cs.
267+
268+
Web layer defines that user required actions in page services classes as below way;
269+
```csharp
270+
public interface IProductPageService
271+
{
272+
Task<IEnumerable<ProductViewModel>> GetProducts(string productName);
273+
Task<ProductViewModel> GetProductById(int productId);
274+
Task<IEnumerable<ProductViewModel>> GetProductByCategory(int categoryId);
275+
Task<IEnumerable<CategoryViewModel>> GetCategories();
276+
Task<ProductViewModel> CreateProduct(ProductViewModel productViewModel);
277+
Task UpdateProduct(ProductViewModel productViewModel);
278+
Task DeleteProduct(ProductViewModel productViewModel);
279+
}
280+
```
281+
Also implementation located same places in order to choose different implementation at runtime when DI bootstrapped.
282+
```csharp
283+
public class ProductPageService : IProductPageService
284+
{
285+
private readonly IProductAppService _productAppService;
286+
private readonly ICategoryAppService _categoryAppService;
287+
private readonly IMapper _mapper;
288+
private readonly ILogger<ProductPageService> _logger;
289+
290+
public ProductPageService(IProductAppService productAppService, ICategoryAppService categoryAppService, IMapper mapper, ILogger<ProductPageService> logger)
291+
{
292+
_productAppService = productAppService ?? throw new ArgumentNullException(nameof(productAppService));
293+
_categoryAppService = categoryAppService ?? throw new ArgumentNullException(nameof(categoryAppService));
294+
_mapper = mapper ?? throw new ArgumentNullException(nameof(mapper));
295+
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
296+
}
297+
298+
public async Task<IEnumerable<ProductViewModel>> GetProducts(string productName)
299+
{
300+
if (string.IsNullOrWhiteSpace(productName))
301+
{
302+
var list = await _productAppService.GetProductList();
303+
var mapped = _mapper.Map<IEnumerable<ProductViewModel>>(list);
304+
return mapped;
305+
}
306+
307+
var listByName = await _productAppService.GetProductByName(productName);
308+
var mappedByName = _mapper.Map<IEnumerable<ProductViewModel>>(listByName);
309+
return mappedByName;
310+
}
311+
}
312+
```
313+
### Test Layer
314+
For each layer, there is a test project which includes intended layer dependencies and mock classes. So that means Core-Application-Infrastructure and Web layer has their own test layer. By this way this test projects also divided by **unit, functional and integration tests** defined by in which layer it is implemented.
315+
Test projects using **xunit and Mock libraries**. xunit, because that's what ASP.NET Core uses internally to test the product. Moq, because perform to create fake objects clearly and its very modular.
316+
317+
318+
## Technologies
319+
* .NET Core 2.2
320+
* ASP.NET Core 2.2
321+
* Entity Framework Core 2.2
322+
* .NET Core Native DI
323+
* Razor Pages
324+
* AutoMapper
325+
326+
## Architecture
327+
* Clean Architecture
328+
* Full architecture with responsibility separation of concerns
329+
* SOLID and Clean Code
330+
* Domain Driven Design (Layers and Domain Model Pattern)
331+
* Unit of Work
332+
* Repository and Generic Repository
333+
* Multiple Page Web Application (MPA)
334+
* Monolitic Deployment Architecture
335+
* Specification Pattern
336+
337+
## Disclaimer
338+
339+
* This repository is not intended to be a definitive solution.
340+
* This repository not implemented a lot of 3rd party packages, we are try to avoid the over engineering when building on best practices.
341+
* Beware to use in production way.
342+
343+
## Contributing
344+
345+
Please read [Contributing.md](https://gist.github.com/PurpleBooth/b24679402957c63ec426) for details on our code of conduct, and the process for submitting pull requests to us.
346+
347+
## Versioning
348+
349+
We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/aspnetrun/run-core/tags).
350+
351+
## Next Releases and RoapMap
352+
353+
For information on upcoming features and fixes, take a look at the [product roadmap](https://github.com/aspnetrun/run-core/projects).
354+
355+
## Deployment - AspnetRun Online
356+
357+
This project is deployed on Azure. See the project running on Azure in [here](aspnetrun.com).
358+
359+
## Pull-Request
360+
361+
Please fork this repository, and send me your findings with pull-requests. This is open-source repository so open to contributions.
362+
363+
## Authors
364+
365+
* **Mehmet Ozkaya** - *Initial work* - [mehmetozkaya](https://github.com/mehmetozkaya)
366+
367+
See also the list of [contributors](https://github.com/aspnetrun/run-core/contributors) who participated in this project.
368+
369+
## License
370+
371+
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /