mirror of https://github.com/abpframework/abp.git
enisn
2 years ago
1125 changed files with 21237 additions and 6241 deletions
|
Before Width: | Height: | Size: 280 KiB After Width: | Height: | Size: 212 KiB |
|
Before Width: | Height: | Size: 72 KiB After Width: | Height: | Size: 54 KiB |
|
After Width: | Height: | Size: 189 KiB |
|
After Width: | Height: | Size: 525 KiB |
@ -0,0 +1,93 @@ |
|||
# ABP.IO Platform 9.0 Has Been Released Based on .NET 9.0 |
|||
|
|||
 |
|||
|
|||
Today, [ABP](https://abp.io/) 9.0 stable version has been released based on [.NET 9.0](https://dotnet.microsoft.com/en-us/download/dotnet/9.0). You can create solutions with ABP 9.0 starting from ABP Studio v0.9.11 or by using the ABP CLI as explained in the following sections. |
|||
|
|||
## What's New With Version 9.0? |
|||
|
|||
All the new features were explained in detail in the [9.0 RC Announcement Post](https://abp.io/blog/announcing-abp-9-0-release-candidate), so there is no need to review them again. You can check it out for more details. |
|||
|
|||
## Getting Started with 9.0 |
|||
|
|||
### Creating New Solutions |
|||
|
|||
You can check the [Get Started page](https://abp.io/get-started) to see how to get started with ABP. You can either download [ABP Studio](https://abp.io/get-started#abp-studio-tab) (**recommended**, if you prefer a user-friendly GUI application - desktop application) or use the [ABP CLI](https://abp.io/docs/latest/cli) to create new solutions. |
|||
|
|||
By default, ABP Studio uses stable versions to create solutions. Therefore, it will be creating the solution with the latest stable version, which is v9.0 for now, so you don't need to specify the version. **You can create solutions with ABP 9.0 starting from v0.9.11.** |
|||
|
|||
### How to Upgrade an Existing Solution |
|||
|
|||
You can upgrade your existing solutions with either ABP Studio or ABP CLI. In the following sections, both approaches are explained: |
|||
|
|||
### Upgrading via ABP Studio |
|||
|
|||
If you are already using the ABP Studio, you can upgrade it to the latest version to align it with ABP v9.0. ABP Studio periodically checks for updates in the background, and when a new version of ABP Studio is available, you will be notified through a modal. Then, you can update it by confirming the opened modal. See [the documentation](https://abp.io/docs/latest/studio/installation#upgrading) for more info. |
|||
|
|||
After upgrading the ABP Studio, then you can open your solution in the application, and simply click the **Switch to stable** action button to instantly upgrade your solution: |
|||
|
|||
 |
|||
|
|||
> Please note that ABP CLI & ABP Studio only upgrade the related ABP packages, so you need to upgrade the other packages for .NET 9.0 manually. |
|||
|
|||
### Upgrading via ABP CLI |
|||
|
|||
Alternatively, you can upgrade your existing solution via ABP CLI. First, you need to install the ABP CLI or upgrade it to the latest version. |
|||
|
|||
If you haven't installed it yet, you can run the following command: |
|||
|
|||
```bash |
|||
dotnet tool install -g Volo.Abp.Studio.Cli |
|||
``` |
|||
|
|||
Or to update the existing CLI, you can run the following command: |
|||
|
|||
```bash |
|||
dotnet tool update -g Volo.Abp.Studio.Cli |
|||
``` |
|||
|
|||
After installing/updating the ABP CLI, you can use the [`update` command](https://abp.io/docs/latest/CLI#update) to update all the ABP related NuGet and NPM packages in your solution as follows: |
|||
|
|||
```bash |
|||
abp update |
|||
``` |
|||
|
|||
You can run this command in the root folder of your solution to update all ABP related packages. |
|||
|
|||
> Please note that ABP CLI & ABP Studio only upgrade the related ABP packages, so you need to upgrade the other packages for .NET 9.0 manually. |
|||
|
|||
## Migration Guides |
|||
|
|||
There are a few breaking changes in this version that may affect your application. Please read the migration guide carefully, if you are upgrading from v8.x: [ABP Version 9.0 Migration Guide](https://abp.io/docs/9.0/release-info/migration-guides/abp-9-0) |
|||
|
|||
## Community News |
|||
|
|||
### Highlights from .NET 9.0 |
|||
|
|||
Our team has closely followed the ASP.NET Core and Entity Framework Core 9.0 releases, read Microsoft's guides and documentation, and adapted the changes to our ABP.IO Platform. We are proud to say that we've shipped the ABP 9.0 based on .NET 9.0 just after Microsoft's .NET 9.0 release. |
|||
|
|||
In addition to the ABP's .NET 9.0 upgrade, our team has created many great articles to highlight the important features coming with ASP.NET Core 9.0 and Entity Framework Core 9.0. |
|||
|
|||
> You can read [this post](https://volosoft.com/blog/Highlights-for-ASP-NET-Entity-Framework-Core-NET-9-0) to see the list of all articles. |
|||
|
|||
### New ABP Community Articles |
|||
|
|||
In addition to [the articles to highlight .NET 9.0 features written by our team](https://volosoft.com/blog/Highlights-for-ASP-NET-Entity-Framework-Core-NET-9-0), here are some of the recent posts added to the [ABP Community](https://abp.io/community): |
|||
|
|||
* [Video: Building Modular Monolith Applications with ASP.NET Core & ABP Studio](https://abp.io/community/videos/building-modular-monolith-applications-with-asp.net-core-abp-studio-66znukvf) by [Halil İbrahim Kalkan](https://x.com/hibrahimkalkan) |
|||
* [How to create your Own AI Bot on WhatsApp Using an ABP.io Template](https://abp.io/community/articles/how-to-create-your-own-ai-bot-on-whatsapp-using-the-abp-framework-c6jgvt9c) by [Michael Kokula](https://abp.io/community/members/Michal_Kokula) |
|||
* [ABP Now Supports .NET 9](https://abp.io/community/articles/abp-now-supports-.net-9-zpkznc4f) by [Alper Ebiçoğlu](https://x.com/alperebicoglu) |
|||
|
|||
Thanks to the ABP Community for all the content they have published. You can also [post your ABP related (text or video) content](https://abp.io/community/posts/submit) to the ABP Community. |
|||
|
|||
### ABP Community Talks 2024.7: What’s New with .NET 9 & ABP 9? |
|||
|
|||
 |
|||
|
|||
In this episode of ABP Community Talks, 2024.7; we will dive into the features that came with .NET 9.0 with [Alper Ebicoglu](https://github.com/ebicoglu), [Engincan Veske](https://github.com/EngincanV), [Berkan Sasmaz](https://github.com/berkansasmaz) and [Ahmet Faruk Ulu](https://github.com/ahmetfarukulu). |
|||
|
|||
## Conclusion |
|||
|
|||
This version comes with some new features and a lot of enhancements to the existing features. You can see the [Road Map](https://docs.abp.io/en/abp/9.0/Road-Map) documentation to learn about the release schedule and planned features for the next releases. Please try ABP v9.0 and provide feedback to help us release more stable versions. |
|||
|
|||
Thanks for being a part of this community! |
|||
|
After Width: | Height: | Size: 27 KiB |
@ -0,0 +1,67 @@ |
|||
# ABP Studio Goes AOT: Faster Startups with Ready-to-Run (R2R) Publishing |
|||
|
|||
We're excited that [ABP Studio](https://abp.io/studio) now supports [Ready-to-Run (R2R) publishing](https://learn.microsoft.com/en-us/dotnet/core/deploying/ready-to-run) (starting from v0.9.16+), a hybrid form of ahead-of-time (AOT) compilation. This enhancement significantly improves the startup time and overall performance of ABP Studio, making it faster and more performant than ever before. |
|||
|
|||
Let's dive into what R2R publishing is, how it works, and the benefits it brings to ABP Studio. |
|||
|
|||
## What is Ready-to-Run (R2R) Publishing? |
|||
|
|||
Ready-to-Run (R2R) is a form of AOT compilation available in the .NET ecosystem. Unlike traditional just-in-time (JIT) compilation, R2R precompiles parts of your application to native code before deployment. This precompiled code helps reduce the startup time by minimizing the work needed during runtime. |
|||
|
|||
However, R2R isn't a complete AOT compilation. Instead, it's a hybrid approach because it stores both: |
|||
|
|||
* **Native code for precompiled methods** (to improve startup time and performance) |
|||
|
|||
* **Intermediate Language (IL) code** for methods that may need further JIT compilation |
|||
|
|||
This hybrid nature is why R2R binaries are typically larger. For ABP Studio, the storage size increased by ~150 MB with R2R enabled, but the trade-off is well worth it for the performance and startup-time gains. |
|||
|
|||
## How R2R (Ready-to-Run) Improves ABP Studio |
|||
|
|||
### Faster Startup Time 🚀 |
|||
|
|||
One of the biggest advantages of R2R publishing is its impact on startup times. In our local tests, enabling R2R resulted in startup times being **reduced by 2.5x** ⬇️. |
|||
|
|||
This means you can get to work faster, without waiting for the application to being startup from the beginning. Whether you're launching ABP Studio to manage projects, generate code, or deploy applications, the improved responsiveness is noticeable. |
|||
|
|||
### Performance Enhancements 📈 |
|||
|
|||
In addition to faster startups, R2R publishing contributes to overall performance improvements. By precompiling frequently used methods, R2R reduces the workload on the JIT compiler during execution, leading to smoother and more efficient operations. |
|||
|
|||
### Trade-offs: Increased Storage Size 🆙 |
|||
|
|||
With great performance comes a slight trade-off: storage size. R2R binaries include both **native** and **IL code**, which increases the file size. In the case of ABP Studio, the storage footprint increased by ~150 MB. However, the substantial improvements in speed and responsiveness make this a worthwhile investment. |
|||
|
|||
## How to Enable R2R Publishing in Your Applications? |
|||
|
|||
If you're developing applications and want to benefit from R2R, here's a quick guide on how to enable it in your .NET projects: |
|||
|
|||
1. You can add the following configuration to your final project's `.csproj` file: |
|||
|
|||
```xml |
|||
<PropertyGroup> |
|||
<PublishReadyToRun>true</PublishReadyToRun> |
|||
</PropertyGroup> |
|||
``` |
|||
|
|||
2. Then, publish your application with the `dotnet publish` command: |
|||
|
|||
```bash |
|||
dotnet publish -c Release |
|||
``` |
|||
|
|||
Alternatively, you can specify the _PublishReadyToRun_ flag directly to the `dotnet publish` command as follows: |
|||
|
|||
```bash |
|||
dotnet publish -c Release -r win-x64 -p:PublishReadyToRun=true |
|||
``` |
|||
|
|||
That's it! Your application will now include precompiled native code for faster startup and great performance benefits. |
|||
|
|||
> Please refer to the [official documentation](https://learn.microsoft.com/en-us/dotnet/core/deploying/ready-to-run) before publishing your application with R2R. |
|||
|
|||
## Conclusion |
|||
|
|||
As ABP team, we're always looking for ways to improve the developer experience. By adopting **Ready-to-Run (R2R) publishing** for ABP Studio, we're aiming to deliver a faster and more efficient tool for your development needs. |
|||
|
|||
Stay tuned for more updates and enhancements as we continue to optimize ABP Studio and please provide us with your invaluable feedback. |
|||
|
Before Width: | Height: | Size: 541 KiB After Width: | Height: | Size: 524 KiB |
|
Before Width: | Height: | Size: 110 KiB After Width: | Height: | Size: 106 KiB |
|
Before Width: | Height: | Size: 441 KiB After Width: | Height: | Size: 432 KiB |
|
Before Width: | Height: | Size: 33 KiB After Width: | Height: | Size: 23 KiB |
|
Before Width: | Height: | Size: 60 KiB After Width: | Height: | Size: 40 KiB |
|
Before Width: | Height: | Size: 155 KiB After Width: | Height: | Size: 108 KiB |
|
Before Width: | Height: | Size: 121 KiB After Width: | Height: | Size: 71 KiB |
|
Before Width: | Height: | Size: 54 KiB After Width: | Height: | Size: 36 KiB |
|
Before Width: | Height: | Size: 840 KiB After Width: | Height: | Size: 93 KiB |
|
Before Width: | Height: | Size: 528 KiB After Width: | Height: | Size: 46 KiB |
@ -0,0 +1,125 @@ |
|||
# Hybrid Cache in .NET 9 |
|||
|
|||
.NET 9 introduces an exciting feature: **HybridCache**, an advanced caching mechanism that seamlessly combines multiple caching strategies to maximize performance and scalability. |
|||
|
|||
It offers a flexible caching solution that combines the best aspects of local and distributed caching. **HybridCache** is particularly useful in scenarios where quick, in-memory access is desirable but data consistency across multiple application instances is also a requirement. |
|||
|
|||
In this article, we’ll explore **HybridCache** in .NET 9 and how it integrates with ABP Framework using `AbpHybridCache`. This new feature offers a robust solution for applications that need to scale while maintaining efficient caching strategies. |
|||
|
|||
## What is HybridCache? |
|||
|
|||
**HybridCache** is designed to merge different caching layers, commonly including an in-memory cache (for high-speed access) and a distributed cache (for scalability across multiple instances). This hybrid approach allows for: |
|||
|
|||
* **Improved Performance**: Frequently accessed data is stored in-memory, reducing latency. |
|||
* **Increased Scalability**: Cached data can still be shared across distributed environments, essential for load-balanced applications. |
|||
* **Automatic Synchronization**: Changes in distributed cache automatically update the in-memory cache, ensuring data consistency. |
|||
|
|||
## Using HybridCache with ABP |
|||
|
|||
> For more information about the implementation in the ABP side, you can refer to the pull request [here](https://github.com/abpframework/abp/pull/20859). |
|||
|
|||
ABP's support for **HybridCache** is available starting from version 9.0 through the [`AbpHybridCache`](https://github.com/abpframework/abp/blob/dev/framework/src/Volo.Abp.Caching/Volo/Abp/Caching/Hybrid/AbpHybridCache.cs) implementation. By leveraging this feature, developers using ABP can implement hybrid caching in a way that aligns with ABP’s modular and extensible architecture. |
|||
|
|||
To demonstrate how to use **HybridCache** in ABP, let's start with a simple example. |
|||
|
|||
> You can create an ABP-based application with v9.0+, and then follow the next steps for using hybrid caching in your application. |
|||
|
|||
### Configuring the `AbpHybridCacheOptions` (Optional) |
|||
|
|||
First, you can configure the hybrid cache options in your module class as below (it's optional): |
|||
|
|||
```csharp |
|||
using Microsoft.Extensions.Caching.Hybrid; |
|||
using Volo.Abp.Caching.Hybrid; |
|||
|
|||
public class YourModule : AbpModule |
|||
{ |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
//... |
|||
|
|||
Configure<AbpHybridCacheOptions>(options => |
|||
{ |
|||
//configuring the global hybrid cache options |
|||
options.GlobalHybridCacheEntryOptions = new HybridCacheEntryOptions() |
|||
{ |
|||
Expiration = TimeSpan.FromMinutes(20), |
|||
LocalCacheExpiration = TimeSpan.FromMinutes(10) |
|||
}; |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
* You can configure the `AbpHybridCacheOptions` to set *keyPrefix* for your cache keys, throw or hide exceptions for the distributed cache (by default *it hides errors*), or configure cache for specific cache item keys and more... |
|||
* By setting the `GlobalHybridCacheEntryOptions`, you specify the caching options globally in your application. Thanks to that, you don't need to manually pass the related options whenever you use the `IHybridCache` service. |
|||
|
|||
### Using the `IHybridCache` Service |
|||
|
|||
After the configuration, now you can inject the `IHybridCache` and use it to set and retrieve cache values: |
|||
|
|||
```csharp |
|||
using Volo.Abp.Caching.Hybrid; |
|||
|
|||
public class BookAppService : ApplicationService, IBookAppService |
|||
{ |
|||
private readonly IHybridCache<BookCacheItem> _hybridCache; |
|||
|
|||
public BookAppService(IHybridCache<BookCacheItem> hybridCache) |
|||
{ |
|||
_hybridCache = hybridCache; |
|||
} |
|||
|
|||
public async Task<BookCacheItem> GetBookWithPageCountAsync(string name) |
|||
{ |
|||
var cacheKey = "cacheKey:book-" + name; |
|||
|
|||
// Retrieve data from hybrid cache |
|||
return await _hybridCache.GetOrCreateAsync(cacheKey, async () => |
|||
{ |
|||
// Simulating getting and returning the data if not exist in the cache |
|||
return new BookCacheItem |
|||
{ |
|||
Name = name, |
|||
PageCount = 100 |
|||
}; |
|||
}); |
|||
} |
|||
} |
|||
|
|||
public class BookCacheItem |
|||
{ |
|||
public string Name { get; set; } |
|||
|
|||
public int PageCount { get; set; } |
|||
} |
|||
``` |
|||
|
|||
* You can use the `IHybridCache<TCacheItem>` or `IHybridCache<TCacheItem, TCacheKey>` service to leverage the hybrid caching. If you use `IHybridCache<TCacheItem>`as the service, then you should pass the cache key as *string* like in the example above. |
|||
* In this example, you used the `GetOrCreateAsync` method, which first tries to get the cache item with the provided cache key, if there is no cache with the specified key, then it runs the factory method and add the returned data to the cache. |
|||
* Alternatively, you can use the `SetAsync` method to set the cache item. |
|||
|
|||
### Debugging the `IHybridCache` Service (deep-dive) |
|||
|
|||
When you debug the `IHybridCache` service, you'll notice the L1 and L2 cache stores. (L1 is in-memory cache store and L2 is the distributed cache store): |
|||
|
|||
 |
|||
|
|||
As you can see from the figure, it only set the cache item to the **LocalCache** (`MemoryCache`) and did not set the **BackendCache** (`DistributedCache`) because I did not configure the distributed cache and not running my application in multiple instances. But as you can notice, even without an `IDistributedCache` configuration, the `HybridCache` service will still provide in-process caching. |
|||
|
|||
**Note:** If you configure distributed caching options, `HybridCache` service uses the distributed cache and sets the **BackendCache**. |
|||
|
|||
## Conclusion |
|||
|
|||
The **HybridCache** library in .NET 9 provides a powerful tool for applications needing both high-speed caching and consistency in distributed environments. |
|||
|
|||
With ABP Framework’s `AbpHybridCache` support, integrating this feature into an ABP-based application becomes straightforward. This setup helps ensure that cached data remains synchronized across instances, bringing a new level of flexibility to caching in .NET 9 applications. |
|||
|
|||
> For more information, you can refer to the [Microsoft's official document](https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-9.0?view=aspnetcore-9.0#new-hybridcache-library). |
|||
|
|||
## References |
|||
|
|||
- https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-9.0?view=aspnetcore-9.0#new-hybridcache-library |
|||
- https://www.youtube.com/watch?v=TDyZc11cJfA |
|||
- https://github.com/abpframework/abp/pull/20803 |
|||
- https://github.com/abpframework/abp/pull/20859 |
|||
|
After Width: | Height: | Size: 483 KiB |
|
After Width: | Height: | Size: 144 KiB |
@ -0,0 +1,86 @@ |
|||
# EF Core 9 Read-only Primitive Collections |
|||
|
|||
In this article, we will explore the new features introduced in EF Core 9, specifically focusing on Read-only Primitive Collections. EF Core 8 introduced support for mapping arrays and mutable lists of primitive types, and you can read more about it [here](https://abp.io/community/articles/ef-core-8-primitive-collections-ttn5b6xp). This has been expanded in EF Core 9 to include read-only collections/lists. Specifically, EF Core 9 supports collections typed as `IReadOnlyList`, `IReadOnlyCollection`, or `ReadOnlyCollection`. |
|||
|
|||
## Introduction to EF Core 9 Read-only Primitive Collections |
|||
|
|||
Entity Framework Core 9 introduces several enhancements, one of which is the support for Read-only Primitive Collections. This feature aims to provide better support for scenarios where collections of primitive types, such as `int`, `string`, or `bool`, need to be used in a read-only manner in your entity classes. Previously, developers had to use complex workarounds to ensure collections couldn't be modified, but EF Core 9 now provides a simpler, built-in solution to handle this more effectively. |
|||
|
|||
### Why Read-only Primitive Collections Matter |
|||
|
|||
Read-only Primitive Collections are particularly useful when you need to guarantee the integrity of certain data within your entities. For example, imagine you have a `Car` entity that has a collection of `Colors`, represented as a set of enums. You might not want these colors to be modified after they're initially set, ensuring that any business logic reliant on these values remains consistent. |
|||
|
|||
EF Core 9 introduces a convenient way to define these collections as read-only, helping developers maintain stricter control over their data. |
|||
|
|||
### How It Works |
|||
|
|||
Defining a read-only primitive collection is quite straightforward in EF Core 9. You can use the `IReadOnlyList<T>`, `IReadOnlyCollection<T>`, or `ReadOnlyCollection<T>` types to declare your properties, ensuring a consistent read-only behavior. This helps maintain data integrity by preventing modifications after the collection is set. Below is an example that includes a `Car` class and a `Color` enum. The `Car` class has a `Colors` property that holds a read-only list of available colors, ensuring that these values cannot be modified after being initially set: |
|||
|
|||
```csharp |
|||
public enum Color |
|||
{ |
|||
Black, |
|||
White, |
|||
Red, |
|||
Blue |
|||
} |
|||
|
|||
public class Car |
|||
{ |
|||
public int Id { get; set; } |
|||
public string Brand { get; set; } |
|||
public string Model { get; set; } |
|||
public IReadOnlyList<Color> Colors { get; private set; } = new List<Color> { Color.Black, Color.White }.AsReadOnly(); |
|||
|
|||
protected Car() |
|||
{ |
|||
/* This constructor is for deserialization / ORM purpose */ |
|||
} |
|||
|
|||
public Car(string brand, string model, IEnumerable<Color> colors) |
|||
{ |
|||
Brand = brand; |
|||
Model = model; |
|||
Colors = colors.ToList().AsReadOnly(); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
In the example above, `Colors` is defined as a read-only list, preventing any accidental modifications once it is set. This ensures that data integrity is maintained without the need for manual validation. |
|||
|
|||
To query cars with specific colors, you can use the following example: |
|||
|
|||
```csharp |
|||
var colors = new List<Color> { Color.Black, Color.White }; |
|||
var cars = await context.Cars |
|||
.Where(c => c.Colors.Intersect(colors).Any()) |
|||
.ToListAsync(); |
|||
``` |
|||
|
|||
The query selects all cars that have any of the specified colors in their `Colors` collection. |
|||
|
|||
The SQL result looks like this; as you can see, it sends colors as parameters instead of adding them inline. It also uses the `json_each` function to deserialize on the database side: |
|||
|
|||
```sql |
|||
SELECT "c"."id", |
|||
"c"."brand", |
|||
"c"."colors", |
|||
"c"."model" |
|||
FROM "cars" AS "c" |
|||
WHERE EXISTS (SELECT 1 |
|||
FROM (SELECT "c0"."value" |
|||
FROM Json_each("c"."colors") AS "c0" |
|||
INTERSECT |
|||
SELECT "c1"."value" |
|||
FROM Json_each(@__colors_0) AS "c1") AS "i") |
|||
``` |
|||
|
|||
### Conclusion |
|||
|
|||
Read-only primitive collections make it easier to enforce data integrity by preventing changes to your collection data. This feature helps simplify your code while ensuring that critical parts of your data remain consistent. |
|||
|
|||
## References |
|||
|
|||
- https://learn.microsoft.com/en-us/ef/core/what-is-new/ef-core-9.0/whatsnew#read-only-primitive-collections |
|||
- https://learn.microsoft.com/en-us/ef/core/what-is-new/ef-core-8.0/whatsnew#primitive-collections |
|||
- https://abp.io/community/articles/ef-core-8-primitive-collections-ttn5b6xp |
|||
@ -0,0 +1,54 @@ |
|||
# .NET Aspire 9.0 Features |
|||
|
|||
.NET Aspire 9.0 is the next major release, supporting both .NET 8 and .NET 9. This version includes new features and improvements. |
|||
|
|||
## Upgrade to .NET Aspire |
|||
|
|||
Now, you don't need workloads to develop .NET Aspire applications. In your project, you can add an SDK reference to `Aspire.AppHost.Sdk`. |
|||
For more information, you can check out [https://learn.microsoft.com/en-us/dotnet/aspire/whats-new/dotnet-aspire-9?tabs=windows#upgrade-to-net-aspire-9](https://learn.microsoft.com/en-us/dotnet/aspire/whats-new/dotnet-aspire-9?tabs=windows#upgrade-to-net-aspire-9) which explains upgrading an existing project in details. |
|||
|
|||
## Dashboard |
|||
|
|||
.NET Aspire offers a nice dashboard for developers to observe the performance and behavior of their applications. In this version, there are some enhancements; |
|||
|
|||
* **Manage resource lifecycle**: You can stop, start, and restart resources. |
|||
* **Mobile and responsive support**: The .NET Aspire dashboard is now mobile-friendly. |
|||
* **Sensitive properties**: Properties can be marked as sensitive, automatically masking them in the dashboard UI. |
|||
* **Volumes**: Configured container volumes are listed in resource details. |
|||
* **Health checks**: .NET Aspire 9 adds support for health checks. |
|||
|
|||
 |
|||
|
|||
## Telemetry |
|||
|
|||
.NET Aspire 9 comes with many new features to the Telemetry service. |
|||
|
|||
* **Improve telemetry filtering**: Telemetry data can now be filtered by attribute values. |
|||
* **Combine telemetry from multiple resources**: If a resource has multiple replicas, you can now filter telemetry data to view from all instances. |
|||
* **Browser telemetry support**: The dashboard now supports OpenTelemetry Protocol (OTLP) over HTTP and cross-origin resource sharing (CORS). |
|||
|
|||
 |
|||
|
|||
## Orchestration |
|||
|
|||
The .NET App Host is a core component of the .NET runtime that helps launch and execute .NET applications. |
|||
.NET Aspire 9 introduces many new features to the app host. Let's take a look; |
|||
|
|||
* **Waiting for dependencies**: You can configure a resource to wait for another resource to start before starting. |
|||
* **Resource health checks**: The `Waiting for dependencies` feature uses health checks to determine if a resource is ready. |
|||
|
|||
## Integrations |
|||
|
|||
.NET Aspire has integrations with some services and tools that make it easy to get started. New integrations are coming with .NET Aspire 9. |
|||
|
|||
* Redis Insight |
|||
* OpenAI (Preview) |
|||
* MongoDB |
|||
* Azure |
|||
|
|||
For Azure part, it is better to check the official documentation here [https://learn.microsoft.com/en-us/dotnet/aspire/whats-new/dotnet-aspire-9-release-candidate-1?tabs=windows&pivots=visual-studio#azure](https://learn.microsoft.com/en-us/dotnet/aspire/whats-new/dotnet-aspire-9-release-candidate-1?tabs=windows&pivots=visual-studio#azure) because it has a very detailed explanation. |
|||
|
|||
## ABP Studio |
|||
|
|||
.NET Aspire and [ABP Studio](https://abp.io/studio) are tools for different purposes with different scopes, and they have different approaches to solving problems; many developers may still be confused since they also have some similar functionalities and solve some common problems. You can check the comparison of .NET Aspire and ABP Studio in this [article](https://abp.io/community/articles/.net-aspire-vs-abp-studio-side-by-side-t1c73d1l). |
|||
|
|||
|
After Width: | Height: | Size: 51 KiB |
|
After Width: | Height: | Size: 55 KiB |
@ -0,0 +1,113 @@ |
|||
# SignalR supports trimming and Native AOT |
|||
|
|||
## What is SignalR? |
|||
|
|||
SignalR is a library that allows you to add real-time web functionality to your applications. It provides a simple API for creating server-to-client remote procedure calls (RPC) that can be called from the server and client. Now SignalR supports trimming and Native AOT in .NET 8.0 and .NET 9.0. You can learn more about [SignalR new features](https://abp.io/community/articles/asp.net-core-signalr-new-features-summary-kcydtdgq) in this article. |
|||
|
|||
## What is trimming and Native AOT? |
|||
|
|||
AOT (Ahead-of-Time) compilation is a feature that allows you to compile your application into native code before running it. This can help improve performance and reduce startup times. Trimming is a feature that allows you to remove unused code from your application, reducing its size and improving performance. You can learn more about [Native AOT Compilation](https://abp.io/community/articles/native-aot-compilation-in-.net-8-oq7qtwov) in this article. |
|||
|
|||
## How to use SignalR with trimming and Native AOT? |
|||
|
|||
You can create ASP.NET Core AOT application with using the following command: |
|||
|
|||
```bash |
|||
dotnet new webapiaot -n Acme.Sample |
|||
``` |
|||
|
|||
The created application uses `CreateSlimBuilder` method to create minimal builder for the application. You can use `CreateBuilder` method to create a builder with all the services registered. However, deploying an application with `CreateSlimBuilder` method is more convenient because it reduces the size of the application. You can learn more about [CreateSlimBuilder vs CreateBuilder](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/native-aot#createslimbuilder-vs-createbuilder). |
|||
|
|||
Replace the `Program.cs` file with the following code: |
|||
|
|||
```csharp |
|||
using Microsoft.AspNetCore.SignalR; |
|||
using System.Text.Json.Serialization; |
|||
|
|||
var builder = WebApplication.CreateSlimBuilder(args); |
|||
|
|||
builder.Services.AddSignalR(); |
|||
builder.Services.Configure<JsonHubProtocolOptions>(o => |
|||
{ |
|||
o.PayloadSerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonSerializerContext.Default); |
|||
}); |
|||
|
|||
var app = builder.Build(); |
|||
|
|||
app.MapHub<ChatHub>("/chatHub"); |
|||
app.MapGet("/", () => Results.Content(""" |
|||
<!DOCTYPE html> |
|||
<html> |
|||
<head> |
|||
<title>SignalR Chat</title> |
|||
</head> |
|||
<body> |
|||
<input id="userInput" placeholder="Enter your name" /> |
|||
<input id="messageInput" placeholder="Type a message" /> |
|||
<button onclick="sendMessage()">Send</button> |
|||
<ul id="messages"></ul> |
|||
|
|||
<script src="https://cdnjs.cloudflare.com/ajax/libs/microsoft-signalr/8.0.7/signalr.min.js"></script> |
|||
<script> |
|||
const connection = new signalR.HubConnectionBuilder() |
|||
.withUrl("/chatHub") |
|||
.build(); |
|||
|
|||
connection.on("ReceiveMessage", (user, message) => { |
|||
const li = document.createElement("li"); |
|||
li.textContent = `${user}: ${message}`; |
|||
document.getElementById("messages").appendChild(li); |
|||
}); |
|||
|
|||
async function sendMessage() { |
|||
const user = document.getElementById("userInput").value; |
|||
const message = document.getElementById("messageInput").value; |
|||
await connection.invoke("SendMessage", user, message); |
|||
} |
|||
|
|||
connection.start().catch(err => console.error(err)); |
|||
</script> |
|||
</body> |
|||
</html> |
|||
""", "text/html")); |
|||
|
|||
app.Run(); |
|||
|
|||
[JsonSerializable(typeof(string))] |
|||
internal partial class AppJsonSerializerContext : JsonSerializerContext { } |
|||
|
|||
public class ChatHub : Hub |
|||
{ |
|||
public async Task SendMessage(string user, string message) |
|||
{ |
|||
await Clients.All.SendAsync("ReceiveMessage", user, message); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
It is a simple chat application that uses SignalR to send and receive messages. |
|||
|
|||
 |
|||
|
|||
Before deploying the application, ensure that **Desktop development with C++** is installed on your machine if you're using Windows OS. For more details, you can check the [pre-requisites](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot#prerequisites). |
|||
|
|||
You can deploy the application with the following command: |
|||
|
|||
```bash |
|||
dotnet publish -c Release |
|||
``` |
|||
|
|||
### Limitations |
|||
|
|||
Since we are using Native AOT, there are some limitations that you should be aware of: |
|||
|
|||
- **Only the JSON protocol is supported**: For the payload serialization in SignalR, only the JSON protocol is supported. You need to configure the `JsonHubProtocolOptions` to use the `AppJsonSerializerContext` for serialization/deserialization. |
|||
- **Reflection**: Native AOT does not support reflection. You need to use the `JsonSerializable` attribute to specify the types that should be serialized/deserialized. In this example, we have used the `JsonSerializable` attribute for the `string` type in the `AppJsonSerializerContext` class. |
|||
|
|||
For more details, you can check the [limitations](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot#limitations-of-native-aot-deployment) of Native AOT. |
|||
|
|||
## Conclusion |
|||
|
|||
In this article, we learned how to use SignalR with trimming and Native AOT in .NET 8.0 and .NET 9.0. We created a simple chat application that uses SignalR to send and receive messages. We also discussed the limitations of using Native AOT and how to overcome them. |
|||
|
|||
For more information, you can refer to the [Microsoft's official document](https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-9.0?view=aspnetcore-9.0#signalr-supports-trimming-and-native-aot). |
|||
|
After Width: | Height: | Size: 31 KiB |
@ -0,0 +1,58 @@ |
|||
# Middleware Now Supports Keyed Dependency Injection in .NET 9 |
|||
|
|||
This article explores a new feature in .NET 9 that enables keyed dependency injection in middleware. Previously, .NET 8 introduced keyed services, which allowed developers to register multiple instances of the same service type with distinct keys. Now, .NET 9 extends this feature to middleware, making it easier to inject specific services within the middleware based on defined keys. For more details, see this [overview on the .NET blog](https://github.com/dotnet/core/blob/main/release-notes/9.0/preview/rc1/aspnetcore.md#keyed-di-in-middleware). |
|||
|
|||
## What is Keyed Dependency Injection? |
|||
|
|||
Keyed dependency injection is a technique for registering multiple service versions with unique identifiers, or “keys.” This approach is especially helpful when multiple implementations of the same service are required in different contexts. For example, you may have various logging services but want to inject a specific logger based on the application’s current needs. By using keys, developers can ensure that the appropriate service version is injected precisely where it’s needed. |
|||
|
|||
## Using Keyed Dependency Injection in Middleware |
|||
|
|||
In .NET 9, developers can now use keyed dependency injection directly in middleware. Keyed services can be injected through the middleware constructor or via the `Invoke`/`InvokeAsync` methods, allowing for straightforward and flexible control of service instances in middleware components. Here’s an example of how to configure and use keyed dependency injection in middleware: |
|||
|
|||
```csharp |
|||
var builder = WebApplication.CreateBuilder(args); |
|||
|
|||
// Register services with unique keys |
|||
builder.Services.AddKeyedSingleton<MySingletonClass>("test"); |
|||
builder.Services.AddKeyedScoped<MyScopedClass>("test2"); |
|||
|
|||
var app = builder.Build(); |
|||
app.UseMiddleware<MyMiddleware>(); |
|||
app.Run(); |
|||
|
|||
internal class MyMiddleware |
|||
{ |
|||
private readonly RequestDelegate _next; |
|||
private readonly MySingletonClass _singletonService; |
|||
|
|||
// Constructor injection with key |
|||
public MyMiddleware(RequestDelegate next, [FromKeyedServices("test")] MySingletonClass singletonService) |
|||
{ |
|||
_next = next; |
|||
_singletonService = singletonService; |
|||
} |
|||
|
|||
// Invoke method with additional scoped service injection using key |
|||
public Task Invoke(HttpContext context, [FromKeyedServices("test2")] MyScopedClass scopedService) |
|||
{ |
|||
// Middleware logic here |
|||
return _next(context); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
In this example: |
|||
- `MySingletonClass` and `MyScopedClass` are registered with unique keys (`"test"` and `"test2"`). |
|||
- These services are injected into the middleware through both the constructor and `Invoke` method, based on their respective keys. |
|||
|
|||
This approach allows developers to manage which service instances are available within middleware precisely. |
|||
|
|||
## Conclusion |
|||
|
|||
Keyed dependency injection in middleware is a significant addition in .NET 9. It provides developers with more control over which services are injected based on specific keys. This enhancement enables selective service injection in middleware scenarios, allowing for more modular and maintainable applications. |
|||
|
|||
## References |
|||
|
|||
- [.NET 9 Release Notes](https://github.com/dotnet/core/blob/main/release-notes/9.0/preview/rc1/aspnetcore.md#keyed-di-in-middleware) |
|||
- [Dependency Injection and Keyed Services](https://learn.microsoft.com/aspnet/core/fundamentals/dependency-injection#keyed-services) |
|||
@ -0,0 +1,108 @@ |
|||
# Optimizing Static Asset Delivery feature in ASP.NET Core 9.0 |
|||
|
|||
Delivering static assets efficiently is a key factor in building performant web applications. By optimizing how assets like CSS, JavaScript, and images are served to the browser, you can reduce load times, decrease network traffic, and improve the overall user experience. |
|||
|
|||
One powerful tool to help achieve this is **MapStaticAssets**, a feature in ASP.NET Core that significantly optimizes the delivery of static resources. Whether you're working with Blazor, Razor Pages, MVC, or other UI frameworks, **MapStaticAssets** streamlines asset management and ensures that your web app delivers resources in the most efficient way possible. |
|||
|
|||
## Why Optimizing Static Assets Matters |
|||
|
|||
Serving static assets without optimization can lead to several performance bottlenecks: |
|||
|
|||
- **Excessive network requests**: The browser may need to request the same resources multiple times, even if they haven’t changed. |
|||
- **Unnecessary data transfer**: Larger files are sent over the network, consuming bandwidth and slowing down page loads. |
|||
- **Outdated assets**: Without proper cache management, users may receive stale versions of files after an app update. |
|||
|
|||
Optimizing static assets involves compressing files, managing caching headers, and ensuring that only the necessary resources are sent to the client. **MapStaticAssets** takes care of all these issues in a seamless, automated way. |
|||
|
|||
## What is MapStaticAssets? |
|||
|
|||
**MapStaticAssets** is designed to enhance the default static asset serving mechanism in ASP.NET Core. It can replace `UseStaticFiles` in most scenarios and comes with several built-in optimizations. These optimizations are executed at both build and publish time, ensuring that static resources are served in the most efficient way possible when your app is running. |
|||
|
|||
Here's how you can implement **MapStaticAssets** in your app: |
|||
|
|||
```csharp |
|||
var builder = WebApplication.CreateBuilder(args); |
|||
|
|||
builder.Services.AddRazorPages(); |
|||
|
|||
var app = builder.Build(); |
|||
|
|||
if (!app.Environment.IsDevelopment()) |
|||
{ |
|||
app.UseExceptionHandler("/Error"); |
|||
app.UseHsts(); |
|||
} |
|||
|
|||
app.UseHttpsRedirection(); |
|||
|
|||
app.UseRouting(); |
|||
|
|||
app.UseAuthorization(); |
|||
|
|||
// Replacing UseStaticFiles with MapStaticAssets |
|||
app.MapStaticAssets(); |
|||
app.MapRazorPages(); |
|||
|
|||
app.Run(); |
|||
``` |
|||
|
|||
## Key Features of MapStaticAssets |
|||
|
|||
1. **Build-time Compression**: |
|||
**MapStaticAssets** automatically compresses all static assets during the build process. It uses **gzip** compression during development and **gzip + brotli** compression when publishing. This reduces the file size significantly, ensuring faster download times. |
|||
|
|||
For example, in a default Razor Pages template, assets like `bootstrap.min.css` and `jquery.js` are compressed by over 80%, resulting in significantly reduced file sizes: |
|||
|
|||
| File | Original Size | Compressed Size | Compression Reduction | |
|||
|----------------------|---------------|-----------------|-----------------------| |
|||
| `bootstrap.min.css` | 163 KB | 17.5 KB | 89.26% | |
|||
| `jquery.js` | 89.6 KB | 28 KB | 68.75% | |
|||
| `bootstrap.min.js` | 78.5 KB | 20 KB | 74.52% | |
|||
| **Total** | 331.1 KB | 65.5 KB | 80.20% | |
|||
|
|||
2. **Content-based ETags**: |
|||
**MapStaticAssets** generates **ETags** based on the SHA-256 hash of the file content, encoded in Base64. This ensures that the browser only re-downloads a resource if its content has changed. This eliminates unnecessary network requests, improving page load speeds. |
|||
|
|||
3. **Smaller File Sizes for Libraries**: |
|||
Popular component libraries, such as **Fluent UI Blazor** and **MudBlazor**, benefit from similar compression optimizations. For example, the size of the **MudBlazor** library is reduced by over 90%, from 588 KB to just 46.7 KB after compression. |
|||
|
|||
| File | Original Size | Compressed Size | Compression Reduction | |
|||
|----------------------|---------------|-----------------|-----------------------| |
|||
| `MudBlazor.min.css` | 541 KB | 37.5 KB | 93.07% | |
|||
| `MudBlazor.min.js` | 47.4 KB | 9.2 KB | 80.59% | |
|||
| **Total** | 588.4 KB | 46.7 KB | 92.07% | |
|||
|
|||
4. **Automatic Optimization**: |
|||
As libraries or components are added or updated, **MapStaticAssets** automatically optimizes the assets as part of the build process. This includes minimizing the size of JavaScript and CSS files, reducing the impact of mobile or low-bandwidth environments. |
|||
|
|||
5. **Serving Assets with a CDN**: |
|||
Although **MapStaticAssets** is focused on server-side optimizations, integrating a **CDN (Content Delivery Network)** can further boost performance by serving static assets from servers geographically closer to the user, reducing latency. |
|||
|
|||
## Comparing MapStaticAssets to IIS Dynamic Compression |
|||
|
|||
**MapStaticAssets** provides several advantages over traditional dynamic compression techniques, such as IIS **gzip** compression: |
|||
|
|||
- **Simplicity**: There is no need for server-specific configuration, making **MapStaticAssets** easy to implement. |
|||
- **Performance**: By compressing assets at build time, the app doesn't need to perform compression during every request, which improves server performance. |
|||
- **Optimization**: Developers can focus on ensuring that assets are compressed to the smallest possible size during the build process. |
|||
|
|||
For example, using **MapStaticAssets**, a file like `MudBlazor.min.css` is compressed down to 37.5 KB, whereas IIS dynamic compression might result in a size of 90 KB. This represents a **59%** reduction in size. |
|||
|
|||
## About MapAbpStaticAssets |
|||
|
|||
The ABP framework is 100% compatible with this new feature. |
|||
|
|||
However, some JavaScript, CSS, and image files exist in the [Virtual File System](https://abp.io/docs/latest/framework/infrastructure/virtual-file-system), which ASP.NET Core's **MapStaticAssets** can't handle. For these files, additional **StaticFileMiddleware** is needed to serve them, which is where **MapAbpStaticAssets** comes in. |
|||
|
|||
**MapAbpStaticAssets** adds the necessary **StaticFileMiddleware** to ensure that virtual files are correctly served. This middleware setup ensures seamless delivery of virtual resources alongside static assets. |
|||
|
|||
You can view the source code of **MapAbpStaticAssets** on [GitHub](https://github.com/abpframework/abp/blob/dev/framework/src/Volo.Abp.AspNetCore/Microsoft/AspNetCore/Builder/AbpApplicationBuilderExtensions.cs#L129-L198). |
|||
|
|||
## Conclusion |
|||
|
|||
Optimizing static asset delivery is essential for building fast, efficient web applications. **MapStaticAssets** simplifies and automates the optimization of static files by providing build-time compression, caching headers, and content-based ETags. This ensures that your app's static assets are always delivered in the most efficient way, whether users are on fast broadband or slower mobile connections. By using **MapStaticAssets**, you can deliver a faster, more reliable experience for your users with minimal effort. |
|||
|
|||
## References |
|||
|
|||
* [Static files in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/static-files?view=aspnetcore-9.0) |
|||
* [What's new in ASP.NET Core 9.0](https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-9.0?view=aspnetcore-8.0#optimize-static-web-asset-delivery) |
|||
|
After Width: | Height: | Size: 445 KiB |
|
After Width: | Height: | Size: 174 KiB |
|
After Width: | Height: | Size: 175 KiB |
|
After Width: | Height: | Size: 271 KiB |
|
After Width: | Height: | Size: 116 KiB |
|
After Width: | Height: | Size: 106 KiB |
@ -0,0 +1,164 @@ |
|||
Built-in OpenAPI Document Generation with .NET 9 — No more SwaggerUI! 👋 |
|||
======================================================================== |
|||
|
|||
 |
|||
|
|||
What’s Swagger UI? |
|||
------------------ |
|||
|
|||
[Swagger UI](https://swagger.io/) is an open-source tool that automatically generates an interactive, web-based documentation interface for WebAPIs. |
|||
It supports OpenAPI standards. It was very popular tool among the ASP.NET Core developers from 2020 to 2024. |
|||
Because it was a built-in tool comes with ASP.NET Core default templates. |
|||
We liked this tool because it was the first tool that allows us to make WebAPI calls for testing. |
|||
Now it provides paid services as well as free ones. |
|||
|
|||
> Previously, Swagger was included by default from **.NET 5** to **.NET 8** in .NET web templates. |
|||
|
|||
--- |
|||
|
|||
|
|||
|
|||
What’s OpenAPI? |
|||
--------------- |
|||
|
|||
OpenAPI is a standard specification for defining REST APIs. |
|||
The official website is [https://www.openapis.org/](https://www.openapis.org/). |
|||
Microsoft is now using OpenAPI and here is the official documentation 👉 [https://aka.ms/aspnet/openapi](https://aka.ms/aspnet/openapi) |
|||
|
|||
--- |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
Replacement of Swagger UI with OpenAPI |
|||
---------------------------------------------------------------------------- |
|||
|
|||
Swagger UI is no longer integrated into NET 9, as Microsoft wants a solution with first-class support, better control, and enhanced security. As you see in the below screenshot, Microsoft declares that it's already removed. |
|||
|
|||
 |
|||
|
|||
--- |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
## Why is Swagger Removed from .NET 9? |
|||
|
|||
In March 2024, the ASP.NET Core team announced that they are removing the `Swashbuckle.AspNetCore` dependency from web templates from .NET 9 release. |
|||
|
|||
|
|||
|
|||
> This decision was influenced by the project's lack of active maintenance and the absence of an official release for .NET 8. |
|||
|
|||
|
|||
|
|||
Microsoft team created a new package `Microsoft.AspNetCore.OpenApi`. It provides built-in OpenAPI document generation just like Swagger. So Microsoft doesn't depend on external tools. Because in every .NET release, they need to ask the owners of the external tool libraries to align with their new version. And sometimes these library owners cannot update their code-base according to the recent .NET changes. And it is becoming harder for Microsoft to support the 3rd party libraries under these circumstances. Basically reducing 3rd party dependencies will help Microsoft fast release cycles. |
|||
|
|||
I read Reddit, GitHub discussions and YouTube reviews about this topic. As I see community members expressed concerns about the inactivity of Swashbuckle and they are discussing alternatives like contributing to or forking the project. The Microsoft team also contacted the owners of Swashbuckle and NSwag to explore potential collaborations and ensure a smooth transition for developers. |
|||
|
|||
In the below GitHub issue, you can see the details of this decision: |
|||
|
|||
* [github.com/dotnet/aspnetcore/issues/54599](https://github.com/dotnet/aspnetcore/issues/54599) |
|||
|
|||
|
|||
|
|||
**Jeremy** -Product Manager- at Microsoft, answers why they took this decision in [this post](https://github.com/dotnet/aspnetcore/issues/54599#issuecomment-2004975574). |
|||
|
|||
 |
|||
|
|||
As a summary; |
|||
|
|||
**The change is due to a lack of maintenance of the Swagger library**, although it has seen some recent updates. This aims to reduce dependency on external tools and provide a streamlined, out-of-the-box experience for generating OpenAPI documentation for ASP.NET Core Web APIs. |
|||
|
|||
--- |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
What are the Benefits of the New OpenAI Package? |
|||
--------------------------------------------------------------- |
|||
|
|||
### Native Support and Reduced Dependency |
|||
|
|||
The new `Microsoft.AspNetCore.OpenApi` package provides first-class citizen support for OpenAPI. It reduces reliance on external tools like Swashbuckle or NSwag for basic documentation needs. The native implementation leverages source generators to reduce runtime overhead. |
|||
|
|||
### Simplified Configuration |
|||
|
|||
No need extra setup or 3rd party integrations. Just by defining controllers and endpoints, ASP.NET Core automatically generates OpenAPI specifications. |
|||
|
|||
### Well Integration with Minimal APIs |
|||
|
|||
[Minimal APIs](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis) introduced in .NET 6. There's an optimized built-in support for Minimal APIs. It automatically adds metadata for routes, request parameters, and responses. |
|||
|
|||
### Compatibility with Existing Tools |
|||
|
|||
You can still use the output of OpenAPI with Swagger or NSwag... So it doesn't mean that in this case you have only one option when you use OpenAPI. |
|||
|
|||
--- |
|||
|
|||
|
|||
|
|||
How to Use the New OpenAPI in .NET9? |
|||
------------------------------------ |
|||
|
|||
When you create a new ASP.NET Core project, you can see the below checkbox to add OpenAPI. |
|||
|
|||
 |
|||
|
|||
I created a new .NET 9 web project, I saw that OpenAPI had already been added. |
|||
|
|||
 |
|||
|
|||
## Add OpenAPI Support For Your Existing Project |
|||
|
|||
Upgrade your project to .NET 9 and add the required NuGet package [Microsoft.AspNetCore.OpenApi](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) |
|||
|
|||
``` |
|||
dotnet add package Microsoft.AspNetCore.OpenApi |
|||
``` |
|||
|
|||
### |
|||
|
|||
Add the following services and middleware in `Program.cs` |
|||
|
|||
``` |
|||
var builder = WebApplication.CreateBuilder(); |
|||
builder.Services.AddOpenApi(); //<<----- |
|||
var app = builder.Build(); |
|||
app.MapOpenApi(); //<<----- |
|||
app.MapGet("/", () => "Test"); |
|||
app.Run(); |
|||
``` |
|||
|
|||
Your OpenAPI document URL is [_https://localhost:7077/openapi/v1.json_](https://localhost:7077/openapi/v1.json) |
|||
|
|||
Change the port to your active port. This is how it looks like: |
|||
|
|||
 |
|||
|
|||
--- |
|||
|
|||
|
|||
|
|||
Alternative 3rd Party Tool: Scalar |
|||
================================== |
|||
|
|||
**Scalar** is an open-source API platform for RestAPI documentation. Also, it provides an interface for interacting with RESTful API. Generates interactive and user-friendly API documentation. Supports OpenAPI and Swagger specifications. It’s open-source with **7K stars** on GitHub. |
|||
|
|||
See the repo 👉 [https://github.com/scalar/scalar](https://github.com/scalar/scalar). |
|||
|
|||
|
|||
|
|||
That's all from the replacement of Swagger in .NET 9. |
|||
Happy coding 👨💻 |
|||
|
|||
|
|||
|
|||
**References** |
|||
|
|||
* [https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-9.0?view=aspnetcore-8.0#openapi](https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-9.0?view=aspnetcore-8.0#openapi) |
|||
|
|||
|
|||
@ -0,0 +1,202 @@ |
|||
# C# 13 Features |
|||
|
|||
C# 13 is the latest version of C# and it comes with a lot of new features. In this article, we will discuss some of the new features of C# 13. |
|||
|
|||
## `params` collections |
|||
|
|||
With the C# 13, method parameter with `params` keyword isn't limited to be an array. You can now use any collection type that implements `IEnumerable<T>` interface. |
|||
|
|||
Let's see how it can help us in our code. |
|||
|
|||
```csharp |
|||
public IEnumerable<int> GetOdds(params IEnumerable<int> numbers) |
|||
{ |
|||
foreach (var number in numbers) |
|||
{ |
|||
if (number % 2 != 0) |
|||
{ |
|||
Console.WriteLine(number); |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## New lock object |
|||
|
|||
I'm sure you have used `lock` statement in your code to synchronize access to a shared resource. With C# 13, you can now use a new lock object that is more efficient than the traditional lock object. |
|||
The new `Lock` type provides better thread synchronization through its API. When `Lock.EnterScope()` method is called, it returns a struct named `Scope` that contains a `Dispose` method. The `Dispose` method is called when the `Scope` object goes out of scope, which releases the lock. C# `using` statement recognizes the `Dispose` method and calls it automatically like it does with other `IDisposable` objects. |
|||
|
|||
It was something similar before: |
|||
```csharp |
|||
private object _lock = new(); |
|||
|
|||
public void DoSomething() |
|||
{ |
|||
lock (_lock) |
|||
{ |
|||
// Do something |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Now, you can use the new lock object like this: |
|||
```csharp |
|||
System.Threading.Lock x = new System.Threading.Lock(); |
|||
public void DoSomething() |
|||
{ |
|||
using (x.EnterScope()) |
|||
{ |
|||
// Do something |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## New escape sequence |
|||
In C# 13, a new escape sequence `\e` has been introduced to represent the `ESCAPE` character, Unicode `U+001B`. Previously, you had to use `\u001b` or `\x1b` to represent this character. The new `\e` escape sequence simplifies this process and avoids potential issues with hexadecimal digits following `\x1b`. |
|||
|
|||
> You can check [here](https://en.wikipedia.org/wiki/ANSI_escape_code#C0_control_codes) for ANSI escape codes. |
|||
|
|||
## Implicit index access |
|||
|
|||
The implicit "from the end" index operator, `^`, is now allowed in an object initializer expression. |
|||
|
|||
It was not possible before, but now you can do this: |
|||
|
|||
```csharp |
|||
var countdown = new TimerRemaining() |
|||
{ |
|||
buffer = |
|||
{ |
|||
[^1] = 0, |
|||
[^2] = 1, |
|||
[^3] = 2, |
|||
[^4] = 3, |
|||
[^5] = 4, |
|||
[^6] = 5, |
|||
[^7] = 6, |
|||
[^8] = 7, |
|||
[^9] = 8, |
|||
[^10] = 9 |
|||
} |
|||
}; |
|||
``` |
|||
|
|||
It's a great feature that makes the code more readable and maintainable. Still not a big deal, but it's nice to have it. |
|||
|
|||
## `ref` and `unsafe` in iterators and async methods |
|||
|
|||
In C# 13, the restrictions on using `ref` and `unsafe` constructs in iterators and async methods have been relaxed. Previously, you couldn't declare local `ref` variables or use unsafe contexts in these methods. Now, you can declare ref local variables and use unsafe contexts in async methods and iterators, provided they are not accessed across `await` or `yield` boundaries |
|||
|
|||
|
|||
This change allows for more expressive and efficient code, especially when working with types like `System.Span<T>` and `System.ReadOnlySpan<T>`. The compiler ensures that these constructs are used safely, and it will notify you if any safety rules are violated. |
|||
|
|||
You can read more about this feature on the [Microsoft Learn page](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-13.0/ref-unsafe-in-iterators-async). |
|||
|
|||
|
|||
|
|||
## More partial members |
|||
|
|||
In C# 13, the concept of partial members has been expanded to include partial properties and partial indexers. Previously, only methods could be defined as partial members. This means you can now split the definition of properties and indexers across multiple files, just like you could with methods. |
|||
|
|||
For example, you can declare a partial property in one part of your class and implement it in another part. Here's a simple illustration: |
|||
|
|||
```csharp |
|||
public partial class MyClass |
|||
{ |
|||
// Declaring declaration |
|||
public partial string MyProperty { get; set; } |
|||
} |
|||
|
|||
public partial class MyClass |
|||
{ |
|||
// Implementing declaration |
|||
private string _myProperty; |
|||
public partial string MyProperty |
|||
{ |
|||
get => _myProperty; |
|||
set => _myProperty = value; |
|||
} |
|||
} |
|||
``` |
|||
|
|||
This feature allows for better organization and modularization of your code, especially in large projects where different parts of a class might be implemented by different team members. |
|||
|
|||
## Overload resolution priority |
|||
|
|||
What does "Overload resolution priority" section mean in this page? |
|||
In C# 13, the OverloadResolutionPriority attribute allows library authors to specify which method overload should be preferred by the compiler when multiple overloads are available. This attribute helps avoid ambiguity and ensures that the most appropriate overload is chosen, even if it might not be the most obvious choice based on traditional overload resolution rules. |
|||
|
|||
This may be useful in scenarios where you have multiple overloads that are equally valid, but you want to prioritize one over the others. The attribute can be applied to a method or constructor to indicate its priority in the overload resolution process. It can prevent unexpected behavior and make your code more predictable and maintainable. |
|||
|
|||
|
|||
Let me show with an example: |
|||
```csharp |
|||
public class Example |
|||
{ |
|||
// Existing method |
|||
public void Display(string message = "Hello!") |
|||
{ |
|||
Console.WriteLine("Message: " + message); |
|||
} |
|||
|
|||
// New, more efficient method with higher priority |
|||
[OverloadResolutionPriority(1)] |
|||
public void Display(string message = "Hello!", int repeatCount = 3) |
|||
{ |
|||
for (int i = 0; i < repeatCount; i++) |
|||
{ |
|||
Console.WriteLine("Message: " + message); |
|||
} |
|||
} |
|||
} |
|||
|
|||
class Program |
|||
{ |
|||
static void Main() |
|||
{ |
|||
Example example = new Example(); |
|||
|
|||
// Normally, you can't compile this code because of ambiguity: |
|||
example.Display(); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Output: |
|||
``` |
|||
Message: Hello! |
|||
Message: Hello! |
|||
Message: Hello! |
|||
``` |
|||
|
|||
## The `field` keyword |
|||
|
|||
n C# 13, the `field` keyword is introduced as a preview feature to simplify property accessors. This keyword allows you to reference the compiler-generated backing `field` directly within a property accessor, eliminating the need to declare an explicit backing `field` in your type declaration. |
|||
|
|||
For example, instead of writing: |
|||
|
|||
```csharp |
|||
private int _value; |
|||
public int Value |
|||
{ |
|||
get => _value; |
|||
set => _value = value; |
|||
} |
|||
``` |
|||
|
|||
You can now write: |
|||
|
|||
```csharp |
|||
public int Value |
|||
{ |
|||
get => field; |
|||
set => field = value; |
|||
} |
|||
``` |
|||
|
|||
This makes your code cleaner and more concise. However, be cautious if you have a `field` named `field` in your class, as it could cause confusion. You can disambiguate by using `@field` or `this.field`. |
|||
|
|||
Make sure you're using the latest `LangVersion` in your `.csproj` project file to enable this feature. |
|||
```xml |
|||
<LangVersion>preview</LangVersion> |
|||
``` |
|||
@ -0,0 +1,165 @@ |
|||
# EF Core 9 LINQ & SQL translation |
|||
|
|||
EF Core improves the translation of LINQ queries to SQL with every release. EF Core 9 is no exception. This article will show you some of the improvements in EF Core 9. |
|||
|
|||
EF Core 9 includes a lot of improvements in LINQ to SQL translation. we don't cover all of them in this article. You can find more information in the [official release notes](https://learn.microsoft.com/en-us/ef/core/what-is-new/ef-core-9.0/whatsnew#linq-and-sql-translation). |
|||
|
|||
## Support for complex types |
|||
|
|||
### GroupBy |
|||
|
|||
EF Core now supports grouping by complex type instance. For example: |
|||
|
|||
```csharp |
|||
var groupedAddress = await context.Customers |
|||
.GroupBy(c => new { c.Address }) |
|||
.Select(g => new { g.Key, Count = g.Count() }) |
|||
.ToListAsync(); |
|||
``` |
|||
|
|||
Address is a complex type as a value object here. |
|||
|
|||
### ExecuteUpdate |
|||
|
|||
EF Core now supports updating a complex type. For example: |
|||
|
|||
```csharp |
|||
var newAddress = new Address("New Street", "New City", "New Country"); |
|||
|
|||
await context.Customers |
|||
.Where(e => e.Region == "Turkey") |
|||
.ExecuteUpdateAsync(s => s.SetProperty(b => b.Address, newAddress)); |
|||
``` |
|||
|
|||
EF Core updates each column of the complex type. |
|||
|
|||
## Prune unneeded elements from SQL |
|||
|
|||
Ef Core now translates LINQ queries to SQL more efficiently. It will remove unneeded elements from the SQL query and bring better performance. |
|||
|
|||
### Table pruning |
|||
|
|||
When you use table-per-hierarchy (TPH) inheritance, previously EF Core generated SQL queries that included JIONs to tables that were not needed. |
|||
|
|||
For example: |
|||
|
|||
```csharp |
|||
public class Order |
|||
{ |
|||
public int Id { get; set; } |
|||
... |
|||
|
|||
public Customer Customer { get; set; } |
|||
} |
|||
|
|||
public class DiscountedOrder : Order |
|||
{ |
|||
public double Discount { get; set; } |
|||
} |
|||
|
|||
public class Customer |
|||
{ |
|||
public int Id { get; set; } |
|||
... |
|||
|
|||
public List<Order> Orders { get; set; } |
|||
} |
|||
|
|||
public class AppContext : DbContext |
|||
{ |
|||
... |
|||
|
|||
protected override void OnModelCreating(ModelBuilder modelBuilder) |
|||
{ |
|||
modelBuilder.Entity<Order>().UseTptMappingStrategy(); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Consider the following query to get all customers with at least one order: |
|||
|
|||
```csharp |
|||
var customers = await context.Customers.Where(o => o.Orders.Any()).ToListAsync(); |
|||
``` |
|||
|
|||
Previously, EF Core generated the following SQL query: |
|||
|
|||
```sql |
|||
SELECT [c].[Id], [c].[Name] |
|||
FROM [Customers] AS [c] |
|||
WHERE EXISTS ( |
|||
SELECT 1 |
|||
FROM [Orders] AS [o] |
|||
LEFT JOIN [DiscountedOrders] AS [d] ON [o].[Id] = [d].[Id] |
|||
WHERE [c].[Id] = [o].[CustomerId]) |
|||
``` |
|||
|
|||
It included a JOIN to the `DiscountedOrders` table, which was not needed. In EF Core 9, the generated SQL query is: |
|||
|
|||
```sql |
|||
SELECT [c].[Id], [c].[Name] |
|||
FROM [Customers] AS [c] |
|||
WHERE EXISTS ( |
|||
SELECT 1 |
|||
FROM [Orders] AS [o] |
|||
WHERE [c].[Id] = [o].[CustomerId]) |
|||
``` |
|||
|
|||
## EF Core in ABP |
|||
|
|||
ABP Framework is built on top of the latest technologies. It will support EF Core 9 as soon as it is released. You can use the latest features of EF Core in your ABP applications. |
|||
|
|||
For example, you can use the `ExecuteUpdateAsync` method in your ABP application: |
|||
|
|||
```csharp |
|||
public class Book : FullAuditedAggregateRoot<Guid> |
|||
{ |
|||
public string Name { get; set; } |
|||
|
|||
public float Price { get; set; } |
|||
|
|||
public string Author { get; set; } |
|||
} |
|||
|
|||
public class AppContext : AbpDbContext<AppContext> |
|||
{ |
|||
public DbSet<Book> Books { get; set; } |
|||
|
|||
protected override void OnModelCreating(ModelBuilder modelBuilder) |
|||
{ |
|||
base.OnModelCreating(builder); |
|||
|
|||
builder.Entity<Book>(b => |
|||
{ |
|||
b.ToTable("Books"); |
|||
b.ConfigureByConvention(); |
|||
b.Property(x => x.Name).IsRequired().HasMaxLength(128); |
|||
b.Property(x => x.Author).IsRequired().HasMaxLength(64); |
|||
}); |
|||
} |
|||
} |
|||
|
|||
public class BookRepository : EfCoreRepository<AppContext, Book, Guid>, IBookRepository |
|||
{ |
|||
public BookRepository(IDbContextProvider<AppContext> dbContextProvider) |
|||
: base(dbContextProvider) |
|||
{ |
|||
} |
|||
|
|||
public async Task UpdatePriceByAuthorAsync(string author, float price) |
|||
{ |
|||
await (await GetDbSetAsync()) |
|||
.Where(b => b.Author == author) |
|||
.ExecuteUpdateAsync(b => b.SetProperty(x => x.Price, price)); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
* `FullAuditedAggregateRoot` is an aggregate root base class with auditing properties provided by ABP Framework. |
|||
* `IRepository` is a generic repository interface provided by ABP Framework that provides CRUD operations and you can use EF Core's API in your entity repository implementation. |
|||
|
|||
## References |
|||
|
|||
* [LINQ and SQL translation](https://learn.microsoft.com/en-us/ef/core/what-is-new/ef-core-9.0/whatsnew#linq-and-sql-translation) |
|||
* [ABP Entity Framework Core Integration](https://abp.io/docs/latest/framework/data/entity-framework-core) |
|||
* [ABP Entities](https://abp.io/docs/latest/framework/architecture/domain-driven-design/entities) |
|||
@ -0,0 +1,309 @@ |
|||
# ABP Global Assets - New way to bundle JavaScript/CSS files in Blazor WebAssembly app |
|||
|
|||
We have introduced a new feature in the ABP framework to bundle the `JavaScript/CSS` files in the Blazor wasm app. This feature is called `Global Assets`. |
|||
With this feature, you don't need to run the `abp bundle` command to manually create/maintain the `global.js` and `global.css` files in your Blazor wasm app. |
|||
|
|||
## How Global Assets works? |
|||
|
|||
The new `Blazor wasm app` has two projects: |
|||
|
|||
1. `MyProjectName` (ASP.NET Core app) |
|||
2. `MyProjectName.Client` (Blazor wasm app) |
|||
|
|||
The `MyProjectName` reference the `MyProjectName.Client` project, and will be the entry point of the application, which means the `MyProjectName` project will be the `host` project of the `MyProjectName.Client` project. |
|||
|
|||
The static/virtual files of `MyProjectName` can be accessed by the `MyProjectName.Client` project, so we can create dynamic global assets in the `MyProjectName` project and use them in the `MyProjectName.Client` project. |
|||
|
|||
## How it works in ABP? |
|||
|
|||
We have created a new package `WebAssembly.Theme.Bundling` for the theme `WebAssembly` module and used the `Volo.Abp.AspNetCore.Mvc.UI.Bundling.BundleContributor` to add `JavaScript/CSS` files to the bundling system. |
|||
|
|||
* LeptonXLiteTheme: `AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule` |
|||
* LeptonXTheme: `AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule` |
|||
* LeptonTheme: `AbpAspNetCoreComponentsWebAssemblyLeptonThemeBundlingModule` |
|||
* BasicTheme: `AbpAspNetCoreComponentsWebAssemblyBasicThemeBundlingModule` |
|||
|
|||
The new `ThemeBundlingModule` only depends on `AbpAspNetCoreComponentsWebAssemblyThemingBundlingModule(new package)`. It's an `abstractions module`, which only depends on `AbpAspNetCoreMvcUiBundlingAbstractionsModule`. |
|||
|
|||
We will get all `JavaScript/CSS` files on `OnApplicationInitializationAsync` method of `AbpAspNetCoreMvcUiBundlingModule` from bundling system and add them to `IDynamicFileProvider` service. After that, we can access the `JavaScript/CSS` files in the Blazor wasm app. |
|||
|
|||
## Add the Global Assets in the module |
|||
|
|||
If your module has `JavaScript/CSS` files that need to the bundling system, You have to create a new project(`YourModuleName.Blazor.WebAssembly.Bundling`) to your module solution, and reference the new project in the `MyProjectName` project and module dependencies. |
|||
|
|||
The new project should **only** depend on the `AbpAspNetCoreComponentsWebAssemblyThemingBundlingModule` and define `BundleContributor` classes to contribute the `JavaScript/CSS` files. |
|||
|
|||
> Q: The new project(`YourModuleName.Blazor.WebAssembly.Bundling`) doesn't have the `libs/myscript.js` and `libs/myscript.css` files why the files can be added to the bundling system? |
|||
|
|||
> A: Because the `MyProjectName.Client` will depend on the `MyBlazorModule(YourModuleName.Blazor)` that contains the `JavaScript/CSS` files, The `MyProjectName` is referencing the `MyProjectName.Client` project, so the `MyProjectName` project can access the `JavaScript/CSS` files in the `MyProjectName.Client` project and add them to the bundling system. |
|||
|
|||
```csharp |
|||
[DependsOn( |
|||
typeof(AbpAspNetCoreComponentsWebAssemblyThemingBundlingModule) |
|||
)] |
|||
public class MyBlazorWebAssemblyBundlingModule : AbpModule |
|||
{ |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
Configure<AbpBundlingOptions>(options => |
|||
{ |
|||
// Script Bundles |
|||
options.ScriptBundles.Get(BlazorWebAssemblyStandardBundles.Scripts.Global).AddContributors(typeof(MyModuleBundleScriptContributor)); |
|||
|
|||
// Style Bundles |
|||
options.ScriptBundles.Get(BlazorWebAssemblyStandardBundles.Scripts.Global).AddContributors(typeof(MyModuleBundleStyleBundleContributor)); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
```csharp |
|||
public class MyModuleBundleScriptContributor : BundleContributor |
|||
{ |
|||
public override void ConfigureBundle(BundleConfigurationContext context) |
|||
{ |
|||
context.Files.AddIfNotContains("_content/MyModule.Blazor/libs/myscript.js"); |
|||
} |
|||
} |
|||
|
|||
public class MyModuleBundleStyleBundleContributor : BundleContributor |
|||
{ |
|||
public override void ConfigureBundle(BundleConfigurationContext context) |
|||
{ |
|||
context.Files.AddIfNotContains("_content/MyModule.Blazor/libs/myscript.css"); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Use the Global Assets in the Blazor WASM |
|||
|
|||
### MyCompanyName.MyProjectName.Blazor |
|||
|
|||
Convert your `MyCompanyName.MyProjectName.Blazor` project to integrate the `ABP module` system and depend on the `AbpAspNetCoreMvcUiBundlingModule` and `AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule/AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule`: |
|||
|
|||
* The `AbpAspNetCoreMvcUiBundlingModule` uses to create the `JavaScript/CSS` files to virtual files. |
|||
* The `AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule/AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule` uses to add theme `JavaScript/CSS` to the bundling system. |
|||
|
|||
Here is how your project files look like: |
|||
|
|||
**`Program.cs`:** |
|||
|
|||
```csharp |
|||
public class Program |
|||
{ |
|||
public async static Task<int> Main(string[] args) |
|||
{ |
|||
//... |
|||
|
|||
var builder = WebApplication.CreateBuilder(args); |
|||
builder.Host.AddAppSettingsSecretsJson() |
|||
.UseAutofac() |
|||
.UseSerilog(); |
|||
await builder.AddApplicationAsync<MyProjectNameBlazorModule>(); |
|||
var app = builder.Build(); |
|||
await app.InitializeApplicationAsync(); |
|||
await app.RunAsync(); |
|||
return 0; |
|||
|
|||
//... |
|||
} |
|||
} |
|||
``` |
|||
|
|||
**`MyProjectNameBlazorModule.cs`:** |
|||
|
|||
```csharp |
|||
[DependsOn( |
|||
typeof(AbpAutofacModule), |
|||
typeof(AbpAspNetCoreMvcUiBundlingModule), |
|||
typeof(AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule/AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule) //Should be added! |
|||
)] |
|||
public class MyProjectNameBlazorModule : AbpModule |
|||
{ |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
//https://github.com/dotnet/aspnetcore/issues/52530 |
|||
Configure<RouteOptions>(options => |
|||
{ |
|||
options.SuppressCheckForUnhandledSecurityMetadata = true; |
|||
}); |
|||
|
|||
// Add services to the container. |
|||
context.Services.AddRazorComponents() |
|||
.AddInteractiveWebAssemblyComponents(); |
|||
} |
|||
|
|||
public override void OnApplicationInitialization(ApplicationInitializationContext context) |
|||
{ |
|||
var env = context.GetEnvironment(); |
|||
var app = context.GetApplicationBuilder(); |
|||
|
|||
// Configure the HTTP request pipeline. |
|||
if (env.IsDevelopment()) |
|||
{ |
|||
app.UseWebAssemblyDebugging(); |
|||
} |
|||
else |
|||
{ |
|||
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts. |
|||
app.UseHsts(); |
|||
} |
|||
|
|||
app.UseHttpsRedirection(); |
|||
app.MapAbpStaticAssets(); |
|||
app.UseRouting(); |
|||
app.UseAntiforgery(); |
|||
|
|||
app.UseConfiguredEndpoints(builder => |
|||
{ |
|||
builder.MapRazorComponents<App>() |
|||
.AddInteractiveWebAssemblyRenderMode() |
|||
.AddAdditionalAssemblies(WebAppAdditionalAssembliesHelper.GetAssemblies<MyProjectNameBlazorClientModule>()); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
**`MyCompanyName.MyProjectName.Blazor.csproj`:** |
|||
|
|||
```xml |
|||
<ItemGroup> |
|||
<PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.Server" Version="9.0.0.0" /> |
|||
<PackageReference Include="Volo.Abp.Autofac" Version="9.0.0" /> |
|||
<PackageReference Include="Volo.Abp.AspNetCore.Mvc.UI.Bundling" Version="9.0.0" /> |
|||
<PackageReference Include="Volo.Abp.AspNetCore.Components.WebAssembly.LeptonXLiteTheme.Bundling" Version="9.0.0" /> |
|||
<!-- <PackageReference Include="Volo.Abp.AspNetCore.Components.WebAssembly.LeptonXTheme.Bundling" Version="9.0.0" /> --> if you're using LeptonXTheme |
|||
<ProjectReference Include="..\MyProjectName.Blazor.Client\MyProjectName.Blazor.Client.csproj" /> |
|||
</ItemGroup> |
|||
``` |
|||
|
|||
### BlazorWebAssemblyBundlingModule in the ABP commercial |
|||
|
|||
Here is the list of `Bundling Modules` in the ABP commercial. If you're using the pro template, you should add them to the `MyCompanyName.MyProjectName.Blazor` project. |
|||
|
|||
| BundlingModules | Nuget Package | |
|||
|---------------------------------------------|-----------------------------------------------------| |
|||
| AbpAuditLoggingBlazorWebAssemblyBundlingModule | Volo.Abp.AuditLogging.Blazor.WebAssembly.Bundling | |
|||
| FileManagementBlazorWebAssemblyBundlingModule | Volo.FileManagement.Blazor.WebAssembly.Bundling | |
|||
| SaasHostBlazorWebAssemblyBundlingModule | Volo.Saas.Host.Blazor.WebAssembly.Bundling | |
|||
| ChatBlazorWebAssemblyBundlingModule | Volo.Chat.Blazor.WebAssembly.Bundling | |
|||
| CmsKitProAdminBlazorWebAssemblyBundlingModule | Volo.CmsKit.Pro.Admin.Blazor.WebAssembly.Bundling | |
|||
|
|||
|
|||
### MyCompanyName.MyProjectName.Blazor.Client |
|||
|
|||
1. Remove the `global.JavaScript/CSS` files from the `MyCompanyName.MyProjectName.Blazor`'s `wwwroot` folder. |
|||
2. Remove the `AbpCli:Bundle` section from the `appsettings.json` file. |
|||
3. Remove all BundleContributor classes that inherit from IBundleContributor. Then, create `MyProjectNameStyleBundleContributor` and `MyProjectNameScriptBundleContributor` classes to add your style and JavaScript files. Finally, add them to `AbpBundlingOptions`. |
|||
|
|||
|
|||
```cs |
|||
public class MyProjectNameStyleBundleContributor : BundleContributor |
|||
{ |
|||
public override void ConfigureBundle(BundleConfigurationContext context) |
|||
{ |
|||
context.Files.Add(new BundleFile("main.css", true)); |
|||
} |
|||
} |
|||
|
|||
|
|||
public class MyProjectNameScriptBundleContributor : BundleContributor |
|||
{ |
|||
public override void ConfigureBundle(BundleConfigurationContext context) |
|||
{ |
|||
context.Files.Add(new BundleFile("main.js", true)); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
```cs |
|||
Configure<AbpBundlingOptions>(options => |
|||
{ |
|||
var globalStyles = options.StyleBundles.Get(BlazorWebAssemblyStandardBundles.Styles.Global); |
|||
globalStyles.AddContributors(typeof(MyProjectNameStyleBundleContributor)); |
|||
|
|||
var globalScripts = options.ScriptBundles.Get(BlazorWebAssemblyStandardBundles.Scripts.Global); |
|||
globalScripts.AddContributors(typeof(MyProjectNameScriptBundleContributor)); |
|||
}); |
|||
``` |
|||
|
|||
## Use the Global Assets in the Blazor WebApp |
|||
|
|||
### MyCompanyName.MyProjectName.Blazor.WebApp |
|||
|
|||
Depending on the `AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule/AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule` in your `MyCompanyName.MyProjectName.Blazor.WebApp` project. |
|||
|
|||
* The `AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule/AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule` uses to add theme `JavaScript/CSS` to the bundling system. |
|||
|
|||
|
|||
### BlazorWebAssemblyBundlingModule in the ABP commercial |
|||
|
|||
Here is the list of `Bundling Modules` in the ABP commercial. If you're using the pro template, you should add them to the `MyCompanyName.MyProjectName.Blazor.WebApp` project. |
|||
|
|||
| BundlingModules | Nuget Package | |
|||
|---------------------------------------------|-----------------------------------------------------| |
|||
| AbpAuditLoggingBlazorWebAssemblyBundlingModule | Volo.Abp.AuditLogging.Blazor.WebAssembly.Bundling | |
|||
| FileManagementBlazorWebAssemblyBundlingModule | Volo.FileManagement.Blazor.WebAssembly.Bundling | |
|||
| SaasHostBlazorWebAssemblyBundlingModule | Volo.Saas.Host.Blazor.WebAssembly.Bundling | |
|||
| ChatBlazorWebAssemblyBundlingModule | Volo.Chat.Blazor.WebAssembly.Bundling | |
|||
| CmsKitProAdminBlazorWebAssemblyBundlingModule | Volo.CmsKit.Pro.Admin.Blazor.WebAssembly.Bundling | |
|||
|
|||
|
|||
### MyCompanyName.MyProjectName.Blazor.WebApp.Client |
|||
|
|||
1. Remove the `global.JavaScript/CSS` files from the `MyCompanyName.MyProjectName.Blazor.WebApp.Client`'s `wwwroot` folder. |
|||
2. Remove the `AbpCli:Bundle` section from the `appsettings.json` file. |
|||
3. Remove all BundleContributor classes that inherit from IBundleContributor. Then, create `MyProjectNameStyleBundleContributor` and `MyProjectNameScriptBundleContributor` classes to add your style and JavaScript files. Finally, add them to `AbpBundlingOptions`. |
|||
|
|||
```cs |
|||
public class MyProjectNameStyleBundleContributor : BundleContributor |
|||
{ |
|||
public override void ConfigureBundle(BundleConfigurationContext context) |
|||
{ |
|||
context.Files.Add(new BundleFile("main.css", true)); |
|||
} |
|||
} |
|||
|
|||
|
|||
public class MyProjectNameScriptBundleContributor : BundleContributor |
|||
{ |
|||
public override void ConfigureBundle(BundleConfigurationContext context) |
|||
{ |
|||
context.Files.Add(new BundleFile("main.js", true)); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
```cs |
|||
Configure<AbpBundlingOptions>(options => |
|||
{ |
|||
var globalStyles = options.StyleBundles.Get(BlazorWebAssemblyStandardBundles.Styles.Global); |
|||
globalStyles.AddContributors(typeof(MyProjectNameStyleBundleContributor)); |
|||
|
|||
var globalScripts = options.ScriptBundles.Get(BlazorWebAssemblyStandardBundles.Scripts.Global); |
|||
globalScripts.AddContributors(typeof(MyProjectNameScriptBundleContributor)); |
|||
}); |
|||
``` |
|||
|
|||
### Check the Global Assets |
|||
|
|||
Run the `MyProject` project and check the `https://localhost/global.js` and `https://localhost/global.css` files. You should be able to see the `JavaScript/CSS` files content from the Bundling system: |
|||
|
|||
 |
|||
|
|||
## GlobalAssets(AbpBundlingGlobalAssetsOptions) |
|||
|
|||
You can configure the JavaScript and CSS file names in the `GlobalAssets` property of the `AbpBundlingOptions` class. |
|||
|
|||
The default values are `global.js` and `global.css`. |
|||
|
|||
## Conclusion |
|||
|
|||
With the new `Global Assets` feature, you can easily bundle the `JavaScript/CSS` files in the Blazor wasm app. This feature is very useful for the Blazor wasm app, and it will save you a lot of time and effort. We hope you will enjoy this feature and use it in your projects. |
|||
|
|||
## References |
|||
|
|||
* [Virtual Files](https://docs.abp.io/en/abp/latest/Virtual-Files) |
|||
* [Bundle Contributors](https://abp.io/docs/latest/framework/ui/mvc-razor-pages/bundling-minification#bundle-contributors) |
|||
* [Global Assets Pull Request](https://github.com/abpframework/abp/pull/19968) |
|||
|
|||
|
After Width: | Height: | Size: 360 KiB |
@ -0,0 +1,385 @@ |
|||
# How to Use OpenAI API with ABP Framework |
|||
|
|||
In this article, I will show you how to integrate and use the [OpenAI API](https://github.com/openai/openai-dotnet?tab=readme-ov-file#getting-started) with the [ABP Framework](https://abp.io/). We will explore step-by-step how these technologies can work together to enhance your application with powerful AI capabilities, such as natural language processing, image generation, and more. |
|||
|
|||
 |
|||
|
|||
## Creating an ABP Project |
|||
|
|||
To begin integrating OpenAI API with ABP Framework, you first need to create an ABP project. Follow these steps to create and set up your ABP project: |
|||
### Step 1: Install ABP CLI |
|||
|
|||
The ABP CLI is a command-line interface tool that helps you create and manage ABP projects easily. To install the ABP CLI, run the following command in your terminal: |
|||
|
|||
```bash |
|||
dotnet tool install -g Volo.Abp.Studio.Cli |
|||
``` |
|||
|
|||
### Step 2: Create a New ABP Project |
|||
|
|||
Once you have installed the ABP CLI, you can create a new ABP project using the following command: |
|||
|
|||
```bash |
|||
abp new Acme.OpenAIIntegration -t app --ui-framework mvc --database-provider ef -dbms PostgreSQL --csf |
|||
``` |
|||
|
|||
> This command will generate a complete ABP project with an [MVC UI](https://abp.io/docs/latest/framework/ui/mvc-razor-pages/overall). The examples provided in this article make use of UI controllers for demonstration purposes. However, the same approach can easily be applied to other UI types supported by ABP, such as Blazor or Angular. You can find other options [here](https://abp.io/docs/latest/cli). |
|||
## OpenAI Integration Setup |
|||
|
|||
To begin integrating OpenAI API with ABP Framework, follow these steps: |
|||
|
|||
### Step 1: Create an API Key |
|||
|
|||
To use the OpenAI services, you first need an API key. To obtain one, first [create a new OpenAI account](https://platform.openai.com/signup) or [log in](https://platform.openai.com/login). Next, navigate to the [API key page](https://platform.openai.com/account/api-keys) and select "Create new secret key", optionally naming the key. Make sure to save your API key somewhere safe and do not share it with anyone. |
|||
|
|||
This key will be used to authenticate your application when making requests to the OpenAI endpoints. |
|||
|
|||
### Step 2: Adding *Microsoft.Extensions.AI* Package |
|||
|
|||
To integrate OpenAI API with ABP, we use [Microsoft.Extensions.AI](https://www.nuget.org/packages/Microsoft.Extensions.AI.OpenAI/). This package offers a unified API for integrating AI services, making it easy for developers to work with different AI providers. You can find more details in [this blog post](https://devblogs.microsoft.com/dotnet/introducing-microsoft-extensions-ai-preview/). |
|||
|
|||
To begin integrating OpenAI API with ABP Framework, follow these steps: |
|||
|
|||
1. Add the **Microsoft.Extensions.AI** and **Microsoft.Extensions.AI.OpenAI** (used to interact specifically with OpenAI services. Additionally, this package has alternatives like [Azure OpenAI](https://www.nuget.org/packages/Microsoft.Extensions.AI.OpenAI/), [Azure AI Inference](https://www.nuget.org/packages/Microsoft.Extensions.AI.AzureAIInference/), and [Ollama](https://www.nuget.org/packages/Microsoft.Extensions.AI.Ollama/), offering flexibility for developers to choose the AI provider that best fits their needs) packages: |
|||
|
|||
```bash |
|||
dotnet add package Microsoft.Extensions.AI --prerelease |
|||
dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease |
|||
``` |
|||
|
|||
2. Add the required configuration to the `appsettings.json` file located inside the `Acme.OpenAIIntegration.Web` project and dependencies to your `ConfigureServices` method: |
|||
|
|||
```json |
|||
"AI": { |
|||
"OpenAI": { |
|||
"Key": "YOUR-API-KEY", |
|||
"Chat": { |
|||
"ModelId": "gpt-4o-mini" |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
> Replace the value of the `Key` with your OpenAI API key. |
|||
|
|||
Next, add the following code to the `ConfigureServices` method in `OpenAIIntegrationBlazorModule`: |
|||
|
|||
```csharp |
|||
context.Services.AddSingleton(new OpenAIClient(configuration["AI:OpenAI:Key"])); |
|||
|
|||
context.Services.AddChatClient(services => |
|||
services.GetRequiredService<OpenAIClient>().AsChatClient(configuration["AI:OpenAI:Chat:ModelId"] ?? "gpt-4o-mini")); |
|||
``` |
|||
|
|||
## Creating a Sample Page |
|||
|
|||
To demonstrate the use of OpenAI API, let's create a page named `Sample` in the `Acme.OpenAIIntegration.Web` project: |
|||
|
|||
Create a `Sample` folder under the `Pages` folder of the `Acme.OpenAIIntegration.Web` project. Add a new Razor Page by right-clicking the `Sample` folder then selecting `Add > Razor Page`. Name it `Index`. |
|||
|
|||
Open the `Index.cshtml` and change the whole content as shown below: |
|||
|
|||
> Note: This example demonstrates a simple implementation of a sample page that interacts with the OpenAI API, covering chat, [retrieval-augmented generation (RAG)](https://github.com/openai/openai-dotnet?tab=readme-ov-file#how-to-use-assistants-with-retrieval-augmented-generation-rag), and image generation features. Each example is explained in detail in the next section, so feel free to continue for a better understanding of the steps and logic involved. |
|||
|
|||
```html |
|||
@page |
|||
@model Acme.OpenAIIntegration.Web.Pages.Sample |
|||
@{ |
|||
ViewData["Title"] = "OpenAI API Demonstration"; |
|||
} |
|||
|
|||
<h1>@ViewData["Title"]</h1> |
|||
|
|||
<br/><br/> |
|||
|
|||
<div class="row"> |
|||
<div class="col-md-4"> |
|||
<h2>Chat Example</h2> |
|||
<form method="post" asp-page-handler="Chat"> |
|||
<div class="form-group"> |
|||
<label asp-for="ChatInput">Enter your message:</label> |
|||
<textarea asp-for="ChatInput" class="form-control" rows="4"></textarea> |
|||
</div> |
|||
<button type="submit" class="btn btn-primary mt-2">Send</button> |
|||
</form> |
|||
@if (!string.IsNullOrEmpty(Model.ChatResponse)) |
|||
{ |
|||
<h3 class="mt-3">Response:</h3> |
|||
<p>@Model.ChatResponse</p> |
|||
} |
|||
</div> |
|||
|
|||
<div class="col-md-4"> |
|||
<h2>RAG Example</h2> |
|||
<form method="post" asp-page-handler="RAG"> |
|||
<div class="form-group mt-2"> |
|||
<label asp-for="RAGQuery">Query:</label> |
|||
<input asp-for="RAGQuery" class="form-control" /> |
|||
</div> |
|||
<button type="submit" class="btn btn-primary mt-2">Ask</button> |
|||
</form> |
|||
@if (!string.IsNullOrEmpty(Model.RAGResponse)) |
|||
{ |
|||
<h3 class="mt-3">Result:</h3> |
|||
<p>@Model.RAGResponse</p> |
|||
} |
|||
</div> |
|||
|
|||
<div class="col-md-4"> |
|||
<h2>Image Generation Example</h2> |
|||
<form method="post" asp-page-handler="ImageGeneration"> |
|||
<div class="form-group"> |
|||
<label asp-for="ImagePrompt">Image Description:</label> |
|||
<input asp-for="ImagePrompt" class="form-control" /> |
|||
</div> |
|||
<button type="submit" class="btn btn-primary mt-2">Generate Image</button> |
|||
</form> |
|||
@if (Model.GeneratedImageBytes != null) |
|||
{ |
|||
<h3 class="mt-3">Generated Image:</h3> |
|||
<img src="data:image/png;base64,@Convert.ToBase64String(Model.GeneratedImageBytes)" alt="Generated image" class="img-fluid mt-2" /> |
|||
} |
|||
</div> |
|||
</div> |
|||
``` |
|||
|
|||
`Index.cshtml.cs` content should be like that: |
|||
|
|||
```csharp |
|||
using System; |
|||
using System.ClientModel; |
|||
using System.IO; |
|||
using System.Text; |
|||
using System.Threading; |
|||
using System.Threading.Tasks; |
|||
using Microsoft.AspNetCore.Mvc; |
|||
using Microsoft.AspNetCore.Mvc.RazorPages; |
|||
using Microsoft.Extensions.AI; |
|||
using OpenAI; |
|||
using OpenAI.Assistants; |
|||
using OpenAI.Files; |
|||
using OpenAI.Images; |
|||
|
|||
namespace Acme.OpenAIIntegration.Web.Pages; |
|||
|
|||
public class Sample : PageModel |
|||
{ |
|||
[BindProperty] |
|||
public string ChatInput { get; set; } |
|||
public string ChatResponse { get; set; } |
|||
|
|||
[BindProperty] |
|||
public string RAGQuery { get; set; } |
|||
public string RAGResponse { get; set; } |
|||
|
|||
[BindProperty] |
|||
public string ImagePrompt { get; set; } |
|||
public byte[] GeneratedImageBytes { get; set; } |
|||
|
|||
private readonly IChatClient _chatClient; |
|||
private readonly OpenAIClient _openAiClient; |
|||
|
|||
public Sample( |
|||
IChatClient chatClient, |
|||
OpenAIClient openAiClient) |
|||
{ |
|||
_chatClient = chatClient; |
|||
_openAiClient = openAiClient; |
|||
} |
|||
|
|||
public async Task<IActionResult> OnPostChatAsync() |
|||
{ |
|||
ChatResponse = $"Chat response: {(await _chatClient.CompleteAsync(ChatInput)).Message}"; |
|||
return Page(); |
|||
} |
|||
|
|||
public async Task<IActionResult> OnPostRAGAsync() |
|||
{ |
|||
#pragma warning disable OPENAI001 |
|||
var fileClient = _openAiClient.GetOpenAIFileClient(); |
|||
var assistantClient = _openAiClient.GetAssistantClient(); |
|||
|
|||
using var document = BinaryData.FromBytes(GetExceptionHandlingDocumentContent().ToArray()).ToStream(); |
|||
var exceptionHandlingDoc = await fileClient.UploadFileAsync( |
|||
document, |
|||
"ExceptionHandling.md", |
|||
FileUploadPurpose.Assistants); |
|||
|
|||
AssistantCreationOptions assistantOptions = new() |
|||
{ |
|||
Name = "Exception Handling Assistant", |
|||
Instructions = |
|||
""" |
|||
This assistant helps you with exception handling in ABP Framework. You can ask questions about exception handling and get answers. |
|||
|
|||
- Do not make any assumptions when asked for information that is not in the document |
|||
- Give the most accurate information possible |
|||
- Give short(max 1-2 sentence) and concise answers |
|||
- Do not provide file citations |
|||
""", |
|||
|
|||
Tools = |
|||
{ |
|||
new FileSearchToolDefinition(), |
|||
}, |
|||
ToolResources = new() |
|||
{ |
|||
FileSearch = new() |
|||
{ |
|||
NewVectorStores = |
|||
{ |
|||
new VectorStoreCreationHelper([exceptionHandlingDoc.Value.Id]), |
|||
} |
|||
} |
|||
}, |
|||
}; |
|||
|
|||
var assistant = await assistantClient.CreateAssistantAsync("gpt-4o", assistantOptions); |
|||
|
|||
ThreadCreationOptions threadOptions = new() |
|||
{ |
|||
InitialMessages = { RAGQuery } |
|||
}; |
|||
|
|||
ThreadRun threadRun = assistantClient.CreateThreadAndRun(assistant.Value.Id, threadOptions); |
|||
|
|||
do |
|||
{ |
|||
Thread.Sleep(TimeSpan.FromSeconds(1)); |
|||
threadRun = assistantClient.GetRun(threadRun.ThreadId, threadRun.Id); |
|||
} while (!threadRun.Status.IsTerminal); |
|||
|
|||
CollectionResult<ThreadMessage> messages |
|||
= assistantClient.GetMessages(threadRun.ThreadId, |
|||
new MessageCollectionOptions() { Order = MessageCollectionOrder.Ascending }); |
|||
|
|||
var response = new StringBuilder(); |
|||
|
|||
foreach (var message in messages) |
|||
{ |
|||
response.AppendLine($"[{message.Role.ToString().ToUpper()}]: "); |
|||
foreach (var contentItem in message.Content) |
|||
{ |
|||
if (!string.IsNullOrEmpty(contentItem.Text)) |
|||
{ |
|||
response.AppendLine(contentItem.Text); |
|||
|
|||
if (contentItem.TextAnnotations.Count > 0) |
|||
{ |
|||
response.AppendLine(""); |
|||
} |
|||
} |
|||
} |
|||
|
|||
response.AppendLine(""); |
|||
#pragma warning restore OPENAI001 |
|||
} |
|||
|
|||
RAGResponse = response.ToString(); |
|||
|
|||
return Page(); |
|||
} |
|||
|
|||
public async Task<IActionResult> OnPostImageGenerationAsync() |
|||
{ |
|||
var client = _openAiClient.GetImageClient("dall-e-3"); |
|||
|
|||
var image = await client.GenerateImageAsync(ImagePrompt, new ImageGenerationOptions |
|||
{ |
|||
ResponseFormat = GeneratedImageFormat.Bytes |
|||
}); |
|||
|
|||
var imageBytes = image.Value.ImageBytes; |
|||
|
|||
using var memoryStream = new MemoryStream(); |
|||
await imageBytes.ToStream().CopyToAsync(memoryStream); |
|||
GeneratedImageBytes = memoryStream.ToArray(); |
|||
|
|||
return Page(); |
|||
} |
|||
|
|||
public ReadOnlySpan<byte> GetExceptionHandlingDocumentContent() |
|||
{ |
|||
return """ |
|||
# Exception Handling |
|||
|
|||
ABP provides a built-in infrastructure and offers a standard model for handling exceptions. |
|||
|
|||
* Automatically **handles all exceptions** and sends a standard **formatted error message** to the client for an API/AJAX request. |
|||
* Automatically hides **internal infrastructure errors** and returns a standard error message. |
|||
* Provides an easy and configurable way to **localize** exception messages. |
|||
* Automatically maps standard exceptions to **HTTP status codes** and provides a configurable option to map custom exceptions. |
|||
|
|||
## Automatic Exception Handling |
|||
|
|||
`AbpExceptionFilter` handles an exception if **any of the following conditions** are met: |
|||
|
|||
* Exception is thrown by a **controller action** which returns an **object result** (not a view result). |
|||
* The request is an AJAX request (`X-Requested-With` HTTP header value is `XMLHttpRequest`). |
|||
* Client explicitly accepts the `application/json` content type (via `accept` HTTP header). |
|||
|
|||
If the exception is handled it's automatically **logged** and a formatted **JSON message** is returned to the client. |
|||
|
|||
## Business Exceptions |
|||
|
|||
Most of your own exceptions will be business exceptions. The `IBusinessException` interface is used to mark an exception as a business exception. |
|||
|
|||
`BusinessException` implements the `IBusinessException` interface in addition to the `IHasErrorCode`, `IHasErrorDetails` and `IHasLogLevel` interfaces. The default log level is `Warning`. |
|||
|
|||
Usually you have an error code related to a particular business exception. For example: |
|||
|
|||
````C# |
|||
throw new BusinessException(QaErrorCodes.CanNotVoteYourOwnAnswer); |
|||
```` |
|||
|
|||
### User Friendly Exception |
|||
|
|||
If an exception implements the `IUserFriendlyException` interface, then ABP does not change it's `Message` and `Details` properties and directly send it to the client. |
|||
|
|||
`UserFriendlyException` class is the built-in implementation of the `IUserFriendlyException` interface. Example usage: |
|||
|
|||
````C# |
|||
throw new UserFriendlyException( |
|||
"Username should be unique!" |
|||
); |
|||
```` |
|||
* The `IUserFriendlyException` interface is derived from the `IBusinessException` and the `UserFriendlyException` class is derived from the `BusinessException` class. |
|||
|
|||
"""u8; |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Running the Application |
|||
|
|||
After completing the setup, you can run the application using the following command: |
|||
|
|||
```bash |
|||
dotnet run --project ./src/Acme.OpenAIIntegration.Web |
|||
``` |
|||
|
|||
Once the application is running, open your browser and navigate to `/Sample`. You should see the `Sample` page we created, which contains sections for Chat, RAG (Retrieval-Augmented Generation), and Image Generation. You can find the screenshot of the page below: |
|||
|
|||
 |
|||
|
|||
## Examples Overview |
|||
|
|||
To showcase the integration of the OpenAI API with the ABP Framework, we implemented three different examples: |
|||
|
|||
1. **Chat Example**: This example demonstrates how to use OpenAI's chat capabilities by allowing users to enter a message and receive an AI-generated response. The implementation involves setting up a simple form on the `Sample` page where users can input their message. The form submission triggers the `OnPostChatAsync` method, which uses the `IChatClient` to generate a response. |
|||
|
|||
 |
|||
|
|||
2. **Retrieval-Augmented Generation (RAG) Example**: In this example, we use OpenAI to answer user queries by referencing custom documents uploaded to the OpenAI API. The implementation involves uploading a document using the `OpenAIFileClient` and creating an assistant with specific instructions to handle the uploaded content. In this case, the document is a section from ABP's Exception Handling documentation, which includes examples on how ABP handles exceptions, user-friendly error messages, and business exceptions. Users can input their query on the `Sample` page, and the `OnPostRAGAsync` method processes the query to generate precise answers based on the document content. If users ask questions that are not covered in the document, the assistant clearly indicates that the information is not available, as per the instructions provided. For example, when asked about `Object Extensions`, the response begins with: "The uploaded document does not contain information about `Object Extensions`...". This demonstrates how the assistant adheres to the provided instructions. You can also find this example illustrated in the GIF below. |
|||
|
|||
 |
|||
|
|||
 |
|||
|
|||
3. **Image Generation Example**: This example leverages the [DALL-E](https://openai.com/index/dall-e-3/) model to generate images based on user-provided prompts. On the `Sample` page, users can provide a description of the image they want to generate, and the `OnPostImageGenerationAsync` method uses the `OpenAIClient` to generate the image. |
|||
|
|||
 |
|||
|
|||
## Conclusion |
|||
|
|||
In this article, we covered how to integrate the OpenAI API with the ABP Framework by creating a sample project, setting up the OpenAI services, and implementing examples for conversational AI, knowledge-based assistance, and image generation. By following these steps, you can add powerful AI-driven capabilities to your application, making it more interactive, intelligent, and capable of meeting user needs effectively. |
|||
|
After Width: | Height: | Size: 147 KiB |
|
After Width: | Height: | Size: 565 KiB |
|
After Width: | Height: | Size: 954 KiB |
|
After Width: | Height: | Size: 160 KiB |
|
After Width: | Height: | Size: 220 KiB |
|
After Width: | Height: | Size: 49 KiB |
@ -0,0 +1,234 @@ |
|||
# The new Unit Test structure in ABP application |
|||
|
|||
A typical ABP modular project usually consists of three main projects: `Application`, `Domain`, and `EntityFrameworkCore/MongoDB`. In these projects, we may provide many services that require unit testing. |
|||
|
|||
Using abstract unit test classes involves first writing tests in the `Application` and `Domain` layers that are independent of the storage technology, ensuring the correctness of core business logic. These abstract tests are then implemented in `EntityFrameworkCore` or `MongoDB`. The benefits of this approach include: |
|||
|
|||
1. **Reduced Coupling**: Core logic tests do not depend on specific storage technologies, so switching databases does not require rewriting test code. |
|||
2. **Better Isolation**: Focuses on verifying business logic correctness, avoiding interference from database operations. |
|||
3. **Increased Reusability**: The same abstract tests can be reused with different storage implementations. |
|||
4. **Easier Maintenance and Extensibility**: Different storage implementations can be extended independently without breaking existing tests. |
|||
5. **Faster and More Reliable Tests**: Reduces dependency on databases, making tests faster and more stable. |
|||
|
|||
## How to migrate old unit tests to the new unit test structure |
|||
|
|||
Assume our project name is `MyCompanyName.MyProjectName`. |
|||
|
|||
### Changes to the `MyCompanyName.MyProjectName.Application.Tests` project: |
|||
|
|||
1. Remove the `MyCompanyName.MyProjectName.Application.Tests` project's `MyProjectNameApplicationCollection` class. |
|||
2. Modify the `MyCompanyName.MyProjectName.Application.Tests` project's `MyProjectNameApplicationTestBase` class. |
|||
|
|||
```csharp |
|||
public abstract class MyProjectNameApplicationTestBase<TStartupModule> : MyProjectNameTestBase<TStartupModule> |
|||
where TStartupModule : IAbpModule |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
3. Modify the `MyCompanyName.MyProjectName.Application.Tests` project's unit test classes to become abstract unit test classes, such as: `SampleAppServiceTests`. |
|||
|
|||
```csharp |
|||
public abstract class SampleAppServiceTests<TStartupModule> : MyProjectNameApplicationTestBase<TStartupModule> |
|||
where TStartupModule : IAbpModule |
|||
{ |
|||
[Fact] |
|||
public async Task Initial_Data_Should_Contain_Admin_User() |
|||
{ |
|||
//... |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Changes to the `MyCompanyName.MyProjectName.Domain.Tests` project: |
|||
|
|||
1. Remove the `MyCompanyName.MyProjectName.Domain.Tests` project's `MyProjectNameDomainCollection` class. |
|||
2. Modify the `MyCompanyName.MyProjectName.Domain.Tests` project's `MyProjectNameDomainTestBase` class. |
|||
|
|||
```csharp |
|||
public abstract class MyProjectNameDomainTestBase<TStartupModule> : MyProjectNameTestBase<TStartupModule> |
|||
where TStartupModule : IAbpModule |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
3. Modify the `MyCompanyName.MyProjectName.Domain.Tests` project's unit test classes to become abstract unit test classes, such as: `SampleDomainTests`. |
|||
|
|||
```csharp |
|||
public abstract class SampleDomainTests<TStartupModule> : MyProjectNameDomainTestBase<TStartupModule> |
|||
where TStartupModule : IAbpModule |
|||
{ |
|||
[Fact] |
|||
public async Task Should_Set_Email_Of_A_User() |
|||
{ |
|||
//... |
|||
} |
|||
} |
|||
``` |
|||
|
|||
4. Modify the `MyCompanyName.MyProjectName.Domain.Tests` project's `csproj` and module class. Remove references to `EntityFrameworkCore/MongoDB`. |
|||
|
|||
`MyCompanyName.MyProjectName.Domain.Tests.csproj`: |
|||
```xml |
|||
<Project Sdk="Microsoft.NET.Sdk"> |
|||
|
|||
//... |
|||
|
|||
<ItemGroup> |
|||
<ProjectReference Include="..\..\src\MyCompanyName.MyProjectName.Domain\MyCompanyName.MyProjectName.Domain.csproj" /> |
|||
<ProjectReference Include="..\MyCompanyName.MyProjectName.TestBase\MyCompanyName.MyProjectName.TestBase.csproj" /> |
|||
</ItemGroup> |
|||
</Project> |
|||
|
|||
``` |
|||
|
|||
`MyProjectNameDomainTestModule.cs`: |
|||
|
|||
```csharp |
|||
[DependsOn( |
|||
typeof(MyProjectNameDomainModule), |
|||
typeof(MyProjectNameTestBaseModule) |
|||
)] |
|||
public class MyProjectNameDomainTestModule : AbpModule |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
### Changes to the `MyCompanyName.MyProjectName.EntityFrameworkCore.Tests` project: |
|||
|
|||
Here, we need to create implementation classes for all abstract unit tests. |
|||
|
|||
```csharp |
|||
[Collection(MyProjectNameTestConsts.CollectionDefinitionName)] |
|||
public class EfCoreSampleAppServiceTests : SampleAppServiceTests<MyProjectNameEntityFrameworkCoreTestModule> |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
```csharp |
|||
[Collection(MyProjectNameTestConsts.CollectionDefinitionName)] |
|||
public class EfCoreSampleDomainTests : SampleDomainTests<MyProjectNameEntityFrameworkCoreTestModule> |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
We also need to modify the project's dependencies and module class, which should directly or indirectly reference the `Application` and `Domain` test projects. |
|||
|
|||
`MyCompanyName.MyProjectName.EntityFrameworkCore.Tests.csproj`: |
|||
|
|||
```xml |
|||
<Project Sdk="Microsoft.NET.Sdk"> |
|||
|
|||
//... |
|||
|
|||
<ItemGroup> |
|||
<ProjectReference Include="..\..\src\MyCompanyName.MyProjectName.EntityFrameworkCore\MyCompanyName.MyProjectName.EntityFrameworkCore.csproj" /> |
|||
<ProjectReference Include="..\MyCompanyName.MyProjectName.Application.Tests\MyCompanyName.MyProjectName.Application.Tests.csproj" /> |
|||
<ProjectReference Include="..\..\..\..\..\framework\src\Volo.Abp.EntityFrameworkCore.Sqlite\Volo.Abp.EntityFrameworkCore.Sqlite.csproj" /> |
|||
</ItemGroup> |
|||
</Project> |
|||
``` |
|||
|
|||
`MyProjectNameEntityFrameworkCoreTestModule.cs`: |
|||
|
|||
```csharp |
|||
[DependsOn( |
|||
typeof(MyProjectNameApplicationTestModule), |
|||
typeof(MyProjectNameEntityFrameworkCoreModule), |
|||
typeof(AbpEntityFrameworkCoreSqliteModule) |
|||
)] |
|||
public class MyProjectNameEntityFrameworkCoreTestModule : AbpModule |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
### Changes to the `MyCompanyName.MyProjectName.MongoDB.Tests` project (skip this step if not using MongoDB): |
|||
|
|||
Like the `EntityFrameworkCore` project, we need to create implementation classes for all abstract unit tests and modify the project's dependencies and module class. |
|||
|
|||
```csharp |
|||
[Collection(MyProjectNameTestConsts.CollectionDefinitionName)] |
|||
public class MongoDBSampleAppServiceTests : SampleAppServiceTests<MyProjectNameMongoDbTestModule> |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
```csharp |
|||
[Collection(MyProjectNameTestConsts.CollectionDefinitionName)] |
|||
public class MongoDBSampleDomainTests : SampleDomainTests<MyProjectNameMongoDbTestModule> |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
```xml |
|||
<Project Sdk="Microsoft.NET.Sdk"> |
|||
|
|||
//... |
|||
|
|||
<ItemGroup> |
|||
<ProjectReference Include="..\..\src\MyCompanyName.MyProjectName.MongoDB\MyCompanyName.MyProjectName.MongoDB.csproj" /> |
|||
<ProjectReference Include="..\MyCompanyName.MyProjectName.Application.Tests\MyCompanyName.MyProjectName.Application.Tests.csproj" /> |
|||
</ItemGroup> |
|||
</Project> |
|||
``` |
|||
|
|||
```csharp |
|||
[DependsOn( |
|||
typeof(MyProjectNameApplicationTestModule), |
|||
typeof(MyProjectNameMongoDbModule) |
|||
)] |
|||
public class MyProjectNameMongoDbTestModule : AbpModule |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
### Changes to the `MyCompanyName.MyProjectName.Web.Tests` project: |
|||
|
|||
We need to reference the `EntityFrameworkCore/MongoDB` test projects in this test project. |
|||
|
|||
```xml |
|||
<Project Sdk="Microsoft.NET.Sdk"> |
|||
|
|||
//... |
|||
|
|||
<ItemGroup> |
|||
<ProjectReference Include="..\MyCompanyName.MyProjectName.Application.Tests\MyCompanyName.MyProjectName.Application.Tests.csproj" /> |
|||
<ProjectReference Include="..\..\src\MyCompanyName.MyProjectName.Web\MyCompanyName.MyProjectName.Web.csproj" /> |
|||
<ProjectReference Include="..\..\..\..\..\framework\src\Volo.Abp.AspNetCore.TestBase\Volo.Abp.AspNetCore.TestBase.csproj" /> |
|||
<ProjectReference Include="..\MyCompanyName.MyProjectName.EntityFrameworkCore.Tests\MyCompanyName.MyProjectName.EntityFrameworkCore.Tests.csproj" /> |
|||
</ItemGroup> |
|||
</Project> |
|||
``` |
|||
|
|||
```csharp |
|||
[DependsOn( |
|||
typeof(AbpAspNetCoreTestBaseModule), |
|||
typeof(MyProjectNameWebModule), |
|||
typeof(MyProjectNameApplicationTestModule), |
|||
typeof(MyProjectNameEntityFrameworkCoreTestModule) |
|||
)] |
|||
public class MyProjectNameWebTestModule : AbpModule |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
We no longer need the `MyProjectNameWebCollection` class in this project. Please delete it and use `[Collection(MyProjectNameTestConsts.CollectionDefinitionName)]` instead. |
|||
|
|||
## Conclusion |
|||
|
|||
This is our new unit test structure. Decoupling unit tests from storage technologies ensures the independence of business logic and allows easy switching between storage implementations. Abstract unit test classes improve test reusability, maintainability, and efficiency, reducing refactoring costs and providing flexibility for future tech updates. |
|||
|
|||
## References |
|||
|
|||
- [Unit Test](https://abp.io/docs/latest/testing/unit-tests) |
|||
- [Abstract all db-related unit tests](https://github.com/abpframework/abp/pull/17880) |
|||
@ -0,0 +1,84 @@ |
|||
# Forwarded Headers |
|||
|
|||
Reverse proxies and load balancers play a crucial role in modern web application architectures. When an application is deployed behind these proxies and load balancers, several specific issues can arise. This document will discuss these issues in detail, explain how ASP.NET Core's forwarded headers middleware can address them, and provide a code example for configuring forwarded headers in an ABP application. |
|||
|
|||
## Possible problem in a Reverse Proxy Environment |
|||
|
|||
When requests pass through a reverse proxy or load balancer, the following common issues can occur: |
|||
|
|||
### 1. Loss of Original Request Information |
|||
|
|||
A reverse proxy or load balancer typically modifies the original HTTP request headers. For example, the proxy may replace the client's `X-Forwarded-For` header, or the `Host` header might be set to the proxy's address. This can result in the backend application being unable to directly access the client's IP address, the true hostname, and the protocol used. |
|||
|
|||
### 2. HTTPS vs HTTP Protocol Confusion |
|||
|
|||
When a request is forwarded by a proxy server, it is often upgraded to HTTPS to ensure secure transmission. The proxy server will send a header like `X-Forwarded-Proto` to indicate whether the original request was HTTP or HTTPS. If the backend application does not correctly handle this header, it may generate URLs with the wrong protocol. |
|||
|
|||
### 3. Path Handling Issues |
|||
|
|||
Since load balancers and proxies might modify or map the request URL paths differently, the backend application could encounter path inconsistencies. For example, a reverse proxy might forward a request from `/api` to `/myapp/api`. If the backend application is not correctly configured, path parsing errors may occur. |
|||
|
|||
### 4. IP Address and Security |
|||
|
|||
Reverse proxies might replace the original client IP address with their own, which can affect logging, authentication, and access control mechanisms. To retrieve the actual client IP address, the `X-Forwarded-For` header must be correctly parsed and trusted. |
|||
|
|||
### 5. Load Balancer Impact |
|||
|
|||
Load balancers might distribute requests to different backend servers using different algorithms. This can create session affinity problems. If session data is stored on a single server and the load balancer directs subsequent requests to different servers, session loss or inconsistency may occur. |
|||
|
|||
## Forwarded Headers Middleware in ABP web application |
|||
|
|||
To resolve the above issues, ASP.NET Core provides a built-in middleware, `ForwardedHeadersMiddleware`, which processes the headers forwarded by reverse proxies. This middleware helps the application recover the correct original request information, such as the client’s IP address, protocol, and host. |
|||
|
|||
### Configuring `ForwardedHeadersMiddleware` |
|||
|
|||
ASP.NET Core’s `ForwardedHeadersMiddleware` supports several HTTP headers: |
|||
|
|||
- **X-Forwarded-For**: Contains the original client’s IP address. |
|||
- **X-Forwarded-Proto**: Indicates whether the original request was HTTP or HTTPS. |
|||
- **X-Forwarded-Host**: Contains the original host requested by the client. |
|||
- **X-Forwarded-Port**: Indicates the original port of the request. |
|||
|
|||
To configure this middleware: |
|||
|
|||
1. In the `ConfigureServices` method of your module, configure the `ForwardedHeadersOptions`: |
|||
|
|||
```csharp |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
context.Services.Configure<ForwardedHeadersOptions>(options => |
|||
{ |
|||
options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto; |
|||
}); |
|||
} |
|||
``` |
|||
|
|||
2. In the `OnApplicationInitialization` method of your module, add the middleware: |
|||
|
|||
> Forwarded Headers Middleware should run before other middleware. This ordering ensures that the middleware relying on forwarded headers information can consume the header values for processing. Forwarded Headers Middleware can run after diagnostics and error handling, but it must be run before calling UseHsts: |
|||
|
|||
```csharp |
|||
public override void OnApplicationInitialization(ApplicationInitializationContext context) |
|||
{ |
|||
var app = context.GetApplicationBuilder(); |
|||
var env = context.GetEnvironment(); |
|||
|
|||
if (env.IsDevelopment()) |
|||
{ |
|||
app.UseDeveloperExceptionPage(); |
|||
app.UseForwardedHeaders(); |
|||
} |
|||
else |
|||
{ |
|||
app.UseErrorPage(); |
|||
app.UseForwardedHeaders(); |
|||
app.UseHsts(); |
|||
} |
|||
|
|||
// Other middleware configurations... |
|||
} |
|||
``` |
|||
|
|||
## References |
|||
|
|||
- [ASP.NET Core Proxy and Load Balancer Configuration](https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/proxy-load-balancer?view=aspnetcore-9.0) |
|||
@ -1,83 +1,72 @@ |
|||
# Blazor UI: Managing Global Scripts & Styles |
|||
|
|||
Some modules may require additional styles or scripts that need to be referenced in **index.html** file. It's not easy to find and update these types of references in Blazor apps. ABP offers a simple, powerful, and modular way to manage global style and scripts in Blazor apps. |
|||
You can add your JavaScript and CSS files from your modules or applications to the Blazor global assets system. All the JavaScript and CSS files will be added to the `global.js` and `global.css` files. You can access these files via the following URL in a Blazor WASM project: |
|||
|
|||
To update script & style references without worrying about dependencies, ordering, etc in a project, you can use the [bundle command](../../../cli#bundle). |
|||
- https://localhost/global.js |
|||
- https://localhost/global.css |
|||
|
|||
You can also add custom styles and scripts and let ABP manage them for you. In your Blazor project, you can create a class implementing `IBundleContributor` interface. |
|||
## Add JavaScript and CSS to the global assets system in the module |
|||
|
|||
`IBundleContributor` interface contains two methods. |
|||
Your module project solution will have two related Blazor projects: |
|||
|
|||
* `AddScripts(...)` |
|||
* `AddStyles(...)` |
|||
* `MyModule.Blazor`：This project includes the JavaScript/CSS files required for your Blazor components. The `MyApp.Blazor.Client (Blazor WASM)` project will reference this project. |
|||
* `MyModule.Blazor.WebAssembly.Bundling`：This project is used to add your JavaScript/CSS files to the Blazor global resources. The `MyModule.Blazor (ASP.NET Core)` project will reference this project. |
|||
|
|||
Both methods get `BundleContext` as a parameter. You can add scripts and styles to the `BundleContext` and run [bundle command](../../../cli#bundle). Bundle command detects custom styles and scripts with module dependencies and updates `index.html` file. |
|||
You need to define JavaScript and CSS contributor classes in the `MyModule.Blazor.WebAssembly.Bundling` project to add the files to the global assets system. |
|||
|
|||
## Example Usage |
|||
```csharp |
|||
namespace MyProject.Blazor |
|||
> Please use `BlazorWebAssemblyStandardBundles.Scripts.Global` and `BlazorWebAssemblyStandardBundles.Styles.Global` for the bundle name. |
|||
|
|||
```cs |
|||
public class MyModuleBundleScriptContributor : BundleContributor |
|||
{ |
|||
public class MyProjectBundleContributor : IBundleContributor |
|||
public override void ConfigureBundle(BundleConfigurationContext context) |
|||
{ |
|||
public void AddScripts(BundleContext context) |
|||
{ |
|||
context.Add("site.js"); |
|||
} |
|||
|
|||
public void AddStyles(BundleContext context) |
|||
{ |
|||
context.Add("main.css"); |
|||
context.Add("custom-styles.css"); |
|||
} |
|||
context.Files.AddIfNotContains("_content/MyModule.Blazor/libs/myscript.js"); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
> There is a BundleContributor class implementing `IBundleContributor` interface coming by default with the startup templates. So, most of the time, you don't need to add it manually. |
|||
|
|||
## Bundling And Minification |
|||
`abp bundle` command offers bundling and minification support for client-side resources(JavaScript and CSS files). `abp bundle` command reads the `appsettings.json` file inside the Blazor project and bundles the resources according to the configuration. You can find the bundle configurations inside `AbpCli.Bundle` element. |
|||
|
|||
Here are the options that you can control inside the `appsettings.json` file. |
|||
|
|||
`Mode`: Bundling and minification mode. Possible values are |
|||
* `BundleAndMinify`: Bundle all the files into a single file and minify the content. |
|||
* `Bundle`: Bundle all files into a single file, but not minify. |
|||
* `None`: Add files individually, do not bundle. |
|||
|
|||
`Name`: Bundle file name. Default value is `global`. |
|||
|
|||
`Parameters`: You can define additional key/value pair parameters inside this section. `abp bundle` command automatically sends these parameters to the bundle contributors, and you can check these parameters inside the bundle contributor, take some actions according to these values. |
|||
|
|||
Let's say that you want to exclude some resources from the bundle and control this action using the bundle parameters. You can add a parameter to the bundle section like below. |
|||
|
|||
```json |
|||
"AbpCli": { |
|||
"Bundle": { |
|||
"Mode": "BundleAndMinify", /* Options: None, Bundle, BundleAndMinify */ |
|||
"Name": "global", |
|||
"Parameters": { |
|||
"ExcludeThemeFromBundle":"true" |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
You can check this parameter and take action like below. |
|||
|
|||
```csharp |
|||
public class MyProjectNameBundleContributor : IBundleContributor |
|||
```cs |
|||
public class MyModuleBundleStyleContributor : BundleContributor |
|||
{ |
|||
public void AddScripts(BundleContext context) |
|||
public override void ConfigureBundle(BundleConfigurationContext context) |
|||
{ |
|||
context.Files.AddIfNotContains("_content/MyModule.Blazor/libs/mystyle.css"); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
public void AddStyles(BundleContext context) |
|||
```cs |
|||
[DependsOn( |
|||
typeof(AbpAspNetCoreComponentsWebAssemblyThemingBundlingModule) |
|||
)] |
|||
public class MyBlazorWebAssemblyBundlingModule : AbpModule |
|||
{ |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
var excludeThemeFromBundle = bool.Parse(context.Parameters.GetValueOrDefault("ExcludeThemeFromBundle")); |
|||
context.Add("mytheme.css", excludeFromBundle: excludeThemeFromBundle); |
|||
context.Add("main.css"); |
|||
Configure<AbpBundlingOptions>(options => |
|||
{ |
|||
// Add script bundle |
|||
options.ScriptBundles.Get(BlazorWebAssemblyStandardBundles.Scripts.Global) |
|||
.AddContributors(typeof(MyModuleBundleScriptContributor)); |
|||
|
|||
// Add style bundle |
|||
options.StyleBundles.Get(BlazorWebAssemblyStandardBundles.Styles.Global) |
|||
.AddContributors(typeof(MyModuleBundleStyleContributor)); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Add JavaScript and CSS to the global assets system in the application |
|||
|
|||
This is similar to the module. You need to define JavaScript and CSS contributor classes in the `MyApp.Blazor.Client` project to add the files to the global assets system. |
|||
|
|||
## AbpBundlingGlobalAssetsOptions |
|||
|
|||
You can configure the JavaScript and CSS file names in the `GlobalAssets` property of the `AbpBundlingOptions` class. The default values are `global.js` and `global.css`. |
|||
|
|||
## Reference |
|||
|
|||
- [ASP.NET Core MVC Bundling & Minification](../mvc-razor-pages/bundling-minification#bundle-contributorsg) |
|||
- [ABP Global Assets - New way to bundle JavaScript/CSS files in Blazor WebAssembly app](https://github.com/abpframework/abp/blob/dev/docs/en/Community-Articles/2024-11-25-Global-Assets/POST.md) |
|||
|
|||
|
Before Width: | Height: | Size: 8.5 KiB |
|
After Width: | Height: | Size: 14 KiB |
|
After Width: | Height: | Size: 18 KiB |
|
Before Width: | Height: | Size: 29 KiB |
|
After Width: | Height: | Size: 54 KiB |
|
After Width: | Height: | Size: 86 KiB |
|
After Width: | Height: | Size: 56 KiB |
|
After Width: | Height: | Size: 46 KiB |
|
After Width: | Height: | Size: 75 KiB |
|
After Width: | Height: | Size: 72 KiB |
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue