{"id":21271542,"url":"https://github.com/warappa/opentranssharp","last_synced_at":"2025-07-11T05:32:56.538Z","repository":{"id":43680544,"uuid":"341362539","full_name":"warappa/OpenTransSharp","owner":"warappa","description":"Read/edit/write/validate BMEcat® and openTRANS® xml files.","archived":false,"fork":false,"pushed_at":"2024-07-06T07:53:06.000Z","size":39217,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-11-10T04:20:53.647Z","etag":null,"topics":["bmecat","bmecat2005","csharp","dotnet","dotnet-core","opentrans","opentrans-21"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/warappa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-BMEcat.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-02-22T23:03:00.000Z","updated_at":"2024-09-13T13:21:27.000Z","dependencies_parsed_at":"2024-01-03T19:53:03.189Z","dependency_job_id":null,"html_url":"https://github.com/warappa/OpenTransSharp","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warappa%2FOpenTransSharp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warappa%2FOpenTransSharp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warappa%2FOpenTransSharp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warappa%2FOpenTransSharp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/warappa","download_url":"https://codeload.github.com/warappa/OpenTransSharp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225697196,"owners_count":17509890,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bmecat","bmecat2005","csharp","dotnet","dotnet-core","opentrans","opentrans-21"],"created_at":"2024-11-21T08:27:00.659Z","updated_at":"2024-11-21T08:27:01.098Z","avatar_url":"https://github.com/warappa.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"### OpenTransSharp and BMEcatSharp\n[![openTRANS](https://img.shields.io/badge/openTRANS-2.1-%230b0?color=%230b0\u0026labelColor=7D8D75)](https://de.wikipedia.org/wiki/OpenTRANS) \n[![BMEcat](https://img.shields.io/badge/BMEcat-%202005-%230b0?color=%230b0\u0026labelColor=7D8D75)](https://de.wikipedia.org/wiki/BMEcat)\n[![Supports .NET](https://img.shields.io/badge/-.NET%20Standard%202.0%20%7C%20%20.NET%206+-%230b0?color=%230b0\u0026logo=dotnet\u0026labelColor=5A27D5)](https://www.nuget.org/packages?q=id%3Aopentranssharp+id%3Abmecatsharp)  \n[![NuGet](https://img.shields.io/nuget/v/OpenTransSharp.svg?logo=nuget\u0026labelColor=04487D)](https://www.nuget.org/packages?q=id%3Aopentranssharp+id%3Abmecatsharp)\n [![Downloads](https://img.shields.io/nuget/dt/OpenTransSharp?logo=nuget\u0026labelColor=04487D)](https://www.nuget.org/packages?q=id%3Aopentranssharp+id%3Abmecatsharp)\n[![MPL-2.0 License](https://img.shields.io/github/license/warappa/OpenTransSharp?color=%230b0\u0026logo=internetarchive)](https://github.com/warappa/OpenTransSharp/blob/main/LICENSE.md)  \n\n#### About This Project\n\nThis project enables **reading, editing, writing and validating openTRANS® 2.1 and BMEcat® 2005 files**.\nWhile developing, your **IntelliSense** is enriched with contents of the official specification-documents.\nIt also provides seamless integration into **Microsoft.Extensions.DependencyInjection** and **ASP.NET Core**.\n\nThis project is built on the **[.NET](https://dot.net)** platform and uses the **MPL 2.0 license** (see [MPL 2.0 TLDR;](#mpl-20-TLDR) for what that means for you).\n\n#### Features\n\n* Compatible with **.NET Standard 2.0** or **.NET 6+**\n* **Rich IntelliSense** extended with contents of the official specification-documents\n  * Meaning of elements/attributes\n  * Required elements\n  * Choices between elements\n* **Reading/editing/writing** BMEcat®- and openTRANS®-files\n  * **Enums** where possible, like `LanguageCodes`, `Unit`, `PackageUnit`, `CountryCode`, `OrderType`, `MimePurpose`, `PartyRole`,... and many more\n* **Validation** against official XSDs\n  * Including adding **custom XSD validations** (see UDX below)\n* Proper support for **User-Defined-Extension** data (UDX)\n  * Enhance your documents with **custom data**\n* **Microsoft.Extensions.DependencyInjection** integration\n  * **Extension methods** for service registration (with optional options)\n* **ASP.NET Core** integration\n  * **Model-binding** support\n  * **Model state** support\n  * **Custom encodings and content-types** support\n* **BMEcat® 2005** support\n  * Module **Classification Systems, Catalog Groups Systems, and Feature Systems**\n  * Module **Product Configuration**\n  * Module **Price Formulas**\n  * Module **Integrated Procurement Point**\n  * **Multilingual Strings**\n* **openTRANS® 2.1** support\n  * **RFQ** (request for quotation)\n  * **Quotation**\n  * **Order**\n  * **Order-Change**\n  * **Order-Response** (confirmation of order)\n  * **Dispatch-Notification**\n  * **Receipt-Acknowledgement** (acknowledgement of receipt of goods)\n  * **Invoice**\n  * **Invoice-List** (collective invoice)\n  * **Remittance-Advice** (Notification or remittance)\n  * **Multilingual Strings**\n\n### Usage\n\n#### Reading\n\nHere are **3 ways** of reading a openTRANS®-document in **ASP.NET Core**:\n\n**Note**: for BMEcat®-documents, it works the same way, but using `IBMEcatXmlSerializerFactory` instead of `IOpenTransXmlSerializerFactory`.\n\n```csharp\n...\nusing OpenTransSharp;\nusing OpenTransSharp.Validation;\nusing OpenTransSharp.Xml;\n...\n[ApiController]\n[Route(\"[controller]\")]\npublic class ValidationController : ControllerBase\n{\n    private readonly IOpenTransXmlSerializerFactory serializerFactory;\n\n    public ValidationController(IOpenTransXmlSerializerFactory serializerFactory)\n    {\n        this.serializerFactory = serializerFactory ?? throw new ArgumentNullException(nameof(serializerFactory));\n    }\n\n    [HttpPost(\"via-model-binding\")]\n    public void ViaModelBinding(Order order)\n    {\n        // validation implicitly by model binder\n    }\n\n    [HttpPost(\"via-stream\")]\n    public void ViaStream()\n    {\n        var serializer = serializerFactory.Create\u003cOrder\u003e();\n\n        using var stream = Request.BodyReader.AsStream();\n        var document = serializer.Deserialize\u003cOrder\u003e(stream);\n\n        document.EnsureValid(serializer);\n        // or manually validate your document\n        //var validationResult = document.Validate(serializer);\n    }\n\n    [HttpPost(\"via-file\")]\n    public void ViaFile(IFormFile file)\n    {\n        var serializer = serializerFactory.Create\u003cOrder\u003e();\n\n        var stream = file.OpenReadStream();\n        var document = serializer.Deserialize\u003cOrder\u003e(stream);\n\n        document.EnsureValid(serializer);\n    }\n}\n```\n\n#### Editing and Writing\n\nopenTRANS®- and BMEcat®-documents can be easily **modelled like any other C# Type**.\n\n**Rich IntelliSense** helps you building the documents in the right, valid way, be leveraging the content of the specifications.\n\n```csharp\nusing OpenTransSharp;\nusing OpenTransSharp.Xml;\n...\nvar serializer = serializerFactory.Create\u003cOrder\u003e();\n\nvar document = new Order()\n{\n\tType = OrderType.Express    \n}\ndocument.Header = new OrderHeader\n{\n    ControlInformation = new ControlInformation\n    {\n        GenerationDate = DateTime.UtcNow,\n        GeneratorInfo = \"Demo\"\n    },\n    SourcingInformation = new SourcingInformation { ... }\n    ...\n};\ndocument.Items.Add(new OrderItem\n{\n    LineItemId = \"1\",\n    ProductId = new ProductId \n    { \n        SupplierPid = new SupplierPid(\"A0123456789\", SupplierPidTypeValues.Ean);    \n    },\n    Quantity = 2,\n    OrderUnit = PackageUnit.C62, // pieces\n    ...\n});\n\nvar serializedString = serializer.Serialize(document);\n```\n\n#### Validation\n\nYou can **validate all root-documents** like `BMEcatDocument`, `Order`, `Invoice`,... against the **official XSDs** - without having to fiddle with them. Validation is easy with the provided `Validate` extensions method.\n\nYou can manually validate you documents like this:\n\n```csharp\nusing OpenTransSharp;\nusing OpenTransSharp.Validation;\nusing OpenTransSharp.Xml;\n// if you want to validate BMEcat® documents use the following namespaces:\n//using BMEcatSharp;\n//using BMEcatSharp.Validation;\n//using BMEcatSharp.Xml;\n...\nvar validationResult = order.Validate(serializer);\n\nif (!validationResult.IsValid)\n{\n    foreach(var error in validationResult.Errors)\n    {\n    \tforeach(var message in error.Value)\n        {\n            Console.WriteLine($\"{error.Key}: {message}\");\n        }\n    }\n}\n```\n\nOr you can just call `EnsureValid`, which throws a `OpenTransSharp.Validation.ValidationException` if not valid:\n\n```csharp\norder.EnsureValid(serializer);\n```\n\n### Setup Your Project\n\nBMEcatSharp and OpenTransSharp can be used in any **.NET Standard 2.0** compatible or **.NET 6+** project.\n\n**Note**: For **complete samples** of how to use this library, please see the code samples in this repository under\n\n* [BMEcatSharp.Samples.AspNetCore](https://github.com/warappa/OpenTransSharp/tree/main/BMEcatSharp.Samples.AspNetCore) and\n* [OpenTransSharp.Samples.AspNetCore](https://github.com/warappa/OpenTransSharp/tree/main/OpenTransSharp.Samples.AspNetCore)\n\n#### NuGet Packages\n\nDepending on the desired integrations, you can pick **1 of 3 options**:\n\n**A)** If you want to integrate with **ASP.NET Core**, you can use the following NuGet packages:\n\n* [![NuGet](https://img.shields.io/nuget/v/BMEcatSharp.Microsoft.AspNetCore.svg)](https://nuget.org/packages/BMEcatSharp.Microsoft.AspNetCore) [BMEcatSharp.Microsoft.AspNetCore](https://nuget.org/packages/BMEcatSharp.Microsoft.AspNetCore)\n* [![NuGet](https://img.shields.io/nuget/v/OpenTransSharp.Microsoft.AspNetCore.svg)](https://nuget.org/packages/OpenTransSharp.Microsoft.AspNetCore) [OpenTransSharp.Microsoft.AspNetCore](https://nuget.org/packages/OpenTransSharp.Microsoft.AspNetCore)\n\n**Note**: You need *both* if you want to read/edit/write/validate BMEcat®- *and* openTRANS®-documents in your project.\n\n**B)** Otherwise, if you only want to integrate with **Microsoft.Extensions.DependencyInjection**, you can use the following NuGet packages:\n\n* [![NuGet](https://img.shields.io/nuget/v/BMEcatSharp.Microsoft.Extensions.DependencyInjection.svg)](https://nuget.org/packages/BMEcatSharp.Microsoft.Extensions.DependencyInjection) [BMEcatSharp.Microsoft.Extensions.DependencyInjection](https://nuget.org/packages/BMEcatSharp.Microsoft.Extensions.DependencyInjection)\n* [![NuGet](https://img.shields.io/nuget/v/OpenTransSharp.Microsoft.Extensions.DependencyInjection.svg)](https://nuget.org/packages/OpenTransSharp.Microsoft.Extensions.DependencyInjection)[ OpenTransSharp.Microsoft.Extensions.DependencyInjection](https://nuget.org/packages/OpenTransSharp.Microsoft.Extensions.DependencyInjection)\n\n**Note**: You need *both* if you want to read/edit/write/validate BMEcat®- and openTRANS®-documents in your project.\n\n**C)** And finally, if you don't need any of the above integrations but **only core funcationality**, you can use the following NuGet packages:\n\n* [![NuGet](https://img.shields.io/nuget/v/BMEcatSharp.svg)](https://nuget.org/packages/BMEcatSharp) [BMEcatSharp](https://nuget.org/packages/BMEcatSharp) - if you only need BMEcatSharp\n* [![NuGet](https://img.shields.io/nuget/v/OpenTransSharp.svg)](https://nuget.org/packages/OpenTransSharp) [OpenTransSharp](https://nuget.org/packages/OpenTransSharp) - if you need OpenTransSharp (has a dependency on BMEcatSharp)\n\n#### ASP.NET Core Setup\n\nRegistering the ASP.NET Core integrations as shown here.\nThese integrations add input formatters for **model-binding** and **model-state** handling.\n\n##### OpenTransSharp\n\n```csharp\npublic void ConfigureServices(IServiceCollection services)\n{\n    services.AddOpenTransSharp(configure =\u003e\n    {\n        // optional: register your custom UDX (user defined extension) types here\n        configure.Serialization.IncludeUdxTypes = new[]\n        {\n            typeof(CustomData),\n            typeof(CustomData2)\n        };\n\n        // optional: add custom xsd for validation\n        configure.Serialization.XsdUris = new[] { new Uri($\"file://{Environment.CurrentDirectory.Replace(\"\\\\\", \"/\")}/CustomData.xsd\") };\n\n        // optional: add xml-file encodings that must be supported\n        configure.Serialization.SupportedEncodings.Add(\"iso-8859-1\");\n\n        // optional: add xml-file content types that must be supported\n        configure.Serialization.SupportedMediaTypes.Add(\"text/xml\");\n\n        // optional: if you need more control here the overrides can be customized\n        configure.Serialization.ConfigureXmlAttributeOverrides = overrides =\u003e\n        {\n            // add overrides\n        };\n    });\n    services.AddControllers()\n        // register for proper serialization over API\n        .AddOpenTransSharpXmlSerializer();\n    ...\n}\n```\n\n##### BMEcatSharp\n\n```csharp\npublic void ConfigureServices(IServiceCollection services)\n{\n    services.AddBMEcatSharp(configure =\u003e\n    {\n        // optional: register your custom UDX (user defined extension) types here\n        configure.Serialization.IncludeUdxTypes = new[]\n        {\n            typeof(CustomData),\n            typeof(CustomData2)\n        };\n\n        // optional: add custom xsd for validation\n        configure.Serialization.XsdUris = new[] { new Uri($\"file://{Environment.CurrentDirectory.Replace(\"\\\\\", \"/\")}/CustomData.xsd\") };\n\n        // optional: add xml-file encodings that must be supported\n        configure.Serialization.SupportedEncodings.Add(\"iso-8859-1\");\n\n        // optional: add xml-file content types that must be supported\n        configure.Serialization.SupportedMediaTypes.Add(\"text/xml\");\n\n        // optional: if you need more control here the overrides can be customized\n        configure.Serialization.ConfigureXmlAttributeOverrides = overrides =\u003e\n        {\n            // add overrides\n        };\n    });\n    services.AddControllers()\n        // register for proper serialization over API\n        .AddBMEcatSharpXmlSerializer();\n    ...\n}\n```\n\n#### Microsoft.Extensions.DependencyInjection Setup\n\nIf don't need ASP.NET Core but `Microsoft.Extensions.DependencyInjection` integration, the previous sample sections calling \n\n* `services.AddBMEcatSharp(...)` respectively \n* `services.AddOpenTransSharp(...)` \n\nare the actual `Microsoft.Extensions.DependencyInjection` integration.\n\n#### Core Functionality Setup\n\nIf you don't need any integrations, you can just simply use the core functionality.\n\n##### BMEcatSharp\n\n```csharp\nusing BMEcatSharp;\n...\nvar options = new BMEcatXmlSerializerOptions();\nvar serializerFactory = new BMEcatXmlSerializerFactory(options);\n// from here on see previous usage examples\n```\n\n##### OpenTransSharp\n\n```csharp\nusing OpenTransSharp;\n...\nvar options = new OpenTransXmlSerializerOptions();\nvar serializerFactory = new OpenTransXmlSerializerFactory(options);\n// from here on see previous usage examples\n\n```\n\n### Building this library\n\n#### Prerequisites\n\n* Ensure you have **.NET SDK 8.0+** installed (see https://dot.net)\n\n* Checkout this repository to your computer\n\n* Install [Visual Studio 2022](https://visualstudio.microsoft.com/de/downloads/) if you want to build or develop with it\n\n  **Note**: Visual Studio 2022 *Community Edition* is free for private use or small teams\n\n#### Building with the command line\n\n1. Open command prompt and navigate to your checkout-directory\n2. Run `dotnet build`\n\n#### Building with Visual Studio 2022\n\n1. Open `OpenTransSharp.sln` with Visual Studio 2022\n2. In main menu click `Build` \u003e `Build Solution` (or press \u003ckbd\u003eCTRL+SHIFT+B\u003c/kbd\u003e)\n\n### About BMEcat® and openTRANS®\n\nIn short:\n\n* BMEcat® is about **product catalogs**\n* openTRANS® is about **ordering products** (optionally from BMEcat® catalogs)\n\nFor more information about openTRANS® and BMEcat® see below.\n\n##### Official Information\n\n* BMEcat® information\n  https://www.bme.de/initiativen/bmecat/bmecat-2005/\n* BMEcat® specification + XSDs download\n  https://www.bme.de/initiativen/bmecat/download/\n\n* openTRANS® information\n  https://www.opentrans.de/\n\n  https://www.bme.de/initiativen/bmecat/e-commerce-standard-opentransr/\n\n* openTRANS® specification + XSDs download\n  https://www.digital.iao.fraunhofer.de/de/publikationen/OpenTRANS21/Download-OpenTrans_V2_1.html\n\n##### Wikipedia\n\nhttps://de.wikipedia.org/wiki/OpenTRANS\n\nhttps://de.wikipedia.org/wiki/BMEcat\n\n### Licenses\n\n**Copyright 2021-2023 David Rettenbacher**\n\nThe license of this project is **MPL 2.0**. If not stated otherwise in individual files, this license applies to all files of this project. \n\nFor **MPL 2.0** see the [LICENSE.md](LICENSE.md) file or browse to http://mozilla.org/MPL/2.0/ for the full license text. Additionally you can read up on this license on [Wikipedia](https://en.wikipedia.org/wiki/Mozilla_Public_License), and some Q\u0026A on [StackOverflow](https://opensource.stackexchange.com/questions/8831/pros-and-cons-of-using-mpl-2-0-license).\n\nThis project also uses specifications and XSDs from BMEcat®, openTRANS® and W3C®.\n\nFor **BMEcat®** see [LICENSE-BMEcat.md](LICENSE-BMEcat.md), and for **openTRANS®** see [LICENSE-openTRANS.md](LICENSE-openTRANS.md).\n\n**W3C®** files contain a license header.\n\n#### MPL 2.0 TLDR;\n\n* **You can link this project statically or dynamically** with your program, regardless of your program's license\n  * You can distribute this library with your software under the terms of the GPL licenses\n* Contributions/modifications/forks must **stay MPL 2.0**\n\n### Disclaimer\n\nThis project has no affiliation with the official owners of BMEcat®, openTRANS®, or W3C®.  \nAll trade, company and product names, trademarks or registered trademarks belong to their respective holders.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwarappa%2Fopentranssharp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwarappa%2Fopentranssharp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwarappa%2Fopentranssharp/lists"}