MagicFileEncoding 3.0.0

dotnet add package MagicFileEncoding --version 3.0.0                
NuGet\Install-Package MagicFileEncoding -Version 3.0.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="MagicFileEncoding" Version="3.0.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add MagicFileEncoding --version 3.0.0                
#r "nuget: MagicFileEncoding, 3.0.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install MagicFileEncoding as a Cake Addin
#addin nuget:?package=MagicFileEncoding&version=3.0.0

// Install MagicFileEncoding as a Cake Tool
#tool nuget:?package=MagicFileEncoding&version=3.0.0                

Magic File Encoding

NuGet Downloads Actions Status GitHub

The Magic File Encoding Library is a powerful tool designed to assist you in loading and transforming simple and closed scope character set text files. Whether you're working with txt, xml, json, EDIFACT or similar text formats, this library provides a comprehensive solution to handle various encoding scenarios effortlessly.

Nuget Package

MagicFileEncoding at nuget.org

.Net Version

  • .Net 8: Magic File Encoding 3.0.0 and newer
  • .Net 6: Magic File Encoding 2.0.1 and older

Transformation Considerations

When performing encoding transformations, it is important to be mindful of potential issues that may arise if the target encoding is simpler than the source encoding. Certain characters or language-specific symbols in the source encoding may not be accurately represented or fully preserved in the target encoding.

Thorough testing and validation are recommended to ensure the desired outcome during the transformation process.

Fallback Encoding

The Magic File Encoding Library incorporates a fallback encoding system. By default, it uses ISO-8859-1 (Latin-1) as the fallback encoding. This fallback encoding is specifically designed to cater to the encoding requirements within the German cultural space.

However, it provides the flexibility to modify the fallback encoding through an optional method argument, enabling adaptation to different encoding needs like UTF-8 fallbacks.

Usage

Here are some code examples demonstrating the usage of the code library:

File System

Example 1: Getting the acceptable encoding of a file

string filename = "example.txt";
Encoding fallbackEncoding = Encoding.UTF8;

Encoding acceptableEncoding = FileEncoding.GetAcceptableEncoding(filename, fallbackEncoding);
Console.WriteLine("Acceptable encoding: " + acceptableEncoding.EncodingName);

Example 2: Reading all text from a file using automatic encoding detection

string filename = "example.txt";

string text = FileEncoding.ReadAllText(filename);
Console.WriteLine("Text: " + text);

Example 3: Reading all text from a file and transforming it into a target encoding

string filename = "example.txt";
Encoding targetEncoding = Encoding.UTF8;
Encoding fallbackEncoding = Encoding.GetEncoding("ISO-8859-1");

string text = FileEncoding.ReadAllText(filename, targetEncoding, fallbackEncoding);
Console.WriteLine("Text: " + text);

Example 4: Writing text to a file in a specific encoding

string path = "output.txt";
Encoding targetEncoding = Encoding.UTF8;
string text = "Hello, world!";

FileEncoding.WriteAllText(path, targetEncoding, text);
Console.WriteLine("Text written to file.");

Example 5: Providing writer access to a file in a specific encoding

string path = "output.txt";
Encoding targetEncoding = Encoding.UTF8;

FileEncoding.Write(path, targetEncoding, writer =>
{
    writer.WriteLine("Line 1");
    writer.WriteLine("Line 2");
    writer.WriteLine("Line 3");
});

Console.WriteLine("Text written to file.");

Byte Array

Example 6: Getting the acceptable encoding of a byte array

byte[] bytes = File.ReadAllBytes("example.txt");
Encoding fallbackEncoding = Encoding.UTF8;

Encoding acceptableEncoding = FileEncoding.GetAcceptableEncoding(bytes, fallbackEncoding);
Console.WriteLine("Acceptable encoding: " + acceptableEncoding.EncodingName);

Example 7: Reading all text from a byte array using automatic encoding detection

byte[] bytes = File.ReadAllBytes("example.txt");

string text = FileEncoding.ReadAllText(bytes);
Console.WriteLine("Text: " + text);

Example 8: Reading all text from a byte array and transforming it into a target encoding

byte[] bytes = File.ReadAllBytes("example.txt");
Encoding targetEncoding = Encoding.UTF8;
Encoding fallbackEncoding = Encoding.GetEncoding("ISO-8859-1");

string text = FileEncoding.ReadAllText(bytes, targetEncoding, fallbackEncoding);
Console.WriteLine("Text: " + text);

Versioning & Breaking Changes

Major.Minor.Patch-Suffix

  • Major: Breaking changes
  • Minor: New features, but backwards compatible
  • Patch: Backwards compatible bug fixes only
  • -Suffix (optional): a hyphen followed by a string denoting a pre-release version

See: https://docs.microsoft.com/en-us/nuget/concepts/package-versioning

Credits

This work is heavily based on the following stack overflow and web articles:<br /> determine-a-strings-encoding-in-c-sharp <br /> check-for-invalid-utf8 <br /> how-to-detect-utf-8-in-plain-c <br /> strip-byte-order-mark-from-string-in-c-sharp <br /> what-is-the-most-common-encoding-of-each-language <br /> utf-bom4

Contributions and Support

Contributions to the Magic File Encoding Library are welcome! If you encounter any issues, have suggestions for improvements, or would like to contribute to its development, please visit our GitHub repository.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net8.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
3.0.0 3,809 2/5/2024
2.0.1 4,356 6/10/2023
2.0.0 427 5/25/2023
1.1.1 1,498 2/13/2021
1.1.0 331 2/13/2021
1.0.0 479 9/28/2020
1.0.0-preview.3 252 9/28/2020
1.0.0-preview.2 286 9/27/2020
1.0.0-preview 346 9/27/2020