# dborgards/eds-dcf-net architecture

> Architecture diagram of the GitHub repository dborgards/eds-dcf-net, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dborgards/eds-dcf-net
- Repository: https://github.com/dborgards/eds-dcf-net

## Overview

#### Purpose and Runtime

EdsDcfNet is a .NET Standard 2.0 C# library for reading, editing, validating, converting, and writing CANopen CiA DS 306 (EDS, DCF, CPJ) and CiA 311 (XDD, XDC) files. It is a library, not a service or web application. Consumers run it in their own .NET process; repository builds require .NET SDK 10/C# 13.

Core project: `src/EdsDcfNet/EdsDcfNet.csproj`. Usage entry example: `examples/EdsDcfNet.Examples/Program.cs`.

#### Public API and Format Routing

`CanOpenFile` is the public façade. Its canonical format-specific operations (`Eds`, `Dcf`, `Cpj`, `Xdd`, `Xdc`) centralize sync/async file, stream, and string I/O, shared read limits, write options, validation, and legacy API delegation.

- `src/EdsDcfNet/CanOpenFile.cs`
- `src/EdsDcfNet/FormatCanOpenOperations.cs`
- `src/EdsDcfNet/EdsCanOpenOperations.cs`

Format operations select the corresponding parser/writer and preserve caller stream ownership. EDS-to-DCF conversion is owned by the EDS operation layer.

#### Canonical Domain Models

The central boundary is a typed in-memory CANopen model rather than raw document conversion. EDS/XDD map to `ElectronicDataSheet`; DCF/XDC map to `DeviceConfigurationFile`; CPJ maps to network/project topology. All device formats expose an editable object dictionary, including objects, sub-objects, lists, typed values, device information, and commissioning.

- `src/EdsDcfNet/Models/ICanOpenFileModel.cs`
- `src/EdsDcfNet/Models/ObjectDictionary.cs`
- `src/EdsDcfNet/Models/ElectronicDataSheet.cs`
- `src/EdsDcfNet/Models/DeviceConfigurationFile.cs`
- `src/EdsDcfNet/Models/NodelistProject.cs`

XDD/XDC additionally carry CiA 311 application-process structures.

#### Input Parsing Pipeline

Format readers translate external text/XML into the canonical models. INI-oriented EDS/DCF/CPJ parsing shares reader and section infrastructure; XML-oriented XDD/XDC parsing uses a secure XML boundary and specialized parsers for device, communication, and application-process sections.

- `src/EdsDcfNet/Parsers/CanOpenReaderBase.cs`
- `src/EdsDcfNet/Parsers/IniParser.cs`
- `src/EdsDcfNet/Parsers/EdsReader.cs`
- `src/EdsDcfNet/Parsers/XddReader.cs`
- `src/EdsDcfNet/Parsers/SecureXmlParser.cs`

`CanOpenFileOptions` governs cross-format input-size constraints, providing a denial-of-service boundary for untrusted input.

#### Model Editing, Conversion, and Value Semantics

Consumers mutate the model directly. Object-dictionary extensions support indexed lookup, category/PDO queries, and typed parameter reads/writes. Value conversion maps CANopen data types to .NET values and enforces representable ranges. EDS-to-DCF conversion creates a commissioned configuration from a device description.

- `src/EdsDcfNet/Extensions/ObjectDictionaryExtensions.cs`
- `src/EdsDcfNet/Utilities/CanOpenValueConverter.cs`
- `src/EdsDcfNet/Utilities/ValueConverter.cs`
- `src/EdsDcfNet/CanOpenNodeId.cs`

#### Validation and Write Guard

Validation is separate from parsing and serialization: it checks commissioning constraints, device metadata, object-list consistency, and object/sub-object validity, returning path-based issues. Write calls optionally invoke this guard and throw `ModelValidationException`; async paths support cancellation.

- `src/EdsDcfNet/Validation/CanOpenModelValidator.cs`
- `src/EdsDcfNet/Validation/ValidationIssue.cs`
- `src/EdsDcfNet/CanOpenWriteGuard.cs`
- `src/EdsDcfNet/CanOpenWriteOptions.cs`

#### Serialization and External Boundaries

Writers serialize canonical models to DS 306 INI-like files or CiA 311 XML. File/stream output is UTF-8 without BOM. Writer failures are translated into format-specific exceptions, with section/element context where available.

- `src/EdsDcfNet/Writers/IniWriterBase.cs`
- `src/EdsDcfNet/Writers/EdsWriter.cs`
- `src/EdsDcfNet/Writers/DcfWriter.cs`
- `src/EdsDcfNet/Writers/XddWriter.cs`
- `src/EdsDcfNet/Writers/XdcWriter.cs`

The only material external interoperability targets are CANopen files and the NuGet distribution channel; CI/release automation runs through GitHub Actions and semantic-release.

Main entry points: [`src/EdsDcfNet/FormatCanOpenOperations.cs`](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/FormatCanOpenOperations.cs) (Format Operations), [`src/EdsDcfNet/CanOpenFile.cs`](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/CanOpenFile.cs) (CanOpenFile), [`src/EdsDcfNet/Parsers/IniParser.cs`](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Parsers/IniParser.cs) (INI Readers), [`src/EdsDcfNet/Models/ElectronicDataSheet.cs`](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Models/ElectronicDataSheet.cs) (Device File Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_api["CanOpenFile<br/>public facade<br/>[CanOpenFile.cs]"]
  node_format_ops["Format Operations<br/>format router"]
  node_eds_ops["EDS Operations<br/>conversion API"]
  node_read_options["Read Limits<br/>input options"]
end

subgraph group_models["Canonical Models"]
  node_device_models["Device File Models<br/>domain models"]
  node_dcf_model["DCF Model<br/>domain model"]
  node_object_dictionary["Object Dictionary<br/>editable domain model"]
  node_project_model["Network Project<br/>topology model<br/>[NodelistProject.cs]"]
  node_model_editing["Editing &amp; Values<br/>model utilities"]
end

subgraph group_read["Input Pipeline"]
  node_ini_readers["INI Readers<br/>DS 306 parser<br/>[IniParser.cs]"]
  node_xml_readers["XDD/XDC Readers<br/>CiA 311 parser<br/>[XddReader.cs]"]
  node_secure_xml["Secure XML Boundary<br/>XML security<br/>[SecureXmlParser.cs]"]
end

subgraph group_write["Validation &amp; Output"]
  node_validator["Model Validator<br/>validation"]
  node_write_guard["Write Guard<br/>write policy"]
  node_ini_writers["INI Writers<br/>DS 306 serializer<br/>[EdsWriter.cs]"]
  node_xml_writers["XDD/XDC Writers<br/>CiA 311 serializer<br/>[XddWriter.cs]"]
end

node_consumer(("Consumer .NET Process<br/>library consumer"))
node_examples["Usage Example<br/>console example<br/>[Program.cs]"]
node_canopen_files["CANopen Files<br/>interoperability target"]
node_nuget{{"NuGet Distribution<br/>package channel"}}

node_consumer -->|"uses"| node_api
node_examples -.->|"demonstrates"| node_api
node_api -->|"delegates format I/O"| node_format_ops
node_api -->|"exposes EDS operations"| node_eds_ops
node_api -->|"applies limits"| node_read_options
node_format_ops -->|"reads DS 306"| node_ini_readers
node_format_ops -->|"reads CiA 311"| node_xml_readers
node_secure_xml -->|"secures XML input"| node_xml_readers
node_ini_readers -->|"maps EDS/DCF"| node_device_models
node_ini_readers -->|"maps CPJ"| node_project_model
node_xml_readers -->|"maps XDD/XDC"| node_device_models
node_device_models -->|"exposes"| node_object_dictionary
node_dcf_model -->|"contains"| node_object_dictionary
node_model_editing -->|"edits and queries"| node_object_dictionary
node_eds_ops -->|"converts EDS to"| node_dcf_model
node_format_ops -->|"guards writes"| node_write_guard
node_write_guard -->|"invokes"| node_validator
node_format_ops -->|"writes DS 306"| node_ini_writers
node_format_ops -->|"writes CiA 311"| node_xml_writers
node_ini_writers -->|"serializes"| node_canopen_files
node_xml_writers -->|"serializes"| node_canopen_files
node_canopen_files -->|"input"| node_ini_readers
node_canopen_files -->|"XML input"| node_secure_xml
node_nuget -.->|"delivers library"| node_consumer

click node_examples "https://github.com/dborgards/eds-dcf-net/blob/main/examples/EdsDcfNet.Examples/Program.cs"
click node_api "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/CanOpenFile.cs"
click node_format_ops "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/FormatCanOpenOperations.cs"
click node_eds_ops "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/EdsCanOpenOperations.cs"
click node_read_options "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/CanOpenFileOptions.cs"
click node_device_models "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Models/ElectronicDataSheet.cs"
click node_dcf_model "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Models/DeviceConfigurationFile.cs"
click node_object_dictionary "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Models/ObjectDictionary.cs"
click node_project_model "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Models/NodelistProject.cs"
click node_ini_readers "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Parsers/IniParser.cs"
click node_xml_readers "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Parsers/XddReader.cs"
click node_secure_xml "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Parsers/SecureXmlParser.cs"
click node_model_editing "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Extensions/ObjectDictionaryExtensions.cs"
click node_validator "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Validation/CanOpenModelValidator.cs"
click node_write_guard "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/CanOpenWriteGuard.cs"
click node_ini_writers "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Writers/EdsWriter.cs"
click node_xml_writers "https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Writers/XddWriter.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_format_ops,node_eds_ops,node_read_options toneBlue
class node_device_models,node_dcf_model,node_object_dictionary,node_project_model,node_model_editing toneAmber
class node_ini_readers,node_xml_readers,node_secure_xml toneMint
class node_validator,node_write_guard,node_ini_writers,node_xml_writers toneRose
class node_consumer,node_examples,node_canopen_files,node_nuget toneNeutral
```

## Components

### Public API

- [CanOpenFile](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/CanOpenFile.cs): public facade · Canonical sync and async file, stream, and string API. · `src/EdsDcfNet/CanOpenFile.cs`
- [Format Operations](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/FormatCanOpenOperations.cs): format router · Selects format readers/writers and retains caller stream ownership. · `src/EdsDcfNet/FormatCanOpenOperations.cs`
- [EDS Operations](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/EdsCanOpenOperations.cs): conversion API · Owns EDS-to-DCF conversion. · `src/EdsDcfNet/EdsCanOpenOperations.cs`
- [Read Limits](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/CanOpenFileOptions.cs): input options · Cross-format size limits provide the untrusted-input boundary. · `src/EdsDcfNet/CanOpenFileOptions.cs`

### Canonical Models

- [Device File Models](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Models/ElectronicDataSheet.cs): domain models · EDS/XDD descriptions and DCF/XDC configurations. · `src/EdsDcfNet/Models/ElectronicDataSheet.cs`
- [DCF Model](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Models/DeviceConfigurationFile.cs): domain model · `src/EdsDcfNet/Models/DeviceConfigurationFile.cs`
- [Object Dictionary](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Models/ObjectDictionary.cs): editable domain model · Typed objects, sub-objects, lists, values, metadata, and commissioning. · `src/EdsDcfNet/Models/ObjectDictionary.cs`
- [Network Project](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Models/NodelistProject.cs): topology model · CPJ network and project topology. · `src/EdsDcfNet/Models/NodelistProject.cs`
- [Editing & Values](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Extensions/ObjectDictionaryExtensions.cs): model utilities · Provides dictionary queries and range-checked typed value conversion. · `src/EdsDcfNet/Extensions/ObjectDictionaryExtensions.cs`

### Input Pipeline

- [INI Readers](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Parsers/IniParser.cs): DS 306 parser · Shared INI infrastructure reads EDS, DCF, and CPJ. · `src/EdsDcfNet/Parsers/IniParser.cs`
- [XDD/XDC Readers](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Parsers/XddReader.cs): CiA 311 parser · Specialized device, communication, and application-process parsing. · `src/EdsDcfNet/Parsers/XddReader.cs`
- [Secure XML Boundary](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Parsers/SecureXmlParser.cs): XML security · `src/EdsDcfNet/Parsers/SecureXmlParser.cs`

### Validation & Output

- [Model Validator](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Validation/CanOpenModelValidator.cs): validation · Returns path-based model and commissioning issues. · `src/EdsDcfNet/Validation/CanOpenModelValidator.cs`
- [Write Guard](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/CanOpenWriteGuard.cs): write policy · Optionally validates and raises ModelValidationException before output. · `src/EdsDcfNet/CanOpenWriteGuard.cs`
- [INI Writers](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Writers/EdsWriter.cs): DS 306 serializer · Writes EDS and DCF UTF-8 files. · `src/EdsDcfNet/Writers/EdsWriter.cs`
- [XDD/XDC Writers](https://github.com/dborgards/eds-dcf-net/blob/main/src/EdsDcfNet/Writers/XddWriter.cs): CiA 311 serializer · Writes XML device descriptions and configurations. · `src/EdsDcfNet/Writers/XddWriter.cs`

### Other components

- **Consumer .NET Process**: library consumer · Applications use the library in-process.
- [Usage Example](https://github.com/dborgards/eds-dcf-net/blob/main/examples/EdsDcfNet.Examples/Program.cs): console example · `examples/EdsDcfNet.Examples/Program.cs`
- **CANopen Files**: interoperability target · EDS, DCF, CPJ, XDD, and XDC input/output.
- **NuGet Distribution**: package channel

## Connections

- Consumer .NET Process → CanOpenFile: uses
- Usage Example → CanOpenFile: demonstrates
- CanOpenFile → Format Operations: delegates format I/O
- CanOpenFile → EDS Operations: exposes EDS operations
- CanOpenFile → Read Limits: applies limits
- Format Operations → INI Readers: reads DS 306
- Format Operations → XDD/XDC Readers: reads CiA 311
- Secure XML Boundary → XDD/XDC Readers: secures XML input
- INI Readers → Device File Models: maps EDS/DCF
- INI Readers → Network Project: maps CPJ
- XDD/XDC Readers → Device File Models: maps XDD/XDC
- Device File Models → Object Dictionary: exposes
- DCF Model → Object Dictionary: contains
- Editing & Values → Object Dictionary: edits and queries
- EDS Operations → DCF Model: converts EDS to
- Format Operations → Write Guard: guards writes
- Write Guard → Model Validator: invokes
- Format Operations → INI Writers: writes DS 306
- Format Operations → XDD/XDC Writers: writes CiA 311
- INI Writers → CANopen Files: serializes
- XDD/XDC Writers → CANopen Files: serializes
- CANopen Files → INI Readers: input
- CANopen Files → Secure XML Boundary: XML input
- NuGet Distribution → Consumer .NET Process: delivers library