uml4net 5.1.0

Introduction

Uml4net is a suite of dotnet core libraries and tools that are used to deserialize (read) and serialize (write) a UML version 2.5.1 model in XMI 2.5.1 form. Uml4net is typically used to support opinionated template based code-generation and is a part of modeltopia. Uml4net provides a number of libraries that are described in the following sections.

uml4net

The core library that contains all the class definitions as they appear in the UML 2.5.1 specification. Together with uml4net.xmi it provides the capability to read and write UML models and make them available as an in-memory object graph. The derived properties of the metamodel are implemented, and the owner ends of composite associations are kept in sync with the containment.

uml4net.Extensions

The uml4net.Extensions library provides extensions methods to the uml4net library to support code generation. This library is part of the uml4net ecosystem.

uml4net.xmi

The uml4net.xmi library provides an XMI reader implementation to read UML XMI model files and an XMI writer implementation to write UML models to XMI:

• Reading: references to other documents are resolved, also across documents found on disk or through path maps; stereotype applications are resolved against their profile and their tagged values are typed; content uml4net does not model, such as UML Diagram Interchange, is captured. In strict mode (the default) a document that is not valid XMI 2.5.1 is rejected with an exception that names the element, property and line position; otherwise the problem is logged and reading continues.
• Writing: a model is written as it was read, including its documentation, MOF tags, stereotype applications and captured content, so that a document survives a read-write cycle. A selected Package can be written as well, where references to elements outside the selected package are either written as href references to the original document or the containing root packages are included in the written document, resulting in a self-contained XMI file. The writer can also write Canonical XMI (XMI 2.5.1 Annex B).

To learn more about how to read and write a UML model, read about it here

uml4net.xmi.Extensions.EnterpriseArchitect

The uml4net.xmi.Extensions.EnterpriseArchitect library is a specific XMI Reader extension to support Enterprise Architect XMI reading.

uml4net.HandleBars

The uml4net.HandleBars library provides HandleBars helpers to support code generation. This library is part of the uml4net ecosystem.

uml4net.Reporting

The uml4net.Reporting library contains reporting generators. This library is part of the uml4net ecosystem.

uml4net.Tools

The uml4net.Tools commandline application is used to generate reports on the content of the UML model. Find the documentation here.

Code Quality

Installation

The packages are available on Nuget at:

• uml4net:
• uml4net.Extensions:
• uml4net.xmi:
• uml4net.HandleBars:
• uml4net.Reporting:
• uml4net.Tools:
• uml4net.xmi.Extensions.EnterpriseArchitect:

Reading a UML model

Reading a UML model is straightforward and is done using an IXmiReader. An instance of IXmiReader is created using the XmiReaderBuilder. Once the reader is available, point it to a UML model you want to read and you're off to the races:

var reader = XmiReaderBuilder.Create()
    .Build();

var xmiReaderResult = reader.Read("path-to-your-model");

var rootPackage = xmiReaderResult.QueryRoot("<xmi:id-of-the-root-package-you-are-interested-in>");

The IXmiReader can be configured with an IXmiReaderSettings, read more about reading an XMI document here

The IXmiReader is able to read and process StereoTypes as they are applied to UML model elements. Read more about that here

Writing a UML model

A UML model is written using an IXmiWriter, which is created using the XmiWriterBuilder. Writing the top-level elements of the document that was read, together with its XmiRoot, writes the whole document back:

var writer = XmiWriterBuilder.Create()
    .Build();

writer.Write(xmiReaderResult.DocumentRootElements, "path-to-the-written-model", xmiReaderResult.XmiRoot);

The IXmiWriter can be configured with an IXmiWriterSettings, for example to write Canonical XMI; read more about writing an XMI document here

Design Decisions

Some choices in uml4net are deliberate and can look surprising at first, such as single-valued composite properties exposed as IContainerList<T>, UnlimitedNatural values as string, or the order in which the writer writes the properties. They are recorded, with their reasons, in design-decisions.md.

Build Status

GitHub actions are used to build and test the uml4net libraries

Branch	Build Status
Master
Development

UML Documentation

The Object Management Group (OMG) is an international technology standards consortium. It was founded in 1989 with the goal of creating and maintaining vendor-neutral, interoperable, and portable standards for distributed computing. UML is one of the standards provided by OMG at http://www.omg.org/spec/UML/

Software Bill of Materials (SBOM)

As part of our commitment to security and transparency, this project includes a Software Bill of Materials (SBOM) in the associated NuGet packages. The SBOM provides a detailed inventory of the components and dependencies included in the package, allowing you to track and verify the software components, their licenses, and versions.

Why SBOM?

• Improved Transparency: Gain insight into the open-source and third-party components included in this package.
• Security Assurance: By providing an SBOM, we enable users to more easily track vulnerabilities associated with the included components.
• Compliance: SBOMs help ensure compliance with licensing requirements and make it easier to audit the project's dependencies.

You can find the SBOM in the NuGet package itself, which is automatically generated and embedded during the build process.

License

The uml4net libraries are provided to the community under the Apache License 2.0.

Contributions

Contributions to the code-base are welcome. However, before we can accept your contributions we ask any contributor to sign the Contributor License Agreement (CLA) and send this digitally signed to s.gerene@stariongroup.eu. You can find the CLA's in the CLA folder.

Contribution guidelines for this project