PlistAPI 1.2.0

dotnet add package PlistAPI --version 1.2.0
NuGet\Install-Package PlistAPI -Version 1.2.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="PlistAPI" Version="1.2.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add PlistAPI --version 1.2.0
#r "nuget: PlistAPI, 1.2.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 PlistAPI as a Cake Addin
#addin nuget:?package=PlistAPI&version=1.2.0

// Install PlistAPI as a Cake Tool
#tool nuget:?package=PlistAPI&version=1.2.0

PlistAPI

NuGet Package Link: https://www.nuget.org/packages/PlistAPI

PlistAPI - is a library that allows you deserialize and serialize the data as specific objects, and probably the best Plist library you will ever find in the github for C#, so let me show you an example of it's usage:

.plist (basically a little changed .xml) format

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
     <dict>
          <key>SomeKey</key>
          <string>SomeValue</string>
     </dict>
</plist>

Deserialization

You may provide Id in the attribute argument, or even a complete path to the key (allowed to get outside parent Plist)

using var fileStream = File.Open("filePath");
Plist.Deserialize<SomeClass>(fileStream);

[PlistObject]
class SomeClass
{
    [PlistProperty("SomeKey")]
    // [PlistProperty("SomeDict", "SomeAnotherDict", "SomeValue")] // complete path
    public string SomeKey { get; set; }
}

Also you are able not to provide PlistProperty.Id ( [PlistProperty(string: Id)] ), but the property name must match the Key (Be careful, its case-sensitive, by providing id either).

Serialization

// deserialize
using var fileStream = File.Open("filePath");
var deserialized = Plist.Deserialize<SomeClass>(fileStream);

// serialize
Plist.Serialize<SomeClass>(deserialized);

// OR
// Plist.Serialize(deserialized);

[PlistObject]
class SomeClass
{
    [PlistProperty("SomeKey")]
    public string SomeKey { get; set; }
}

By NOT providing the type in the generic of Serialize(), the serialization will be UNsegnifically slower, but anyways it will! (because of reflection manipulations to obtain the type from the object instance)

Invalid Data Handling

You can use PlistInvalidDataHandlingType to handle invalid data, example:

var settings = new PlistSettings() { InvalidDataHandlingType = PlistInvalidDataHandlingType.ReturnNull };

// then use this settings

/*
    * Plist.Deserialize<T>(data, settings);
    * Plist.Serialize<T>(data, settings);
    * new Plist(settings).Load(data);
    * await new Plist(settings).LoadAsync(data);

    etc...
*/

Other features

  • This library can deserialize and full-named (<key></key>, <string></string> ...), and short-named (<k></k>, <s></s> ...) key-values, and both at the same time (check details in the PlistAPI.Tests project), but serialize obviously strong-type only (full-named or short-named)

  • You can choose whether the serialized output will be indent-formatted or not

  • Also the library uses faster value parsers (faster float parser, and faster int parser)

Converters

Library supports converters that can manipulate input / output values to get better experience with serializers.

You might attach Internal Converters (only 2 yet), or create your one!

You can use converters' classes by attaching [PlistConverter] attribute to the certain object member, and also you can specify whether the converter converts input-data-only, output-data-only or everything at once!

Internal Converter Usages

There are 2 internal converters, one of them is IntToBoolConverter that convertes integers greater than 0 to true, otherwise false

string plistData = """
    <plist version="1.0">
        <dict>
                <key>IntProperty</key>
                <integer>1</integer>
        </dict>
    </plist>
    """;

Plist.Deserialize<SomeClass(plistData);

[PlistObject]
class SomeClass
{
    [PlistProperty("IntProperty")]
    [PlistConverter(typeof(StringToBoolConverter))]
    // [PlistConverter(typeof(StringToBoolConverter), ConverterUsage = PlistAPI.Enums.PlistConverterUsage.ConvertInputType)] // with specifications
    public bool ConvertedInt { get; set; }
}
Creating your own converter

To create your own converter you have to create a class that inherites IPlistConverter<TInput, TOutput>, here is an example:

// converter class
class StringToFileConverter : IPlistConverter<string, FileInfo>
{
    public FileInfo ReadValue(string value)
    {
        if (File.Exists(value))
            return new FileInfo(value);

        return null;
    }

    public string WriteValue(FileInfo value)
    {
        return value.FullName;
    }
}

// usage
class SomeClass
{
    [PlistProperty("SomeFilePath")]
    [PlistConverter(typeof(StringToFileConverter))] // declaring the converter usage
    public FileInfo File { get; set; }
}

this converter returns FileInfo instance when deserializing if the representing string as a file path exists, and returns FileInfo.FullName when serializing

Other important feature about converters: Custom converter property

Custom converter property is a public member (field or property) inside the converter class, that you can use too, here is an example how to create custom property, how to use it, and how to declare the specific member that uses the converter should encount that Custom converter property

i will use the same converter class as above

class StringToFileConverter : IPlistConverter<string, FileInfo>
{
    [PlistConverterProperty(defaultValue: false)] // "false" is a default value
    public bool CheckIfFileIsReadOnly { get; set; }

    public FileInfo ReadValue(string value)
    {
        if (!File.Exists(value))
            return null;

        var file = new FileInfo(value);

        if (CheckIfFileIsReadOnly && file.Attributes.HasFlag(FileAttributes.ReadOnly))
            return file;

        return null;
    }

    public string WriteValue(FileInfo value)
    {
        return value.FullName;
    }
}

// usage
class SomeClass
{
    [PlistProperty("SomeFilePath")]
    [PlistConverter(typeof(StringToFileConverter))] // declaring the converter usage
    [PlistConverterMember(nameof(StringToFileConverter.CheckIfFileIsReadOnly), true)] // declaring that we should use this custom property and use the value "true" for it
    public FileInfo File { get; set; }

    // Also you can use multiple members
    // [PlistConverterMember(nameof(ClassName.SomeMember1), true)]
    // [PlistConverterMember(nameof(ClassName.SomeMember2), "hello")]
    // [PlistConverterMember(nameof(ClassName.SomeMember3), 69)]
    // public object? SomeProperty { get; set; }
}
Note

Converters usually cache themselves in the code internally, but if they have Custom converter property they won't be cached, because every serializable property that uses this custom property may and probably will have distinct values, so caching will make the converters return invalid values

Library is being completely maintenanced by me, so dont be shy and pull some issues 😃

Tests

They are not updated (LET ME BREATH PLEASE)

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  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. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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
1.2.0 220 11/12/2023
1.1.0 102 11/9/2023
1.0.0 98 11/9/2023