LSchuster.HL7MessageProcessor 1.0.7

HL7 .Net Message Processor

LSCH.HL7MessageProcessor is a .NET library for parsing and working with HL7 v2.x messages. It provides structured access to message headers and values without mutating the input string, making it suitable for read-only inspection, validation, and routing scenarios.

Features

• 🔍 Deep field access by segment name and component indices
• 🧩 Immutable HL7ReadonlyMessage wrapper
• 🔁 Mutable transformations with HL7TransformableMessage for editing HL7 content
• ✅ HL7-compliant header parsing (MSH segment)
• 🧾 Automatic ACK generation (CA, AE, AR, CR, CE) with error message support
• 🧪 Tested with xUnit and FluentAssertions
• ⚙️ Optimized for performance with ReadOnlySpan<char>

Install via NuGet

dotnet add package LSchuster.HL7MessageProcessor

Or via NuGet Package Manager:

Install-Package LSchuster.HL7MessageProcessor

🚀 Quick Start

using LSCH.HL7MessageProcessor;

// Load an HL7 message
var rawMessage = File.ReadAllText("some-message.hl7");

// Create a readonly HL7 message wrapper
var hl7 = new HL7ReadonlyMessage(rawMessage);

// ✅ Access message header fields
var sendingApp = hl7.Header.SendingApplication;
var messageDate = hl7.Header.ParsedDateTime;

// ✅ Extract a single field value (e.g., PID-3.1)
string patientId = hl7.GetValue("PID", 3, 1);

// ✅ Extract values across repeated segments (e.g., OBR-4.2 from all OBRs)
IReadOnlyList<string> values = hl7.GetValues("OBR", 4, 2);

// ✅ Use HL7 field path notation (e.g., "OBR-4.2", "PID-5.1.2")
string id = hl7.GetValue("PID-3.1");
IReadOnlyList<string> lipidTestCodes = hl7.GetValues("OBR-4.1");

// ✅ Validate structural correctness
bool isValid = hl7.IsValid();

// ✅ Detect if the message is an HL7 acknowledgment
bool isAck = hl7.IsAcknowledgment();
Console.WriteLine($"Is ACK? {isAck}");

// ✅ Generate an ACK in response
if (!isAck && isValid)
{
    var ack = hl7.GenerateAcknowledgement(
        switchSenderAndReceiver: true,
        acknowledgmentCode: "AE", // "CA" = Accept, "AE" = App Error, "AR" = App Reject, etc.
        errorMessage: "Missing required field: PID-5"
    );

    string ackRaw = ack.ToString();
    Console.WriteLine("Generated ACK:\n" + ackRaw);
}

✏️ Modify the HL7 Message (Transformable)

// Use HL7TransformableMessage for write access
var transformable = new HL7TransformableMessage(rawMessage);

// Redact patient name (e.g., PID-5)
transformable.SetValue("PID", "REDACTED", 5);

// Remove all NTE segments
transformable.RemoveSegments("NTE");

// Add a custom Z-segment
transformable.AddSegment("ZBX", "Custom|Value|Here");

// Get the updated HL7 message
string updatedMessage = transformable.ToString();
File.WriteAllText("transformed.hl7", updatedMessage);

Testing

The library includes a dedicated xUnit test project that uses real HL7 sample messages. Tests verify structural parsing, header field correctness, and field access methods.

Run tests locally:

dotnet test

Project Structure

src/
  HL7MessageProcessor/             # Library project
test/
  HL7MessageProcessor.Tests/      # xUnit test project
  └── TestData/                   # Contains sample .hl7 files

License

This project is licensed under the MIT License.

Links

• NuGet Package
• GitHub Repository

Author

GitHub @LSchuster