Skip to content

README.md

Latest commit

 

History

History
329 lines (266 loc) · 9.72 KB

README.md

File metadata and controls

329 lines (266 loc) · 9.72 KB

TX Text Control Document Repository

A comprehensive document management library built with TX Text Control that provides version control and metadata management.

📋 Overview

The TX Text Control Document Repository is a .NET library that implements a file-based document repository with full version control support. It enables applications to store, manage, and track changes to documents with features similar to enterprise document management systems.

✨ Features

Core Capabilities

  • Version Control: Automatic versioning for all document changes
  • Metadata Management: Store document title, subject, tags, status, and custom metadata
  • Document Search: Full-text search across documents with advanced filtering
  • Version Restoration: Restore any previous version of a document
  • Content Comparison: Track changes between document versions
  • Concurrent Access: Thread-safe operations for multi-user scenarios

Document Operations

  • Create new documents with initial metadata
  • Save new versions of existing documents (automatic versioning)
  • Retrieve document metadata and version history
  • Get content for specific document versions
  • Search documents by title, subject, tags, author, and status
  • Restore previous versions

Metadata Support

  • Title: Document name/title
  • Subject: Brief description
  • Tags: Multiple tags for categorization
  • Status: Document lifecycle state (draft, active, archived)
  • Author: Document creator/owner
  • Comments: Version-specific change notes
  • Timestamps: Created and modified dates (UTC)
  • File Information: Original filename, MIME type, file size

🏗️ Architecture

Repository Structure

DocumentRepository/
├── Documents/
│   └── {DocumentId}/
│       ├── metadata.json          # Document-level metadata
│       └── versions/
│           ├── v1/
│           │   ├── metadata.json  # Version-specific metadata
│           │   └── content.tx     # Document content
│           ├── v2/
│           └── ...

Key Components

IFileDocumentRepository

Main interface for all repository operations:

  • CreateDocumentAsync() - Create new documents
  • SaveNewVersionAsync() - Save new versions of existing documents
  • GetDocumentAsync() - Retrieve document metadata and version history
  • GetVersionContentAsync() - Get specific version content
  • ListDocumentsAsync() - List all documents in the repository
  • SearchDocumentsAsync() - Advanced search with filters
  • RestoreVersionAsync() - Restore previous versions

FileDocumentRepository

Default implementation using file system storage with:

  • Concurrent access protection
  • Atomic write operations
  • Efficient file I/O
  • Comprehensive error handling

🚀 Getting Started

Prerequisites

  • .NET 8.0 or higher
  • TX Text Control SDK 34.0.3 or higher

Installation

Add a direct reference to the compiled library (no NuGet package is provided):

<ItemGroup>
  <Reference Include="TXTextControl.DocumentRepository">
    <HintPath>path/to/TXTextControl.DocumentRepository.dll</HintPath>
  </Reference>
</ItemGroup>

Basic Usage

Initialize Repository

using TXTextControl.DocumentRepository.Repositories;

var repositoryPath = Path.Combine(Directory.GetCurrentDirectory(), "DocumentRepository");
IFileDocumentRepository repository = new FileDocumentRepository(repositoryPath);

Create a Document

var versionMetadata = await repository.CreateDocumentAsync(
    title: "Employment Contract",
    createdBy: "John Doe",
    fileName: "Contract.tx",
    mimeType: "application/vnd.textcontrol",
    content: documentBytes,
    subject: "New employee agreement",
    comment: "Initial draft",
    tags: new[] { "contract", "hr", "legal" },
    cancellationToken: CancellationToken.None
);

Guid documentId = versionMetadata.DocumentId;

Search Documents

using TXTextControl.DocumentRepository.Models;

var searchRequest = new SearchDocumentsRequest
{
    TitleContains = "contract",
    RequireAllTags = new List<string> { "legal" },
    Status = "active",
    CreatedByContains = "John Doe",
    MaxResults = 50
};

var results = await repository.SearchDocumentsAsync(searchRequest, CancellationToken.None);

foreach (var doc in results.Documents)
{
    Console.WriteLine($"{doc.Title} - Version {doc.CurrentVersion}");
}

Save a New Version

var saveRequest = new SaveDocumentRequest
{
    DocumentId = documentId,
    ExpectedCurrentVersion = 1,
    FileName = "Contract.tx",
    MimeType = "application/vnd.textcontrol",
    CreatedBy = "Jane Smith",
    Comment = "Added salary details",
    Content = updatedBytes
};

await repository.SaveNewVersionAsync(saveRequest, CancellationToken.None);

Restore Previous Version

await repository.RestoreVersionAsync(
    documentId: documentId,
    versionToRestore: 2,
    expectedCurrentVersion: 4,
    restoredBy: "Admin",
    comment: "Reverted to version 2",
    cancellationToken: CancellationToken.None
);

Get Document Content

byte[] content = await repository.GetVersionContentAsync(
    documentId: documentId,
    version: 3,
    cancellationToken: CancellationToken.None
);

List All Documents

var documents = await repository.ListDocumentsAsync(CancellationToken.None);

foreach (var doc in documents)
{
    Console.WriteLine($"{doc.Title} - {doc.CurrentVersion} version(s)");
}

⚙️ Configuration

Repository Settings

// Custom repository path
var repository = new FileDocumentRepository("/custom/path/to/repo");

// The repository will automatically create the necessary directory structure

File Organization

  • Each document is stored in a separate folder identified by GUID
  • Versions are stored sequentially (v1, v2, v3, etc.)
  • Metadata is stored in JSON format for easy inspection and portability
  • Content files use TX Text Control's internal format

🔥 Advanced Features

Version History Tracking

Every version maintains:

  • Complete document content
  • Version-specific metadata
  • Author information
  • Timestamp
  • Change comments
  • Restoration tracking (if version was restored from another)

Search Capabilities

Search supports:

  • Text matching: Title and subject
  • Tag filtering: Multiple tags (AND operation)
  • Author filtering: Exact match
  • Status filtering: Document lifecycle state
  • Result limiting: Control result set size
  • Pagination: Via MaxResults parameter

ServerTextControl Integration

The library includes extension methods for seamless integration with TX Text Control's ServerTextControl:

using TXTextControl.DocumentRepository.Extensions;

// Save current document to repository as new document
var metadata = await textControl.SaveToRepositoryAsNewAsync(
    repository: repository,
    fileName: "Document.tx",
    streamType: BinaryStreamType.InternalUnicodeFormat,
    comment: "Initial version",
    cancellationToken: CancellationToken.None
);

// Save new version of existing document
await textControl.SaveToRepositoryAsync(
    repository: repository,
    documentId: documentId,
    comment: "Updated content",
    cancellationToken: CancellationToken.None
);

// Load document from repository
await textControl.LoadFromRepositoryAsync(
    repository: repository,
    documentId: documentId,
    version: 3, // optional - loads current version if omitted
    cancellationToken: CancellationToken.None
);

⚠️ Error Handling

The library provides specific exceptions:

  • DocumentNotFoundException: Document or version not found
  • InvalidOperationException: Invalid state or operation
  • IOException: File system errors
  • OperationCanceledException: Cancelled operations

Example:

try
{
    var doc = await repository.GetDocumentAsync(documentId, ct);
}
catch (DocumentNotFoundException ex)
{
    Console.WriteLine($"Document not found: {ex.Message}");
}

🧪 Testing

The repository is designed to be easily testable:

  • Interface-based design (IFileDocumentRepository)
  • Dependency injection friendly
  • Isolated file system operations
  • Cancellation token support

📦 Dependencies

  • TXTextControl.TextControl.Core.SDK (34.0.3): Core TX Text Control functionality
  • .NET 8.0: Target framework

🔌 Integration

This library is a .NET class library that can be integrated into any .NET application:

  • Console applications
  • Desktop applications (WinForms, WPF)
  • ASP.NET Core web applications
  • Background services and workers
  • Azure Functions

The repository operations are async and support cancellation tokens, making it suitable for both synchronous and asynchronous workflows.

📄 License

This library uses TX Text Control SDK which requires a valid license for production use. Visit https://www.textcontrol.com for licensing information.

🤝 Contributing

Contributions are welcome! Please ensure:

  • Code follows existing patterns
  • All public APIs are documented
  • Error handling is comprehensive
  • Thread safety is maintained

💬 Support

For TX Text Control related questions:

🗺️ Roadmap

Potential future enhancements:

  • Database storage backend option (in addition to file-based storage)
  • Document locking/checkout mechanism
  • Enhanced audit trail and change tracking
  • Bulk operations support
  • Cloud storage integration (Azure Blob, AWS S3)
  • Content-based search indexing
  • Document comparison utilities
  • Archive/compression for older versions

Built with ❤️ using TX Text Control