mirror of https://github.com/abpframework/abp.git
SALİH ÖZKARA
3 months ago
20 changed files with 545 additions and 160 deletions
@ -0,0 +1,287 @@ |
|||||
|
```json |
||||
|
//[doc-seo] |
||||
|
{ |
||||
|
"Description": "Connect ABP Low-Code entities with regular C# code. Register reference entities for low-code lookups and access low-code entities from application code via typed repositories, DynamicEntity, or IDynamicPageAppService." |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
# Code Integration |
||||
|
|
||||
|
> **Preview:** Low-Code integration APIs are part of the preview Low-Code System. Registration details, repository behavior, and page service contracts may change before general availability. |
||||
|
|
||||
|
Use the [Low-Code Designer](designer.md) and [React Runtime](react-runtime.md) for standard CRUD screens. This page covers the integration points for the cases where low-code models and regular application code need to reach each other directly. |
||||
|
|
||||
|
## Choose the Right Integration Path |
||||
|
|
||||
|
| Need | Recommended approach | |
||||
|
|------|----------------------| |
||||
|
| A low-code field should point to an existing C# entity such as `IdentityUser` | Register a [reference entity](reference-entities.md) and use its CLR full name in the foreign key definition | |
||||
|
| Application code should work with a low-code entity that has a real C# class | Inject `IRepository<TEntity, Guid>` for that `[DynamicEntity]` class | |
||||
|
| Application code should work with a descriptor-only or runtime-defined low-code entity | Inject `IRepository<DynamicEntity, Guid>` and call `SetEntityName(...)` | |
||||
|
| Application code should reuse runtime page behavior such as low-code permissions, foreign-access checks, files, attachments, or child-page rules | Inject `IDynamicPageAppService` and work by `pageName` | |
||||
|
|
||||
|
## Low-Code to Existing C# Entities |
||||
|
|
||||
|
Low-code entities can point to existing entities that are not managed by the Low-Code System itself. Register them once during startup: |
||||
|
|
||||
|
````csharp |
||||
|
AbpDynamicEntityConfig.ReferencedEntityList.Add<IdentityUser>( |
||||
|
"UserName", |
||||
|
"UserName", |
||||
|
"Email" |
||||
|
); |
||||
|
```` |
||||
|
|
||||
|
Then use the registered CLR type name in a foreign key: |
||||
|
|
||||
|
````csharp |
||||
|
[DynamicForeignKey("Volo.Abp.Identity.IdentityUser", "UserName")] |
||||
|
public Guid? OwnerId { get; set; } |
||||
|
```` |
||||
|
|
||||
|
or in a descriptor file: |
||||
|
|
||||
|
```json |
||||
|
{ |
||||
|
"name": "OwnerId", |
||||
|
"foreignKey": { |
||||
|
"entityName": "Volo.Abp.Identity.IdentityUser" |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
Scripts can also query the same reference entity: |
||||
|
|
||||
|
```javascript |
||||
|
var user = await db.get('Volo.Abp.Identity.IdentityUser', ownerId); |
||||
|
``` |
||||
|
|
||||
|
Reference entities are read-only from the low-code side. For the full registration model and metadata details, see [Reference Entities](reference-entities.md). |
||||
|
|
||||
|
## C# Code to Low-Code Entities |
||||
|
|
||||
|
### Option 1: Typed Repository for Code-Defined Dynamic Entities |
||||
|
|
||||
|
If the low-code entity is declared as a normal C# class with `[DynamicEntity]` and `DynamicEntityBase`, use it like any other ABP entity. The low-code demo's `Customer` entity is a typical example: |
||||
|
|
||||
|
````csharp |
||||
|
public class CustomerSyncService : ITransientDependency |
||||
|
{ |
||||
|
private readonly IRepository<Customer, Guid> _customerRepository; |
||||
|
|
||||
|
public CustomerSyncService(IRepository<Customer, Guid> customerRepository) |
||||
|
{ |
||||
|
_customerRepository = customerRepository; |
||||
|
} |
||||
|
|
||||
|
public async Task UpdateAsync(Guid id) |
||||
|
{ |
||||
|
var customer = await _customerRepository.GetAsync(id); |
||||
|
|
||||
|
customer.SetData("Telephone", "5550001122"); |
||||
|
customer.SetData("CreditLimit", 119.99m); |
||||
|
|
||||
|
await _customerRepository.UpdateAsync(customer); |
||||
|
} |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
This is the simplest path when a CLR type already exists. `GetData(...)` and `SetData(...)` still work for dynamic or extra properties on that typed entity. |
||||
|
|
||||
|
### Option 2: Generic Repository for Descriptor-Only or Runtime-Defined Entities |
||||
|
|
||||
|
If the low-code entity only exists in descriptor files or runtime metadata, inject `IRepository<DynamicEntity, Guid>`. Set the entity name before repository operations: |
||||
|
|
||||
|
````csharp |
||||
|
public class ProductImportService : ITransientDependency |
||||
|
{ |
||||
|
private readonly IRepository<DynamicEntity, Guid> _dynamicEntityRepository; |
||||
|
|
||||
|
public ProductImportService(IRepository<DynamicEntity, Guid> dynamicEntityRepository) |
||||
|
{ |
||||
|
_dynamicEntityRepository = dynamicEntityRepository; |
||||
|
} |
||||
|
|
||||
|
public async Task<Guid> CreateAsync() |
||||
|
{ |
||||
|
_dynamicEntityRepository.SetEntityName("LowCodeDemo.Products.Product"); |
||||
|
|
||||
|
var product = new DynamicEntity("LowCodeDemo.Products.Product", Guid.NewGuid()) |
||||
|
{ |
||||
|
["Name"] = "Road Helmet", |
||||
|
Data = |
||||
|
{ |
||||
|
["Price"] = 125m, |
||||
|
["StockCount"] = 40 |
||||
|
} |
||||
|
}; |
||||
|
|
||||
|
await _dynamicEntityRepository.InsertAsync(product); |
||||
|
return product.Id; |
||||
|
} |
||||
|
|
||||
|
public async Task<decimal> GetPriceAsync(Guid id) |
||||
|
{ |
||||
|
_dynamicEntityRepository.SetEntityName("LowCodeDemo.Products.Product"); |
||||
|
|
||||
|
var product = await _dynamicEntityRepository.GetAsync(id); |
||||
|
return product.GetData<decimal>("Price"); |
||||
|
} |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
Call `SetEntityName(...)` again whenever you switch to another low-code entity name. After that, standard repository operations such as `GetAsync`, `GetListAsync`, `InsertAsync`, `UpdateAsync`, `DeleteAsync`, and `GetQueryableAsync` work normally. |
||||
|
|
||||
|
Use `GetData(...)` and `SetData(...)` for normal read/write code. Use the indexers only when you need to target the underlying storage explicitly, such as query expressions or manual `DynamicEntity` construction. |
||||
|
|
||||
|
| API | Use it for | |
||||
|
|-----|------------| |
||||
|
| `entity.GetData<T>("FieldName")` | General read API; it resolves CLR properties, mapped fields, and extra properties through one call | |
||||
|
| `entity.SetData("FieldName", value)` | General write API; it chooses the mapped field or `Data` dictionary automatically | |
||||
|
| `entity["FieldName"]` | Direct access to a dynamic property with `isMappedToDbField: true` | |
||||
|
| `entity.Data["FieldName"]` | Direct access to a dynamic property without `isMappedToDbField: true` | |
||||
|
|
||||
|
### Query Expressions: `entity["Field"]` vs `entity.Data["Field"]` |
||||
|
|
||||
|
For materialized entities, `GetData(...)` is the safest read API because it hides the storage details. For `IQueryable` expressions, use the access form that matches the property's storage shape so EF Core and the low-code query layer can translate it correctly: |
||||
|
|
||||
|
| Property shape | Query form | |
||||
|
|----------------|------------| |
||||
|
| Normal CLR property | `x.PropertyName` | |
||||
|
| Dynamic property with `isMappedToDbField: true` | `x["PropertyName"]` | |
||||
|
| Dynamic property without `isMappedToDbField: true` | `x.Data["PropertyName"]` | |
||||
|
|
||||
|
The low-code demo uses both patterns in the same query. In `LowCodeDemo.Orders.OrderLine`, `ProductId` is mapped to a DB field, while `Amount` stays in the `Data` dictionary: |
||||
|
|
||||
|
````csharp |
||||
|
var orderLineQuery = await _dynamicEntityRepository |
||||
|
.SetEntityName("LowCodeDemo.Orders.OrderLine") |
||||
|
.GetQueryableAsync(); |
||||
|
|
||||
|
var filtered = orderLineQuery |
||||
|
.Where(line => line.Data["Amount"] != null && (decimal?)line.Data["Amount"] > 1000m) |
||||
|
.Select(line => new |
||||
|
{ |
||||
|
ProductId = (Guid?)line["ProductId"], |
||||
|
Amount = (decimal?)line.Data["Amount"] |
||||
|
}); |
||||
|
```` |
||||
|
|
||||
|
The same rule applies to joins. `ProductId` is joined through the entity indexer because it is mapped, while `CustomerId` on `LowCodeDemo.Orders.Order` is joined through `Data` because it is not: |
||||
|
|
||||
|
````csharp |
||||
|
var orderLineQuery = await _dynamicEntityRepository |
||||
|
.SetEntityName("LowCodeDemo.Orders.OrderLine") |
||||
|
.GetQueryableAsync(); |
||||
|
|
||||
|
var orderQuery = await _dynamicEntityRepository |
||||
|
.SetEntityName("LowCodeDemo.Orders.Order") |
||||
|
.GetQueryableAsync(); |
||||
|
|
||||
|
var query = |
||||
|
from orderLine in orderLineQuery |
||||
|
join order in orderQuery |
||||
|
on (Guid?)orderLine["OrderId"] equals order.Id |
||||
|
select new |
||||
|
{ |
||||
|
OrderId = order.Id, |
||||
|
CustomerId = (Guid?)order.Data["CustomerId"], |
||||
|
Amount = (decimal?)orderLine.Data["Amount"] |
||||
|
}; |
||||
|
```` |
||||
|
|
||||
|
Use `GetData(...)` again after the query has been materialized into entity objects. |
||||
|
|
||||
|
### Option 3: `IDynamicPageAppService` for Runtime-Like Behavior |
||||
|
|
||||
|
Use `IDynamicPageAppService` when custom code should go through the same page-level behavior as the generated runtime: low-code permissions, foreign-access validation, lookup rules, file handling, attachments, export, and child records. |
||||
|
|
||||
|
This API works with `pageName`, not `entityName`: |
||||
|
|
||||
|
````csharp |
||||
|
public class ProductRuntimeService : ITransientDependency |
||||
|
{ |
||||
|
private readonly IDynamicPageAppService _dynamicPageAppService; |
||||
|
|
||||
|
public ProductRuntimeService(IDynamicPageAppService dynamicPageAppService) |
||||
|
{ |
||||
|
_dynamicPageAppService = dynamicPageAppService; |
||||
|
} |
||||
|
|
||||
|
public async Task<DynamicEntityDto> CreateAsync() |
||||
|
{ |
||||
|
return await _dynamicPageAppService.CreateAsync( |
||||
|
"products", |
||||
|
new DynamicEntityCreateInput |
||||
|
{ |
||||
|
Properties = new Dictionary<string, string?> |
||||
|
{ |
||||
|
["Name"] = "Road Helmet", |
||||
|
["Price"] = "125", |
||||
|
["StockCount"] = "40" |
||||
|
} |
||||
|
} |
||||
|
); |
||||
|
} |
||||
|
|
||||
|
public async Task<PagedResultDto<DynamicEntityDto>> GetListAsync() |
||||
|
{ |
||||
|
return await _dynamicPageAppService.GetDataAsync( |
||||
|
"products", |
||||
|
new DynamicEntityListRequestDto |
||||
|
{ |
||||
|
MaxResultCount = 20 |
||||
|
} |
||||
|
); |
||||
|
} |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
Reach for this service when your custom code should behave like the runtime page rather than like a raw repository call. |
||||
|
|
||||
|
## Joining Low-Code and Regular Entities in LINQ |
||||
|
|
||||
|
Low-code entities can be composed with typed repositories in the same LINQ query. The low-code demo does this by joining dynamic order lines and orders with the typed `Customer` repository: |
||||
|
|
||||
|
````csharp |
||||
|
var orderLineQuery = await _dynamicEntityRepository |
||||
|
.SetEntityName("LowCodeDemo.Orders.OrderLine") |
||||
|
.GetQueryableAsync(); |
||||
|
|
||||
|
var orderQuery = (await _dynamicEntityRepository |
||||
|
.SetEntityName("LowCodeDemo.Orders.Order") |
||||
|
.GetQueryableAsync()) |
||||
|
.As<IQueryable<DynamicEntity>>(); |
||||
|
|
||||
|
var customerQuery = (await _customerRepository.GetQueryableAsync()) |
||||
|
.As<IQueryable<IEntity<Guid>>>(); |
||||
|
|
||||
|
var query = orderLineQuery |
||||
|
.Where(line => line.Data["Amount"] != null && (decimal?)line.Data["Amount"] > 1000m) |
||||
|
.GroupJoin( |
||||
|
orderQuery, |
||||
|
orderLine => (Guid?)orderLine["OrderId"], |
||||
|
order => order.Id, |
||||
|
(orderLine, orders) => new { orderLine, orders } |
||||
|
) |
||||
|
.SelectMany( |
||||
|
x => x.orders.DefaultIfEmpty(), |
||||
|
(x, order) => new { x.orderLine, order } |
||||
|
) |
||||
|
.GroupJoin( |
||||
|
customerQuery, |
||||
|
x => (Guid?)x.order!.Data["CustomerId"], |
||||
|
customer => customer.Id, |
||||
|
(x, customers) => new { x.orderLine, x.order, customers } |
||||
|
); |
||||
|
```` |
||||
|
|
||||
|
This is useful when a business rule or reporting service needs both low-code entities and typed C# entities in one application-layer query. |
||||
|
|
||||
|
## See Also |
||||
|
|
||||
|
* [Reference Entities](reference-entities.md) |
||||
|
* [Attributes & Fluent API](fluent-api.md) |
||||
|
* [Model Descriptor Files](model-json.md) |
||||
|
* [React Runtime](react-runtime.md) |
||||
|
* [Scripting API](scripting-api.md) |
||||
|
Before Width: | Height: | Size: 56 KiB After Width: | Height: | Size: 47 KiB |
|
Before Width: | Height: | Size: 70 KiB After Width: | Height: | Size: 58 KiB |
|
Before Width: | Height: | Size: 33 KiB After Width: | Height: | Size: 46 KiB |
|
Before Width: | Height: | Size: 30 KiB After Width: | Height: | Size: 35 KiB |
|
Before Width: | Height: | Size: 40 KiB After Width: | Height: | Size: 44 KiB |
|
Before Width: | Height: | Size: 71 KiB After Width: | Height: | Size: 59 KiB |
|
Before Width: | Height: | Size: 70 KiB After Width: | Height: | Size: 60 KiB |
Loading…
Reference in new issue