Export tools

To seamlessly reuse your AventusSharp code in AventusJs, we have created a tool that compiles your C# project into a DLL, reads this DLL, and generates AventusJs code. This ensures consistency between your frontend and backend and can also provide frontend developers with a development interface for your APIs.

Setting Up Export

To export your C# classes, follow these steps:

Install the AventusJs extension in VS Code.
Create a configuration file named aventus.sharp.avt to define the export settings. At minimum, you need to specify the following fields:
- csProj: Path to your .csproj file.
- outputPath: Directory where the generated files will be saved.
Right click on the file and press : Avenuts : Export sharp

// aventus.sharp.avt
{
    "csProj": "./Demo.csproj",
    "outputPath": "./Front/src/generated"
}

Additional Configuration

The configuration file supports additional parameters to customize the export process. Below is a detailed description of the fields available in the aventus.sharp.avt configuration file:

`csProj`

Type: string
Description: Specifies the path to your .csproj file. This is a required field.
Example: "./Demo.csproj"

`outputPath`

Type: string
Description: Defines the directory where the generated files will be exported. This is a required field.
Example: "./Front/src/generated"

`exportEnumByDefault`

Type: boolean
Default: false
Description: Determines whether enums should be exported by default. You can override this behavior using [Export] or [NoExport] attributes in your C# code.

`exportStorableByDefault`

Type: boolean
Default: true
Description: Determines whether storable classes should be exported by default. You can override this behavior using [Export] or [NoExport].

`exportHttpRouteByDefault`

Type: boolean
Default: true
Description: Specifies if HTTP routes should be exported by default. You can override this behavior using [Export] or [NoExport].

`exportErrorsByDefault`

Type: boolean
Default: true
Description: Specifies if error classes should be exported by default. You can override this behavior using [Export] or [NoExport].

`exportWsEndPointByDefault`

Type: boolean
Default: true
Description: Specifies if WebSocket endpoints should be exported by default. You can override this behavior using [Export] or [NoExport].

`exportWsEventByDefault`

Type: boolean
Default: true
Description: Specifies if WebSocket events should be exported by default. You can override this behavior using [Export] or [NoExport].

`exportWsRouteByDefault`

Type: boolean
Default: true
Description: Specifies if WebSocket routes should be exported by default. You can override this behavior using [Export] or [NoExport].

`httpRouter`

Type: object
Description: Configuration for HTTP route generation.
- Fields:
  - createRouter (boolean): Generates a router for your HTTP routes.
  - routerName (string, default: "GeneratedRouter"): Specifies the name of the generated router.
  - uri (string): Base URI for the router (e.g., /api).
  - host (string): Host for the router (e.g., https://localhost:5000).
  - parent (string, default: "Aventus.HttpRouter"): Parent type to use for the router.
  - namespace (string, default: "Routes"): Namespace for the generated router.

`wsEndpoint`

Type: object
Description: Configuration for WebSocket endpoint generation.
- Fields:
  - prefix (string): Prefix for WebSocket events.
  - host (string): WebSocket host.
  - port (number): WebSocket port.
  - useHttps (boolean): Determines if HTTPS should be used. Defaults to automatic detection based on connection security.
  - parent (string, default: "AventusSharp.WebSocket.EndPoint"): Parent type to use for the WebSocket endpoint.

`replacer`

Type: object
Description: Allows customization of how specific types are replaced during export.
- Fields:
  - all: Apply to all c# elements
  - genericError: Apply to error elements
  - httpRouter: Apply to httpRouter elements
  - normalClass: Apply to any normal classes
  - storable: Apply to stoable elements
  - withError: Apply to error wrapper elements (VoidWithError or ResultWithError)
  - wsEndPoint: Apply to ws endpoint elements
  - wsEvent: Apply to ws event element
  - wsRouter: Apply to ws router element

The format for each fields provides two key mechanisms for type replacement: type and result.

`type`

The type field is used to replace a type based on its exact match with a C# type. When the specified C# type is encountered, it will be replaced with the defined result in the generated AventusJs code.

Key Usage:
- Matches the C# type.
- Defines the corresponding AventusJs type to be used in the generated code.
- Optionally specifies additional settings like the import file or whether the import should be marked as a type-only import.

Example:

{
    "type": {
        "AventusSharp.Routes.Router": {
            "result": "Aventus.HttpRoute" // The type used in AventusJs
        }
    }
}

In this example:

If the type AventusSharp.Routes.Router is encountered in the C# code, it will be replaced with Aventus.HttpRoute in the exported AventusJs code.

`result`

The result field allows you to customize how a type, already transformed into AventusJs, should be further replaced or adjusted. This is particularly useful for ensuring consistency or applying additional modifications to the final type.

Key Usage:
- Matches a type already written in AventusJs.
- Replaces it with the defined result for further refinement.
Example:
```
{
    "result": {
        "Aventus.HttpRoute": {
            "result": "Aventus.HttpRoute"
        }
    }
}
```
In this example:
- If the type Aventus.HttpRoute is generated, it remains unchanged. However, you can add additional attributes or adjustments if needed.

Below is a complete example illustrating both type and result configurations:

{
    "replacer": {
        "all": {
            "type": {
                "AventusSharp.Routes.Router": {
                    // Optional: Define the file to import
                    // "file": "./path/to/file",
                    // Optional: Specify if the import should be type-only
                    // "useTypeImport": false,
                    "result": "Aventus.HttpRoute" // Transforms the C# type into this AventusJs type
                }
            },
            "result": {
                "Aventus.HttpRoute": {
                    // Optional: Define the file to import
                    // "file": "./path/to/file",
                    // Optional: Specify if the import should be type-only
                    // "useTypeImport": false,
                    "result": "Aventus.HttpRoute" // Adjusts or confirms the final AventusJs type
                }
            }
        }
    }
}

These fields provide a comprehensive way to customize the export process and adapt it to your project’s specific requirements.

Export attributes

AventusSharp provides several attributes to facilitate and control the export of your C# classes, interfaces, and enums to AventusJs. Below is an explanation of the key attributes and how to use them effectively.

`Export`

Use the [Export] attribute to explicitly export a class, interface, or enum that is not exported by default. This is particularly useful for exporting C# Data Transfer Objects (DTOs).

using AventusSharp.Tools.Attributes;

namespace Demo.Routes
{
    [Export]
    public class MyDTO
    {
        public int Version { get; set; }
        public string Name { get; set; } = "";
    }
}

In this example, MyDTO is explicitly marked for export using the [Export] attribute.

`NoExport`

The [NoExport] attribute prevents a class, interface, enum, or property from being exported to AventusJs. This is useful when you want to explicitly exclude certain elements from the export process, even if they are otherwise exported by default.

using AventusSharp.Tools.Attributes;

namespace Demo.Routes
{
    [NoExport]
    public enum InternalEnum
    {
        Value1
    }
}

In this example, the InternalEnum class is excluded from being exported to AventusJs by marking it with the [NoExport] attribute.

You can also exclude properties :

using AventusSharp.Tools.Attributes;

namespace Demo.Routes
{
    public class User
    {
        public int UserId { get; set; }

        [NoExport]
        public string InternalNotes { get; set; } = "";
    }
}

In this example, the InternalNotes property is marked with [NoExport], ensuring it is not included in the exported object, while the rest of the class is exported normally.

`CreateObject`

The [CreateObject] attribute allows you to generate a fully constructed object in your frontend code when used alongside the [ForeignKey] attribute. If no parameter is provided, the property name is generated by replacing Id or Key in the original property name with an empty string.

using AventusSharp.Data;
using AventusSharp.Data.Attributes;

namespace Demo.Data
{
    public class User : Storable<User>
    {
        public string Username { get; set; } = "";

        [ForeignKey<Role>, CreateObject]
        public int RoleId { get; set; }

        // The `Role` property will be created automatically when exported
        // public Role Role { get; set; }
    }
}

In this example, the RoleId property is annotated with both [ForeignKey<Role>] and [CreateObject]. When exported, the Role object will automatically be created.

`FctName`

The [FctName(string name)] attribute allows you to rename a method in your router classes (e.g., HTTP or WebSocket routers). This provides a cleaner or more descriptive name for your methods when accessed programmatically.

using AventusSharp.Routes;
using AventusSharp.Tools.Attributes;
using Demo.Data;

namespace Demo.Routes
{
    public class UserRouter : StorableRouter<User>
    {
        // This method will be accessible as `new UserRouter().myFunc()` instead of `new UserRouter().Test()`
        [FctName("myFunc")]
        public void Test()
        {

        }
    }
}

Here, the Test method in the UserRouter class is renamed to myFunc for frontend use.