webserver.js Kundenerweiterungen

Erweiterungspakete

Für die Erweiterung von webserver.js werden zwei npm-Pakete bereitgestellt:

@wincc-oa/backend — Basisklassen und Hilfsfunktionen zur Anpassung des webserver.js Backends werden bereitgestellt. Dieses Paket ist nicht für die eigenständige Verwendung vorgesehen.
@wincc-oa/create-backend — Ein Scaffolding-Tool, mit dem ein einsatzbereites Erweiterungsprojekt mit Beispielcode für TypeScript- und CTRL-Anpassungen erzeugt wird.

Important:

Die Version dieser Pakete muss mit der Version der WinCC OA Installation übereinstimmen. Die Version in javascript/webserver-js/package.json der Installation ist zu prüfen. Falls @wincc-oa/backend manuell installiert werden muss, ist die exakte Version anzugeben:

npm install @wincc-oa/backend@x.y.z

Erstellen eines Erweiterungsprojekts

Zum Erzeugen eines neuen Erweiterungsprojekts wird das Scaffolding-Tool verwendet:

npx @wincc-oa/create-backend my-backend

Um die Kompatibilität sicherzustellen, ist die Version zu verwenden, die der WinCC OA Installation entspricht:

npx @wincc-oa/create-backend@x.y.z my-backend

Es kann auch in ein bestehendes leeres Verzeichnis installiert werden:

mkdir my-backend
cd my-backend
npx @wincc-oa/create-backend .

Dadurch wird folgende Verzeichnisstruktur im Projekt erstellt:

<project-dir>/
├── javascript/
│   └── customer-webserver-example/    (TypeScript extensions)
│       ├── src/
│       │   ├── index.ts                     (entry point exports)
│       │   ├── customerDashboardServer.ts
│       │   ├── customerTsRequestHandler.ts
│       │   ├── customerRoutes.ts
│       │   ├── connectionsRoute.ts
│       │   └── connectionsController.ts
│       ├── run.js                           (JavaScript Manager entry point)
│       ├── package.json
│       └── tsconfig.json
└── scripts/
    └── libs/
        └── classes/
            └── wsjServer/             (CTRL extensions)
                ├── CustomerCtrlRequestHandler.ctl
                ├── CustomerCtrlHttpEndpoints.ctl
                └── WsjEmbeddedCtrlUser.ctl

TypeScript-Erweiterungen

Mit TypeScript-Erweiterungen kann das webserver.js Backend mit modernen Webentwicklungsmustern angepasst werden. Das generierte Projekt enthält die folgenden Beispieldateien:


Datei	Beschreibung
customerDashboardServer.ts	Eine Unterklasse von `WsjDashboardServer`, mit der gezeigt wird, wie die Hauptserverklasse mit benutzerdefinierter Initialisierung und Verhalten erweitert wird.
customerTsRequestHandler.ts	Benutzerdefinierte Request-Handler auf Basis von `WsjRequestHandlerBase`, mit denen sowohl One-Shot-Request/Response-Muster als auch Live-WebSocket-Subscriptions für Echtzeitdaten unterstützt werden.
customerRoutes.ts	Express-ähnliche Routen-Definitionen mit `WsjRoutes`, mit denen benutzerdefinierte HTTP-Endpunkte registriert werden.
connectionsController.ts	Ein Beispiel-Controller, mit dem Antworten in mehreren Formaten (JSON, Markdown, HTML) demonstriert werden.

Wichtige Basisklassen und Hilfsfunktionen aus dem Paket @wincc-oa/backend:

WsjDashboardServer — Hauptserverklasse, mit der benutzerdefiniertes Verhalten abgeleitet wird.
WsjRequestHandlerBase — Basisklasse, mit der benutzerdefinierte Request-Handler implementiert werden.
WsjRequestHandlerRegistry — Registry, mit der Request-Handler verwaltet werden.
WsjRoutes — Hilfsfunktionen, mit denen Routen registriert werden.
WsjStaticLiveDirectoryRoute — Route, mit der statische Dateien mit Live-Reload-Unterstützung bereitgestellt werden.
WsjCtrlEndpointRoute — Route, mit der CTRL-basierte HTTP-Endpunkte bereitgestellt werden.
WsjAccessControlList — Zugriffssteuerungsverwaltung, mit der Zugriffe gesteuert werden.
WsjServerGlobal — Globale Server-Hilfsfunktionen und Konfiguration.

CTRL-Erweiterungen

Für Entwickler, die mit der WinCC OA CTRL-Sprache vertraut sind, werden auch CTRL-basierte Erweiterungen unterstützt. Das generierte Projekt enthält die folgenden CTRL-Beispieldateien:


Datei	Beschreibung
CustomerCtrlRequestHandler.ctl	Ein CTRL-basierter Request-Handler, mit dem HTTP-Anfragen mit CTRL-Skripten verarbeitet werden.
CustomerCtrlHttpEndpoints.ctl	Benutzerdefinierte HTTP-Endpunkte werden definiert, die in CTRL implementiert sind.
WsjEmbeddedCtrlUser.ctl	CTRL-Handler werden registriert und CTRL-Endpunktaufrufe im Kontext von webserver.js geroutet.

Einrichten einer benutzerdefinierten Erweiterung

Nach dem Scaffolding wird die Erweiterung wie folgt in das WinCC OA Projekt integriert:

Die Erweiterung wird als Unterprojekt in die config/config-Datei eingefügt.
Die npm-Abhängigkeiten werden installiert:
```
npm install
npm install --save-dev <path-to-installation>/javascript/@types/winccoa-manager
```
<path-to-installation> ist durch den Pfad zum WinCC OA Installationsverzeichnis zu ersetzen.
Der TypeScript-Code wird erstellt:
```
npm run build
```
Für automatische Neukompilierung während der Entwicklung kann stattdessen der Watch-Modus verwendet werden:
```
npm run watch
```
In der WinCC OA Console wird ein JavaScript Manager hinzugefügt, dessen Skriptpfad auf den Einstiegspunkt der Erweiterung zeigt:
```
node customer-webserver-example/run.js
```

Die benutzerdefinierte webserver.js Instanz ist jetzt mit den Erweiterungen in Betrieb und Anfragen werden über die benutzerdefinierten Handler und Routen zusätzlich zur Standardfunktionalität verarbeitet.