Skip to content

Commit cdd2db2

Browse files
PTKuPTKu
authored
Merge pull request #518 from Inxton/add-ui-companion-and-referencing-in-target-projects
Add support for UI companion packages in AXSharp configuration
2 parents 816fda5 + c42179e commit cdd2db2

32 files changed

Lines changed: 564 additions & 114 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: docs
2+
3+
on:
4+
push:
5+
branches: [ "dev" ]
6+
paths:
7+
- 'src/**'
8+
- 'docfx/**'
9+
- '.github/workflows/docs.yml'
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
concurrency:
18+
group: "pages"
19+
cancel-in-progress: false
20+
21+
jobs:
22+
build:
23+
runs-on: [self-hosted, Windows, X64, L2, AX]
24+
steps:
25+
- name: Checkout
26+
uses: actions/checkout@v4
27+
with:
28+
fetch-depth: 0
29+
30+
- name: Setup .NET
31+
uses: actions/setup-dotnet@v4
32+
with:
33+
dotnet-version: '10.0.x'
34+
35+
- name: Install DocFX
36+
run: dotnet tool restore || dotnet tool install docfx --global
37+
38+
- name: Build solution
39+
run: .\build.ps1
40+
41+
- name: Generate documentation
42+
run: dotnet docfx docfx/docfx.json
43+
44+
- name: Upload Pages artifact
45+
uses: actions/upload-pages-artifact@v3
46+
with:
47+
path: docs
48+
49+
deploy:
50+
environment:
51+
name: github-pages
52+
url: ${{ steps.deployment.outputs.page_url }}
53+
runs-on: ubuntu-latest
54+
needs: build
55+
steps:
56+
- name: Deploy to GitHub Pages
57+
id: deployment
58+
uses: actions/deploy-pages@v4

‎CODEOWNERS‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
1-
@MTS spol. s r.o. @TomKovac
1+
@TomKovac
2+
@PTKu

‎docfx/api/index.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
11
# AXSharp API Documentation
22

3-
![](~/images/banner.png)
3+
![](~/images/banner.png)
4+
5+
Browse the auto-generated API reference for all AX# packages:
6+
7+
- **AXSharp.Connector** — core connectivity layer, twin objects, and data exchange primitives
8+
- **AXSharp.Compiler** — twin compiler (ixc) internals and code generation
9+
- **AXSharp.Blazor** — Blazor UI rendering components and auto-generated views
10+
- **AXSharp.Abstractions** — shared interfaces and presentation attributes
11+
12+
Use the table of contents on the left to navigate namespaces and types.

‎docfx/articles/compiler/CONFIG_FILE.MD‎

Lines changed: 34 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,53 @@
11
# Ixc config file
22

3-
**AXSharp.config.json** can contain some settings for the compiler. Upon the first run of the ixc the default `AXSharp.config.json` file is created if not previoulsy created manually.
4-
5-
Some compilation options can be overrided by CLI, such as `OutputProjectFolder` (-o) will override `OutputProjectFolder` setting in the config file.
3+
**AXSharp.config.json** can contain settings for the compiler. Upon the first run of `ixc` a default `AXSharp.config.json` file is created if one does not already exist.
64

5+
Some options can be overridden from the CLI. For example, the `-o` flag overrides `OutputProjectFolder`.
76

87
**Default config file**
98

109
~~~json
1110
{
12-
"OutputProjectFolder":"ix",
11+
"OutputProjectFolder": "ix"
1312
}
1413
~~~
1514

16-
**Config file example**
15+
**Config file example (library with UI companion)**
1716

1817
~~~json
1918
{
20-
"OutputProjectFolder":"..\\ix-app"
19+
"OutputProjectFolder": "../ix",
20+
"UiHostProject": "../blazorapp/blazorapp.csproj"
2121
}
2222
~~~
2323

24-
| Parameter | Meaning | Default |
25-
| ------------------- | ------------------------------------------------------------------------------------------------------ | ------- |
26-
| OutputProjectFolder | Sets the directory where the ixc will emmit the twin project.Use path relative to apax project folder. | 'ix' |
27-
| | The value is overridable from the CLI | |
24+
## Parameters
25+
26+
| Parameter | CLI flag | Meaning | Default |
27+
| --- | --- | --- | --- |
28+
| `OutputProjectFolder` | `-o` | Directory where `ixc` emits the twin project. Path relative to the AX project folder. | `ix` |
29+
| `ProjectFile` | `-p` | Name of the output `.csproj` file. | *(project name)* |
30+
| `UseBase` | `-b` | Use `$base` for base types in inherited classes. Obsolete. | `false` |
31+
| `NoDependencyUpdate` | `-u` | Prevent dependent twin packages from being installed via apax. | `false` |
32+
| `IgnoreS7Pragmas` | `-s` | Ignore `S7.extern` pragmas; compile all members regardless of communication settings. | `false` |
33+
| `SkipDependencyCompilation` | `-d` | Skip compilation of referenced AX# dependency projects. | `false` |
34+
| `TargetPlatfromMoniker` | `-t` | Target platform: `ax` or `tia`. | `ax` |
35+
| `UiHostProject` | `-a` | Path (relative to the AX project folder or absolute) of the `.csproj` that hosts or consumes UI companion NuGet packages. In library development this is the Blazor/UI application project; in application development this is the application project itself. When set, `ixc` automatically installs UI companion package references into this project. | *(none)* |
36+
37+
## UI companion packages
38+
39+
When a PLC library ships a UI companion package (Blazor components, auto-generated views, etc.), `ixc` can automatically wire up the dependency for you.
40+
41+
**Library author** — set `UiHostProject` in the library's `AXSharp.config.json` to the path of the UI project that is built alongside the twin project. When `ixc` runs it will:
2842

43+
1. Determine the UI package ID from the `<PackageId>` element in the referenced `.csproj`, or fall back to `<apax-package-name>.UI` when the file does not exist.
44+
2. Write that ID and the library version into `axsharp.companion.json` alongside the usual twin connector fields.
2945

46+
**Consumer** — set `UiHostProject` in your project's `AXSharp.config.json` to point at the application project (e.g. a Blazor server app) that should receive the dependency. When `ixc` resolves a dependency that carries UI companion info, it automatically adds the corresponding NuGet package reference (or project reference when working directly from source) to the configured host project.
47+
48+
~~~json
49+
{
50+
"OutputProjectFolder": "../ix",
51+
"UiHostProject": "../MyBlazorApp/MyBlazorApp.csproj"
52+
}
53+
~~~

‎docfx/articles/compiler/PACKAGING.md‎

Lines changed: 50 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,4 +25,53 @@ Set the files in the `.meta` folder to build action to `Content`.
2525
## Versioning
2626

2727
> **Important**
28-
> The APAX package and respective Twin NuGet package must be released with the same version number. APAX package and NuGet package with the same version number are considered aligned.
28+
> The APAX package and respective Twin NuGet package must be released with the same version number. APAX package and NuGet package with the same version number are considered aligned.
29+
30+
## UI companion packages
31+
32+
A PLC library can ship a UI companion package alongside the twin connector — for example a set of auto-generated Blazor components. `ixc` handles the bookkeeping automatically via `axsharp.companion.json`.
33+
34+
### Library author
35+
36+
Set `UiHostProject` in your library's `AXSharp.config.json` to the path of the UI `.csproj` within your repository:
37+
38+
~~~json
39+
{
40+
"OutputProjectFolder": "../ix",
41+
"UiHostProject": "../MyLib.UI/MyLib.UI.csproj"
42+
}
43+
~~~
44+
45+
When `ixc` compiles the library it:
46+
47+
1. Reads the `<PackageId>` from the UI project file (falls back to `<apax-name>.UI` if the file is absent).
48+
2. Writes `UiId` and `UiVersion` into `axsharp.companion.json` next to the existing twin connector fields.
49+
50+
~~~json
51+
{
52+
"Id": "MyLib.Twin",
53+
"Version": "1.2.3",
54+
"UiId": "MyLib.UI",
55+
"UiVersion": "1.2.3"
56+
}
57+
~~~
58+
59+
> The UI package version always matches the library version — publish both together.
60+
61+
### Consumer
62+
63+
Set `UiHostProject` in your application's `AXSharp.config.json` to the Blazor or UI host project that should receive the dependency:
64+
65+
~~~json
66+
{
67+
"OutputProjectFolder": "ix",
68+
"UiHostProject": "../MyBlazorApp/MyBlazorApp.csproj"
69+
}
70+
~~~
71+
72+
When `ixc` resolves a dependency whose `axsharp.companion.json` contains `UiId`/`UiVersion`, it automatically:
73+
74+
- Adds a **NuGet package reference** to `UiHostProject` when the dependency is consumed as a NuGet package.
75+
- Adds a **project reference** to `UiHostProject` when the dependency is consumed directly from source (i.e. the dependency has its own `AXSharp.config.json` with `UiHostProject` set).
76+
77+
If `UiHostProject` is not configured, the UI reference step is skipped and an informational message is logged.

‎docfx/articles/connectors/README.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -78,8 +78,8 @@ During the batched read operation, the values are stored in *LastValue* property
7878

7979
During a batched write operation, the values written to the controller were retrieved from the *Cyclic* property of the corresponding Primitive Twin.
8080

81-
> **NOTE**
82-
> Accessing *Cyclic* property for **writing** will not result in an autmatic subscription for cyclic reading. Acessing the *LastValue* property will neither result in an automatic subcription for reading.
81+
> **NOTE**
82+
> Accessing *Cyclic* property for **writing** will not result in an automatic subscription for cyclic reading. Accessing the *LastValue* property will neither result in an automatic subscription for reading.
8383
8484
~~~ C#
8585
// in this namespace are extension methods for batched operations.
@@ -93,11 +93,11 @@ public class BatchedAccess
9393
await Entry.PlcTwin.Settings.ReadAsync();
9494

9595
// Write values to the console
96-
Console.WriteLine($"{Entry.PlcTwin.Settings.PosX.Symbol}:{Entry.PlcTwin.MAIN.Settings.PosX.LastValue});
96+
Console.WriteLine($"{Entry.PlcTwin.Settings.PosX.Symbol}:{Entry.PlcTwin.Settings.PosX.LastValue}");
9797

98-
Console.WriteLine($"{Entry.PlcTwin.Settings.PosY.Symbol}:{Entry.PlcTwin.Settings.PosY.LastValue});
98+
Console.WriteLine($"{Entry.PlcTwin.Settings.PosY.Symbol}:{Entry.PlcTwin.Settings.PosY.LastValue}");
9999

100-
Console.WriteLine($"{Entry.PlcTwin.Settings.PosZ.Symbol}:{Entry.PlcTwin.Settings.PosZ.LastValue});
100+
Console.WriteLine($"{Entry.PlcTwin.Settings.PosZ.Symbol}:{Entry.PlcTwin.Settings.PosZ.LastValue}");
101101
}
102102

103103

@@ -108,11 +108,13 @@ public class BatchedAccess
108108
Entry.PlcTwin.Settings.PosZ.Cyclic = 130.0f;
109109

110110
// Writes all values of the settings structure.
111-
await Entry.PlcController.MAIN.Settings.WriteAsynch();
111+
await Entry.PlcTwin.Settings.WriteAsync();
112112
}
113113
}
114114
~~~
115115

116+
## Polling
117+
116118
Polling allows an application to query a structure or variable at different intervals. The values are stored in the `Cyclic` property of value types. The polled variables are retrieved from the controller in the same way as during cyclic reading but at a specified interval. Unlike automatic subscription mode, the polled values can be unsubscribed.
117119

118120
To enable polling, the subscription of the twin connector must be set to `Polling`.
@@ -256,7 +258,7 @@ _length : REAL;
256258
~~~
257259

258260
~~~ C#
259-
// Writes unit of the '_lenght' variable to the console.
261+
// Writes unit of the '_length' variable to the console.
260262
System.Console.WriteLine(PlcTwin._app._length.AttributeUnits);
261263
~~~
262264

@@ -334,10 +336,10 @@ VAR
334336
someWString : WSTRING;
335337
END_VAR
336338
337-
someString := '<#This woule be localized#> and this would stay as it is';
339+
someString := '<#This would be localized#> and this would stay as it is';
338340
339341
340-
someWString := "<#This woule be localized#> and this would stay as it is";
342+
someWString := "<#This would be localized#> and this would stay as it is";
341343
~~~
342344

343345
Connectors implement features that allow localizing of the texts (controller defined and added attributes of string type). For the localization to work the twin assembly must be provided with a resource file (*.resx). Resource files can be generated using [ixr tool](~/articles/ixr/IXR.md). You will need to add the resource file to your **Twin project** and set the resource code generation to *public*.

‎docfx/articles/connectors/WebAPI.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Here is an example on how to set polling subscription mode:
2323
Entry.Plc.Connector.SubscriptionMode = AXSharp.Connector.ReadSubscriptionMode.Polling;
2424
```
2525

26-
For more details about polling within your components, see [Polling Data from the Controller in Components](../blazor/LIBRARIES.md#polling-data-from-the-plc) and [General Polling](README.md#polling).
26+
For more details about polling within your components, see [Polling Data from the Controller in Components](../blazor/LIBRARIES.md#optimizing-plc-data-polling) and [General Polling](README.md#polling).
2727

2828
### Monitoring and Logging
2929

‎docfx/articles/intro.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
* [Config file](~/articles/compiler/CONFIG_FILE.md)
1010
* [Packaging and dependencies](~/articles/compiler/PACKAGING.md)
1111
---
12-
* [Documenation compiler](~/articles/ixd/IXD.md)
12+
* [Documentation compiler](~/articles/ixd/IXD.md)
1313
---
1414
* [Resx compiler](~/articles/ixr/IXR.md)
1515
---

‎docfx/articles/toc.yml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,12 @@
1818
- name: Packaging and dependencies
1919
href: ~/articles/compiler/PACKAGING.md
2020

21-
- name: Documenation compiler
21+
- name: Documentation compiler
2222
href: ~/articles/ixd/IXD.md
2323
- name: Localizables compiler
2424
href: ~/articles/ixr/IXR.md
25+
- name: Localizables to Resx
26+
href: ~/articles/ltr/LTR.md
2527
- name: Connectors
2628
href: ~/articles/connectors/README.md
2729
items:
@@ -38,4 +40,6 @@
3840
href: ~/articles/blazor/LIBRARIES.md
3941
- name: Blazor auto-rendering
4042
href: ~/articles/blazor/RENDERABLECONTENT.md
43+
- name: Coding style
44+
href: ~/articles/general/CODING_STYLE.md
4145

‎docfx/docfx.json‎

Lines changed: 4 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -26,16 +26,16 @@
2626
],
2727
"build": {
2828
"globalMetadata" : {
29-
"_appTitle" : {"api/index.md" : "API"},
29+
"_appTitle" : "AX#",
3030
"_appName" : "AX#",
31-
"_appFooter" : " Generated by DocFx. © MTS spol. s r.o., MTS spol. s r.o., and awesome contributors",
31+
"_appFooter" : " Generated by DocFx. © MTS spol. s r.o. and awesome contributors",
3232
"_enableSearch" : true,
3333
"_appFaviconPath" : "images/favicon.ico"
3434
},
3535

3636
"sitemap": {
3737
"baseUrl": "https://inxton.github.io/axsharp/",
38-
"priority": 0.1,
38+
"priority": 0.5,
3939
"changefreq": "weekly"
4040
},
4141

@@ -65,17 +65,7 @@
6565
]
6666
}
6767
],
68-
"overwrite": [
69-
{
70-
"files": [
71-
"apidoc/**.md"
72-
],
73-
"exclude": [
74-
"obj/**",
75-
"_site/**"
76-
]
77-
}
78-
],
68+
"overwrite": [],
7969
"dest": "../docs",
8070
"globalMetadataFiles": [],
8171
"fileMetadataFiles": [],

0 commit comments

Comments
 (0)