Quick Start

This page takes you from an empty project to reading and writing ReqIF documents. Each step links to a page with more detail.

1. Install

dotnet new console -n ReqIFDemo
cd ReqIFDemo
dotnet add package ReqIFSharp
dotnet add package ReqIFSharp.Extensions

ReqIFSharp.Extensions is optional. This page uses one of its methods, QueryAllContainedSpecObjects, to walk a specification tree.

No ReqIF file at hand? Download the ProR traceability template from the test data of this repository.

2. Read a document

using ReqIFSharp;
using ReqIFSharp.Extensions.ReqIFExtensions;

var deserializer = new ReqIFDeserializer();
var reqif = deserializer.Deserialize("ProR_Traceability-Template-v1.0.reqif").First();

Console.WriteLine($"{reqif.TheHeader.Title}, exported by {reqif.TheHeader.SourceToolId}");

foreach (var specification in reqif.CoreContent.Specifications)
{
    Console.WriteLine(specification.LongName);

    foreach (var specObject in specification.QueryAllContainedSpecObjects())
    {
        foreach (var value in specObject.Values)
        {
            var text = value is AttributeValueXHTML xhtml
                ? xhtml.ExtractUnformattedTextFromValue()
                : value.ObjectValue?.ToString();

            Console.WriteLine($"  {value.AttributeDefinition.LongName}: {text}");
        }
    }
}

Deserialize returns an IEnumerable<ReqIF> because a .reqifz archive can hold more than one document. For a single .reqif file, take the First().

Each ReqIF has two parts:

• TheHeader: the title, the tool that created the file, and when it was created.
• CoreContent: the requirements themselves, their types and the links between them.

ReqIF Concepts explains how the parts of CoreContent fit together.

3. Validate while reading

Pass true and a handler to check the document against the ReqIF XML schema:

var reqif = deserializer.Deserialize(
        "ProR_Traceability-Template-v1.0.reqif",
        validate: true,
        validationEventHandler: (sender, e) => Console.WriteLine($"{e.Severity}: {e.Message}"))
    .First();

Without a handler, the first schema error throws an exception. More in Reading ReqIF.

4. Write a document

var content = new ReqIFContent();
var reqif = new ReqIF
{
    Lang = "en",
    TheHeader = new ReqIFHeader
    {
        Identifier = "header-1",
        Title = "Coffee machine",
        CreationTime = DateTime.UtcNow,
        ReqIFToolId = "ReqIFDemo",
        ReqIFVersion = "1.0",
        SourceToolId = "ReqIFDemo"
    },
    CoreContent = content
};

var text = new DatatypeDefinitionString { Identifier = "dt-text", LongName = "Text", MaxLength = 1000, LastChange = DateTime.UtcNow };
var textAttribute = new AttributeDefinitionString { Identifier = "ad-text", LongName = "Text", Type = text, LastChange = DateTime.UtcNow };
var requirementType = new SpecObjectType { Identifier = "sot-req", LongName = "Requirement", LastChange = DateTime.UtcNow };
requirementType.SpecAttributes.Add(textAttribute);

var requirement = new SpecObject { Identifier = "req-1", Type = requirementType, LastChange = DateTime.UtcNow };
requirement.Values.Add(new AttributeValueString { Definition = textAttribute, TheValue = "The machine shall brew a cup in under 30 seconds." });

content.DataTypes.Add(text);
content.SpecTypes.Add(requirementType);
content.SpecObjects.Add(requirement);

var serializer = new ReqIFSerializer();
serializer.Serialize(new[] { reqif }, "coffee.reqif");

The file extension decides the format: .reqif writes XML, .reqifz or .zip writes a zip archive. Writing ReqIF builds a complete document with a specification tree and trace links.

5. Go async

Every method has an asynchronous variant that takes a CancellationToken:

var reqifs = await deserializer.DeserializeAsync("requirements.reqifz", cancellationToken);
await serializer.SerializeAsync(reqifs, "copy.reqifz", cancellationToken);

Next steps

• Reading ReqIF: streams, archives, typed attribute values, attachments and logging
• Writing ReqIF: all the pieces of a document you can create
• ReqIFSharp.Extensions: less code for common questions