From 098410d444b40ebff918086a4921ba4b0af9958c Mon Sep 17 00:00:00 2001 From: SakshiTamshetti Date: Fri, 6 Mar 2026 21:29:28 +0530 Subject: [PATCH] docs: add Getting Started sections to root and project READMEs #63 --- Kepware.Api.Sample/README.md | 75 ++++++++++++++++++++++++++++++ Kepware.Api/README.md | 82 +++++++++++++++++++++++++++++++++ KepwareSync.Service/README.md | 87 +++++++++++++++++++++++++++++++++++ README.md | 67 +++++++++++++++++++++++++++ 4 files changed, 311 insertions(+) diff --git a/Kepware.Api.Sample/README.md b/Kepware.Api.Sample/README.md index 9aa9f8a..f4f286c 100644 --- a/Kepware.Api.Sample/README.md +++ b/Kepware.Api.Sample/README.md @@ -9,6 +9,81 @@ The `Kepware.Api.Sample` project demonstrates how to use the `Kepware.Api` libra - Example for testing API connections. - HTTPS support with optional certificate validation. +## Getting Started + +### Prerequisites +- [.NET SDK 8.0+](https://dotnet.microsoft.com/download) +- Kepware server reachable on HTTPS **57512** or HTTP **57412** + +### Step 1 — Clone and restore +```bash +git clone https://github.com/PTCInc/Kepware-ConfigAPI-SDK-dotnet.git +cd Kepware-ConfigAPI-SDK-dotnet +dotnet restore Kepware.Api.Sample/Kepware.Api.Sample.csproj +``` + +### Step 2 — Set credentials + +Open `Kepware.Api.Sample/Program.cs` and update: +```csharp +services.AddKepwareApiClient( + name: "sample", + baseUrl: "https://localhost:57512", // ← your Kepware host + apiUserName: "Administrator", // ← your username + apiPassword: "YourPassword!", // ← your password + disableCertificateValidation: true +); +``` + +Or supply via environment variables (no file edits needed): +```bash +# Linux/macOS +export KEPWARE__PRIMARY__HOST=https://localhost:57512 +export KEPWARE__PRIMARY__USERNAME=Administrator +export KEPWARE__PRIMARY__PASSWORD=YourPassword! + +# Windows PowerShell +$env:KEPWARE__PRIMARY__HOST = "https://localhost:57512" +$env:KEPWARE__PRIMARY__USERNAME = "Administrator" +$env:KEPWARE__PRIMARY__PASSWORD = "YourPassword!" +``` + +### Step 3 — Build and run +```bash +dotnet build Kepware.Api.Sample/Kepware.Api.Sample.csproj +dotnet run --project Kepware.Api.Sample/Kepware.Api.Sample.csproj +``` + +### Expected output +``` +Connection successful. +Channel 'Channel by Api' created. +Device 'Device by Api' created. +Tags applied: RampByApi, SineByApi, BooleanByApi + +Press to exit... +``` + +The sample is fully **idempotent** — running it twice will not create duplicates. + +### What it does + +| Step | API call | Result | +|---|---|---| +| 1 | `TestConnectionAsync()` | Verifies server is reachable and credentials are valid | +| 2 | `GetOrCreateChannelAsync("Channel by Api", "Simulator")` | Creates channel or reuses existing | +| 3 | `GetOrCreateDeviceAsync(channel, "Device by Api")` | Creates device or reuses existing | +| 4 | `CompareAndApply(desiredTags, device.Tags, device)` | Adds/updates tags without touching others | + +### Troubleshooting + +| Symptom | Cause | Fix | +|---|---|---| +| `TestConnectionAsync` → `false` | Wrong host/port | HTTPS default = **57512**, HTTP = **57412** | +| TLS error | Self-signed cert | Set `disableCertificateValidation: true` for dev | +| `401 Unauthorized` | Wrong credentials | Check username/password in Kepware User Manager | +| Channel not created | Invalid driver name | Call `api.GetSupportedDriversAsync()` to list valid drivers | + ## Prerequisites - A running Kepware server with the Configuration API enabled. - .NET SDK 8.0 or later. diff --git a/Kepware.Api/README.md b/Kepware.Api/README.md index 40625b1..c0393eb 100644 --- a/Kepware.Api/README.md +++ b/Kepware.Api/README.md @@ -41,6 +41,88 @@ This package is designed to work with all versions of Kepware that support the C 5. Supports advanced operations like project comparison, entity synchronization, and driver property queries. 6. Built-in support for Dependency Injection to simplify integration. +## Getting Started + +### Prerequisites +- [.NET SDK 8.0+](https://dotnet.microsoft.com/download) +- Kepware server reachable on HTTPS port **57512** (default) or HTTP **57412** + +### Step 1 — Install +```bash +dotnet add package Kepware.Api +dotnet restore +``` + +### Step 2 — Register the client +```csharp +// Program.cs +services.AddKepwareApiClient( + name: "default", + baseUrl: "https://localhost:57512", + apiUserName: "Administrator", + apiPassword: "YourPassword!", + disableCertificateValidation: true // false + trusted cert in production +); +``` + +### Step 3 — Configure credentials (never hard-code passwords) + +**Environment variables (recommended)** +```bash +# Linux/macOS +export KEPWARE__PRIMARY__HOST=https://localhost:57512 +export KEPWARE__PRIMARY__USERNAME=Administrator +export KEPWARE__PRIMARY__PASSWORD=YourPassword! + +# Windows PowerShell +$env:KEPWARE__PRIMARY__HOST = "https://localhost:57512" +$env:KEPWARE__PRIMARY__USERNAME = "Administrator" +$env:KEPWARE__PRIMARY__PASSWORD = "YourPassword!" +``` + +**appsettings.json** (add file to `.gitignore`) +```json +{ + "Kepware": { + "Primary": { + "Host": "https://localhost:57512", + "Username": "Administrator", + "Password": "YourPassword!" + }, + "DisableCertificateValidation": true + } +} +``` + +### Step 4 — End-to-end: list channels and devices +```csharp +var api = host.Services.GetRequiredService(); + +if (!await api.TestConnectionAsync()) +{ + Console.Error.WriteLine("Cannot connect — check host, port, and credentials."); + return; +} + +var info = await api.GetProductInfoAsync(); +Console.WriteLine($"Connected: {info.ProductName} {info.ProductVersion}"); + +var project = await api.LoadProject(blnLoadFullProject: false); +foreach (var channel in project.Channels) +{ + Console.WriteLine($"Channel: {channel.Name} Driver: {channel.DeviceDriver}"); + foreach (var device in channel.Devices) + Console.WriteLine($" Device: {device.Name}"); +} +``` + +**Expected output** +``` +Connected: KEPServerEX 6.14.263.0 +Channel: SimulatorChannel Driver: Simulator + Device: SimDevice1 +``` + ## Installation Kepware.Api NuGet package is available from NuGet repository. diff --git a/KepwareSync.Service/README.md b/KepwareSync.Service/README.md index 9f3a746..4c35d1a 100644 --- a/KepwareSync.Service/README.md +++ b/KepwareSync.Service/README.md @@ -51,6 +51,93 @@ Deploy a centralized GIT configuration across multiple Kepware instances. Config - **HTTPS Support**: Secure connections with optional certificate validation. - **Overwrite Configuration Support**: Customize configurations dynamically using YAML files with environment variable placeholders. +## Getting Started + +### Prerequisites +- [.NET SDK 8.0+](https://dotnet.microsoft.com/download) +- Kepware server with Configuration API enabled +- Docker *(optional — for container deployment only)* + +### Step 1 — Clone and restore +```bash +git clone https://github.com/PTCInc/Kepware-ConfigAPI-SDK-dotnet.git +cd Kepware-ConfigAPI-SDK-dotnet +dotnet restore KepwareSync.Service/KepwareSync.Service.csproj +``` + +### Step 2 — Configure credentials + +Priority order: **CLI args > env vars > appsettings.json** + +**Environment variables (recommended)** + +| Variable | Required | Example | +|---|---|---| +| `KEPWARE__PRIMARY__HOST` | ✅ | `https://localhost:57512` | +| `KEPWARE__PRIMARY__USERNAME` | ✅ | `Administrator` | +| `KEPWARE__PRIMARY__PASSWORD` | ✅ | `YourPassword!` | +| `STORAGE__DIRECTORY` | ✅ | `./ExportedYaml` | +| `KEPWARE__DISABLECERTIFICATEVALIDATION` | — | `true` *(dev only)* | +| `SYNC__SYNCMODE` | — | `OneWay` or `TwoWay` | +| `SYNC__SYNCDIRECTION` | — | `KepwareToDisk` / `DiskToKepware` / `KepwareToKepware` | +```bash +# Linux/macOS +export KEPWARE__PRIMARY__HOST=https://localhost:57512 +export KEPWARE__PRIMARY__USERNAME=Administrator +export KEPWARE__PRIMARY__PASSWORD=YourPassword! +export STORAGE__DIRECTORY=./ExportedYaml + +# Windows PowerShell +$env:KEPWARE__PRIMARY__HOST = "https://localhost:57512" +$env:KEPWARE__PRIMARY__USERNAME = "Administrator" +$env:KEPWARE__PRIMARY__PASSWORD = "YourPassword!" +$env:STORAGE__DIRECTORY = "./ExportedYaml" +``` + +**appsettings.json** (add to `.gitignore`) +```json +{ + "Kepware": { + "DisableCertificateValidation": true, + "TimeoutInSeconds": 60, + "Primary": { + "Host": "https://localhost:57512", + "Username": "Administrator", + "Password": "YourPassword!" + } + }, + "Storage": { "Directory": "ExportedYaml" }, + "Sync": { "SyncMode": "OneWay", "SyncDirection": "KepwareToDisk" } +} +``` + +### Step 3 — Build +```bash +dotnet build KepwareSync.Service/KepwareSync.Service.csproj +``` + +### Step 4 — Run: one-shot export (Kepware → disk) +```bash +dotnet run --project KepwareSync.Service/KepwareSync.Service.csproj -- \ + SyncToDisk \ + --primary-kep-api-username Administrator \ + --primary-kep-api-password YourPassword! \ + --primary-kep-api-host https://localhost:57512 \ + --directory ./ExportedYaml +``` +YAML files for every channel/device appear in `./ExportedYaml/`. + +### Step 5 — Run: continuous agent mode +```bash +dotnet run --project KepwareSync.Service/KepwareSync.Service.csproj -- \ + --primary-kep-api-username Administrator \ + --primary-kep-api-password YourPassword! \ + --primary-kep-api-host https://localhost:57512 \ + --directory ./ExportedYaml +``` +Watches both sides and syncs on any change. Press `Ctrl+C` to stop. + + ## Usage ### CLI Commands diff --git a/README.md b/README.md index 60759c7..f3ee5f0 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,73 @@ Sample console applications demonstrating how to use `Kepware.Api` NuGet package [Readme for Kepware.Api.Sample](./Kepware.Api.Sample/README.md) +## Getting Started + +| Goal | Section | +|---|---| +| Use the API library | [→ Kepware.Api](#kepwareapi-quick-start) | +| Run the sync service | [→ KepwareSync.Service](#kepwaresyncservice-quick-start) | +| Run the demo app | [→ Kepware.Api.Sample](#kepwareapisample-quick-start) | + +### Prerequisites +- [.NET SDK 8.0+](https://dotnet.microsoft.com/download) +- A running Kepware server with the Configuration API enabled +```bash +dotnet --version # must be 8.0.x or later +``` + +--- + +### Kepware.Api quick-start +```bash +dotnet add package Kepware.Api +dotnet restore +``` +```csharp +// Register in Program.cs +services.AddKepwareApiClient( + name: "default", + baseUrl: "https://localhost:57512", + apiUserName: "Administrator", + apiPassword: "YourPassword!", + disableCertificateValidation: true +); + +// List all channels +var api = host.Services.GetRequiredService(); +if (await api.TestConnectionAsync()) +{ + var project = await api.LoadProject(blnLoadFullProject: false); + foreach (var ch in project.Channels) + Console.WriteLine($"Channel: {ch.Name} Driver: {ch.DeviceDriver}"); +} +``` + +--- + +### KepwareSync.Service quick-start +```bash +dotnet restore KepwareSync.Service/KepwareSync.Service.csproj +dotnet build KepwareSync.Service/KepwareSync.Service.csproj +dotnet run --project KepwareSync.Service/KepwareSync.Service.csproj -- \ + SyncToDisk \ + --primary-kep-api-username Administrator \ + --primary-kep-api-password YourPassword! \ + --primary-kep-api-host https://localhost:57512 \ + --directory ./ExportedYaml +``` + +--- + +### Kepware.Api.Sample quick-start +```bash +dotnet restore Kepware.Api.Sample/Kepware.Api.Sample.csproj +dotnet build Kepware.Api.Sample/Kepware.Api.Sample.csproj +dotnet run --project Kepware.Api.Sample/Kepware.Api.Sample.csproj +``` +Update credentials in `Kepware.Api.Sample/Program.cs` before running — see section below. + + ## Contribution Guidelines We welcome contributions to this repository. Please review the [Repository Guidelines](./docs/repo-guidelines.md) for information on Commit Message Conventions, Pull Request process and other details.