{"id":385557,"date":"2024-06-29T06:10:50","date_gmt":"2024-06-29T06:10:50","guid":{"rendered":"http:\/\/savepearlharbor.com\/?p=385557"},"modified":"-0001-11-30T00:00:00","modified_gmt":"-0001-11-29T21:00:00","slug":"","status":"publish","type":"post","link":"https:\/\/savepearlharbor.com\/?p=385557","title":{"rendered":"Creating a NuGet package for a library with platform-specific API<\/span>"},"content":{"rendered":"
<\/div>\n
\n
\n
\n
\n

It’s the English version of <\/em>this<\/em><\/a> article. Shout-out to <\/em>Viktor Fedotov<\/em><\/a> for helping with translation.<\/em><\/p>\n

<\/figcaption><\/figure>\n

When creating a .NET library with a partially platform-specific API, we should think about how to pack it into a NuGet package so that the installed library will work in various scenarios (.NET Framework, .NET Core, self-contained application and so on). Unfortunately, it is difficult to find a step-by-step instruction on the web that describes how to perform this task. This article is intended to be such an instruction.<\/p>\n

I\u2019m developing a .NET library DryWetMIDI<\/u><\/a> which is used to work with MIDI files and MIDI devices. Most of the library API is cross-platform (within the operating systems supported by .NET of course), however the exact handling of MIDI devices is different for every operating system. Currently the corresponding API works on Windows only, but there is a strong desire to support other systems too. I\u2019m not rushing to support all the existing platforms from the start, so I\u2019m going to make the API to work on macOS first, since it\u2019s no less popular than Windows, but probably is the most popular one among music professionals.<\/p>\n

Of course, it doesn’t make sense to implement the whole API right away and It\u2019s much easier to make sure that everything works on a small example. This is exactly what I did, and I am suggesting you to go through the whole path to the final solution along with me. The brief list of steps is at the end of the article.<\/p>\n

First attempts<\/h2>\n

As it\u2019s usually done in the .NET world the library is distributed through the NuGet package manager. That’s why I immediately knew that the package must contain native binaries to provide API for specific operating systems.<\/p>\n

In C# we can write a declaration of an external function as follows:<\/p>\n

[DllImport(\"test\")] public static extern int Foo();<\/code><\/pre>\n
As you can see we don\u2019t need to specify the extension of a native library since .NET will use a suitable one based on the current operating system. In other words, if test.dll<\/em> and test.dylib<\/em> files are located alongside our application, the function Foo<\/code> will be called from test.dll on Windows, and from test.dylib on macOS. We can scale the solution to *nix systems by providing a test.so<\/em> file.<\/p>\n
To move forward let\u2019s create a project for our test library. DryWetMIDI specifies netstandard2.0<\/em> and net45<\/em> TFM<\/u><\/a>s within its .csproj file, so in order to be as close as possible to the real conditions I specified those target platforms for the test project as well. The project will be called DualLibClassLibrary<\/em> and will contain a single file Class.cs<\/em>:<\/p>\n
using System.Runtime.InteropServices;  namespace DualLibClassLibrary {     public static class Class     {         [DllImport(\"test\")]         public static extern int Foo();          public static int Bar()         {             return Foo() * 1000;         }     } }<\/code><\/pre>\n
Of course we also need native binaries: test.dll and test.dylib. I compiled them from a simple C code (I\u2019m going to use the same approach for the real library):<\/p>\n
for Windows<\/em><\/p>\n
int Foo() { return 123; }<\/code><\/pre>\n
for macOS<\/em><\/p>\n
int Foo() { return 456; }<\/code><\/pre>\n
If you\u2019re interested, test.dll and test.dylib files were created within an Azure DevOps test pipeline (in fact two pipelines: one for Windows and one for macOS). After all of that, I\u2019ll need to do all the required actions within CI builds, so right away I decided to see how it should be done for the DryWetMIDI. The pipeline is pretty simple and it consist of 3 steps:<\/p>\n
1. generate a file containing C code (PowerShell task)<\/em><\/p>\n
New-Item \"test.c\" -ItemType File -Value \"int Foo() { return 123; }\"<\/code><\/pre>\n
(return 456;<\/code> for macOS);<\/p>\n
2. build a library (Command Line task)<\/em><\/p>\n
gcc -v -c test.c gcc -v -shared -o test.dll test.o<\/code><\/pre>\n
(test.dylib for macOS);<\/p>\n
3. publish an artifact with the library (Publish Pipeline Artifact task)<\/em><\/p>\n
Here we have test.dll and test.dylib files implementing the same function Foo<\/code>, which returns 123<\/code> for Windows and 456<\/code> for macOS, this way we can always easily check if a result of a function call is correct. We\u2019ll place the files near DualLibClassLibrary.csproj<\/em>.<\/p>\n
Now we need to figure out how to add the files to a NuGet package so they are copied to the output directory after each application build in order to guarantee that our test library will work as it should. Since the library is cross-platform and uses the new .csproj format (SDK style), it would be great to declare packing instructions there. After doing some research I came up with this .csproj:<\/p>\n
<Project Sdk=\"Microsoft.NET.Sdk\">    <PropertyGroup>     <TargetFrameworks>netstandard2.0;net45<\/TargetFrameworks>     <LangVersion>6<\/LangVersion>     <Configurations>Debug;Release<\/Configurations>   <\/PropertyGroup>    <PropertyGroup>     <PackageId>DualLibClassLibrary<\/PackageId>     <Version>1.0.0<\/Version>     <Authors>melanchall<\/Authors>     <Owners>melanchall<\/Owners>     <Description>Dual-lib class library<\/Description>     <Copyright>Copyright \u200b Melanchall 2021<\/Copyright>     <AutoGenerateBindingRedirects>true<\/AutoGenerateBindingRedirects>   <\/PropertyGroup>    <ItemGroup>     <Content Include=\"test.dll\">       <Pack>true<\/Pack>       <CopyToOutputDirectory>Always<\/CopyToOutputDirectory>     <\/Content>     <Content Include=\"test.dylib\">       <Pack>true<\/Pack>       <CopyToOutputDirectory>Always<\/CopyToOutputDirectory>     <\/Content>   <\/ItemGroup>  <\/Project><\/code><\/pre>\n
Building the package:<\/p>\n
dotnet pack .\\DualLibClassLibrary.sln -c Release<\/code><\/p>\n
To check the package installation let\u2019s create a folder somewhere, add it as a packages feed in Visual Studio and put the generated file DualLibClassLibrary.1.0.0.nupkg<\/em> to this folder. We are going to use classic .NET Framework on Windows to check the package installation. Now let\u2019s create a console application and install our library into it. After doing so we can see the two files have appeared in the project:<\/p>\n
\"test.dll
test.dll and test.dylib are fetched from the package<\/figcaption><\/figure>\n
So good so far, let\u2019s write a simple code within the Program.cs<\/em>:<\/p>\n
static void Main(string[] args) {     var result = DualLibClassLibrary.Class.Bar();     Console.WriteLine($\"Result = {result}. Press any key to exit...\");     Console.ReadKey(); }<\/code><\/pre>\n
After running the application we see the unsatisfying picture:<\/p>\n
\"The
The program was not able to find the test.dll<\/figcaption><\/figure>\n
Well… let\u2019s take a look into bin\/Debug<\/em> folder:<\/p>\n
\"test.dll
test.dll and test.dylib files are missing in the application\u2019s output directory<\/figcaption><\/figure>\n
Surprisingly enough the files are missing. It is indeed strange since we\u2019ve specified the <CopyToOutputDirectory><\/code> item for them and we do actually see the files within the project structure. But everything becomes clear after we take a look into the .csproj file:<\/p>\n
\"Chaos
Chaos in the .csproj<\/figcaption><\/figure>\n
We have two weird things here. Firstly the <CopyToOutputDirectory><\/code> item is missing. And secondly, test.dylib has been added as <None><\/code> item but test.dll has been added as <Content><\/code> item. If we take a look into the .nupkg file with NuGet Package Explorer<\/u><\/a>, we\u2019ll see the following manifest:<\/p>\n
<?xml version=\"1.0\" encoding=\"utf-8\"?> <package xmlns=\"http:\/\/schemas.microsoft.com\/packaging\/2012\/06\/nuspec.xsd\">   <metadata>     <id>DualLibClassLibrary<\/id>     <version>1.0.0<\/version>     <authors>melanchall<\/authors>     <owners><\/owners>     <requireLicenseAcceptance>false<\/requireLicenseAcceptance>     <description>Dual-lib class library<\/description>     <copyright>Copyright \u200b Melanchall 2021<\/copyright>     <dependencies>       <group targetFramework=\".NETFramework4.5\" \/>       <group targetFramework=\".NETStandard2.0\" \/>     <\/dependencies>     <contentFiles>       <files include=\"any\/net45\/test.dll\" buildAction=\"Content\" \/>       <files include=\"any\/netstandard2.0\/test.dll\" buildAction=\"Content\" \/>       <files include=\"any\/net45\/test.dylib\" buildAction=\"Content\" \/>       <files include=\"any\/netstandard2.0\/test.dylib\" buildAction=\"Content\" \/>     <\/contentFiles>   <\/metadata> <\/package><\/code><\/pre>\n
As you can see, sadly, the files were added without the copyToOutput<\/code> attribute (you can read about the attribute here in the table: Using the contentFiles element for content files<\/u><\/a>).<\/p>\n
Copying files to the application\u2019s output directory<\/h2>\n
After looking through the web (including issues on GitHub, answers on StackOverflow and official Microsoft documentation), I modified the files packing elements in the library\u2019s .csproj:<\/p>\n
<Content Include=\"test.dll\">   <Pack>true<\/Pack>   <CopyToOutputDirectory>Always<\/CopyToOutputDirectory>   <PackageCopyToOutput>true<\/PackageCopyToOutput>   <PackagePath>contentFiles;content<\/PackagePath> <\/Content> <Content Include=\"test.dylib\">   <Pack>true<\/Pack>   <CopyToOutputDirectory>Always<\/CopyToOutputDirectory>   <PackageCopyToOutput>true<\/PackageCopyToOutput>   <PackagePath>contentFiles;content<\/PackagePath> <\/Content><\/code><\/pre>\n
The <PackageCopyToOutput><\/code> item is exactly what we need to make the copyToOutput<\/code> attribute to appear in the package manifest. Also we explicitly specified destination folders for the files to avoid directories like any<\/em>. If you\u2019re interested in this topic you can read more here: Including content in a package<\/u><\/a>.<\/p>\n
Let\u2019s build the project one more time and check the manifest:<\/p>\n
<?xml version=\"1.0\" encoding=\"utf-8\"?> <package xmlns=\"http:\/\/schemas.microsoft.com\/packaging\/2012\/06\/nuspec.xsd\">   <metadata>     <id>DualLibClassLibrary<\/id>     <version>1.0.1<\/version>     <authors>melanchall<\/authors>     <owners><\/owners>     <requireLicenseAcceptance>false<\/requireLicenseAcceptance>     <description>Dual-lib class library<\/description>     <copyright>Copyright \u200b Melanchall 2021<\/copyright>     <dependencies>       <group targetFramework=\".NETFramework4.5\" \/>       <group targetFramework=\".NETStandard2.0\" \/>     <\/dependencies>     <contentFiles>       <files include=\"test.dll\" buildAction=\"Content\" copyToOutput=\"true\" \/>       <files include=\"test.dylib\" buildAction=\"Content\" copyToOutput=\"true\" \/>     <\/contentFiles>   <\/metadata> <\/package><\/code><\/pre>\n
\"copyToOutput
copyToOutput didn\u2019t help<\/figcaption><\/figure>\n
Another failure. If we are going to try the same thing in .NET5, we\u2019ll get:<\/p>\n
\"Still
Still no files in the application\u2019s output directory<\/figcaption><\/figure>\n
Basically there\u2019s no difference except a slightly changed message of the exception. After submitting a GitHub issue I received the answer:<\/p>\n
\n
Please see our <\/em>docs on<\/u><\/em><\/a> <\/em>contentFiles<\/code>. It supports adding different content depending on project’s target framework and language, and therefore needs files in a specific structure which your package is not currently using.<\/em><\/p>\n<\/blockquote>\n
It turns out that I overlooked a few details in the documentation: if you add files into directories named like contentFiles\/any\/netstandard2.0<\/em> instead of simply contentFiles<\/em>, a .props file is created automatically and it contains proper elements for copying files to the application\u2019s output directory. However before I received any answer I did my own research and came up with a different approach. And in hindsight it was the right decision and the reason is that you will not have all of the files installed properly from a package into your .NET Framework application when using the contentFiles<\/code> folder. I strongly believe it is an important scenario and thus it must be supported.<\/p>\n
There is an article on the Microsoft documentation with a promising title: Creating native packages<\/u><\/a>. The article itself is not very informative, but we can learn something useful from it \u2013 the fact that we can create a .targets file with <CopyToOutputDirectory><\/code> elements specified for our files. The .targets file must be included in a package along with native libraries. Well, let\u2019s create DualLibClassLibrary.targets<\/em> file:<\/p>\n
<?xml version=\"1.0\" encoding=\"utf-8\"?> <Project ToolsVersion=\"4.0\" xmlns=\"http:\/\/schemas.microsoft.com\/developer\/msbuild\/2003\">   <ItemGroup>     <None Include=\"$(MSBuildThisFileDirectory)test.dll\">       <Link>test.dll<\/Link>       <CopyToOutputDirectory>PreserveNewest<\/CopyToOutputDirectory>     <\/None>     <None Include=\"$(MSBuildThisFileDirectory)test.dylib\">       <Link>test.dylib<\/Link>       <CopyToOutputDirectory>PreserveNewest<\/CopyToOutputDirectory>     <\/None>   <\/ItemGroup> <\/Project><\/code><\/pre>\n
And in the DualLibClassLibrary.csproj<\/em> file we write:<\/p>\n
<ItemGroup>   <None Include=\"test.dll\">     <CopyToOutputDirectory>PreserveNewest<\/CopyToOutputDirectory>     <PackagePath>build\\<\/PackagePath>     <Pack>true<\/Pack>   <\/None>   <None Include=\"test.dylib\">     <CopyToOutputDirectory>PreserveNewest<\/CopyToOutputDirectory>     <PackagePath>build\\<\/PackagePath>     <Pack>true<\/Pack>   <\/None>   <None Include=\"DualLibClassLibrary.targets\">     <PackagePath>build\\<\/PackagePath>     <Pack>true<\/Pack>   <\/None> <\/ItemGroup><\/code><\/pre>\n
By building a package for the version 1.0.2, installing it to our .NET Framework console application and running it we have:<\/p>\n
\"We
We have a different error now<\/figcaption><\/figure>\n
This exception is usually thrown when the application’s process is 64-bit while the native library is 32-bit or the other way around. But in this case I built the libraries on 64-bit systems and the application was running on a 64-bit operating system too. Well, it seems our journey continues.<\/p>\n
Support for 32-bit and 64-bit processes<\/h2>\n
If we open the properties of our console application project in Visual Studio inside the Build tab, we can see this checkbox:<\/p>\n
\"A
A process will be 32-bit<\/figcaption><\/figure>\n
It turns out, this option is checked by default for a .NET Framework project and the application\u2019s process will be 32-bit even on a 64-bit operating system. It\u2019s funny that for .NET Core\/.NET 5 projects this option is turned off by default:<\/p>\n
\"Checkbox
Checkbox is unchecked for .NET Core<\/figcaption><\/figure>\n
Of course, we can turn this option off and the application will finally print the correct result:<\/p>\n
Result = 123000. Press any key to exit...<\/code><\/p>\n
But that\u2019s obviously not the solution for the following reasons:<\/p>\n
    \n
  1. \n
    we won\u2019t be able to use the library in 32-bit processes;<\/p>\n<\/li>\n
  2. \n
    it requires additional actions from a user (unchecking a checkbox);<\/p>\n<\/li>\n
  3. \n
    the classic default scenario (create new .NET Framework application without any additional actions) won\u2019t be supported.<\/p>\n<\/li>\n<\/ol>\n
    Certainly this is not an option and the problem must be solved. In fact the solution is obvious: let\u2019s just create native binaries for each operating system in two versions \u2013 32-bit and 64-bit. It means the package will be larger in size since it will contain 4 platform-specific libraries instead of 2. I don\u2019t see anything wrong with this approach because the files are small, and thus I am going to proceed with it (and I can\u2019t see how it can be done in another way).<\/p>\n
    Let me briefly tell you about how I build 32-bit libraries. As I\u2019ve mentioned above I create binaries within Azure DevOps pipelines using gcc. gcc is called with -m32<\/code> flag which in theory tells gcc to build a 32-bit library. This is fine on build agents with macOS images, but on Windows I got quite a few nasty log messages:<\/p>\n
    C:\/ProgramData\/Chocolatey\/lib\/mingw\/tools\/install\/mingw64\/bin\/..\/lib\/gcc\/x86_64-w64-mingw32\/8.1.0\/..\/..\/..\/..\/x86_64-w64-mingw32\/bin\/ld.exe: skipping incompatible C:\/ProgramData\/Chocolatey\/lib\/mingw\/tools\/install\/mingw64\/bin\/..\/lib\/gcc\/x86_64-w64-mingw32\/8.1.0\/..\/..\/..\/..\/x86_64-w64-mingw32\/lib\\libuser32.a when searching for -luser32<\/code><\/p>\n
    ...<\/code><\/p>\n
    C:\/ProgramData\/Chocolatey\/lib\/mingw\/tools\/install\/mingw64\/bin\/..\/lib\/gcc\/x86_64-w64-mingw32\/8.1.0\/..\/..\/..\/..\/x86_64-w64-mingw32\/lib\/libmsvcrt.a when searching for -lmsvcrt C:\/ProgramData\/Chocolatey\/lib\/mingw\/tools\/install\/mingw64\/bin\/..\/lib\/gcc\/x86_64-w64-mingw32\/8.1.0\/..\/..\/..\/..\/x86_64-w64-mingw32\/bin\/ld.exe: cannot find -lmsvcrt collect2.exe: error: ld returned 1 exit status<\/code><\/p>\n
    I asked a question about these errors on StackOverflow<\/u><\/a> and on Microsoft Developer Community<\/u><\/a> site, and got answers stating that the 32-bit version of the MinGW is not preinstalled on Microsoft-hosted agents, which causes the error. After trying many options, I chose the brechtsanders\/winlibs_mingw<\/u><\/a> project creating a simple PowerShell script:<\/p>\n
    Write-Host \"Downloading winlibs...\" Invoke-WebRequest -Uri \"https:\/\/github.com\/brechtsanders\/winlibs_mingw\/releases\/download\/11.1.0-12.0.0-9.0.0-r1\/winlibs-i686-posix-dwarf-gcc-11.1.0-mingw-w64-9.0.0-r1.zip\" -OutFile \"winlibs.zip\" Write-Host \"Downloaded.\"  Write-Host \"Extracting winlibs...\" Expand-Archive -LiteralPath 'winlibs.zip' -DestinationPath \"winlibs\" Write-Host \"Extracted.\"  Write-Host \"Building DLL...\" $gccPath = Get-ChildItem -Path \"winlibs\" -File -Filter \"i686-w64-mingw32-gcc.exe\" -Recurse  & $gccPath.FullName -c test.c -m32 & $gccPath.FullName -shared -o test.dll test.o -m32 Write-Host \"Built.\"<\/code><\/pre>\n
    By using the i686-w64-mingw32-gcc.exe<\/em> compiler from the archive, I was finally able to build the 32-bit test.dll. Hooray!<\/p>\n
    Now we need to figure out how to tell our library which API to use: 32-bit or 64-bit one. I am quite sure there are multiple different approaches, but I settled on the following one:<\/p>\n
      \n
    1. \n
      build test32.dll, test64.dll, test32.dylib and test64.dylib native binaries;<\/p>\n<\/li>\n
    2. \n
      create abstract class Api<\/code> containing abstract methods that correspond to our managed API for internal usage;<\/p>\n<\/li>\n
    3. \n
      create two subclasses of Api<\/code> \u2013 Api32<\/code> and Api64<\/code> \u2013 which will implement abstract API from the base class calling unmanaged API from test32 and test64 correspondingly;<\/p>\n<\/li>\n
    4. \n
      create class ApiProvider<\/code> with the Api<\/code> property which will return an implementation based on a current process bitness.<\/p>\n<\/li>\n<\/ol>\n
      UPD:<\/strong> Starting with .NET Core 3.0 you can use NativeLibrary<\/a> class and its SetDllImportResolver<\/a> method. The method allows to simplify the process below and get rid of duplicated signatures of external functions (you will be able to choose required native binary name in runtime by the current process bitness).<\/p>\n
      Here the code of the classes:<\/p>\n
      Api.cs<\/strong><\/p>\n
      namespace DualLibClassLibrary {     internal abstract class Api     {         public abstract int Method();     } }<\/code><\/pre>\n
      Api32.cs<\/strong><\/p>\n
      using System.Runtime.InteropServices;  namespace DualLibClassLibrary {     internal sealed class Api32 : Api     {         [DllImport(\"test32\")]         public static extern int Foo();          public override int Method()         {             return Foo();         }     } }<\/code><\/pre>\n
      Api64.cs<\/strong><\/p>\n
      using System.Runtime.InteropServices;  namespace DualLibClassLibrary {     internal sealed class Api64 : Api     {         [DllImport(\"test64\")]         public static extern int Foo();          public override int Method()         {             return Foo();         }     } }<\/code><\/pre>\n
      ApiProvider.cs<\/strong><\/p>\n
      using System;  namespace DualLibClassLibrary {     internal static class ApiProvider     {         private static readonly bool Is64Bit = IntPtr.Size == 8;         private static Api _api;          public static Api Api         {             get             {                 if (_api == null)                     _api = Is64Bit ? (Api)new Api64() : new Api32();                  return _api;             }         }     } }<\/code><\/pre>\n
      And then the code of Class<\/code> class will be:<\/p>\n
      namespace DualLibClassLibrary {     public static class Class     {         public static int Bar()         {             return ApiProvider.Api.Method() * 1000;         }     } } <\/code><\/pre>\n
      After a new version of the package is created (of course with new files added to the DualLibClassLibrary.targets<\/em> and DualLibClassLibrary.csproj<\/em> before that) we\u2019ll see that the method of our library works correctly no matter whether application\u2019s process is 32-bit or 64-bit.<\/p>\n
      Conclusion<\/h2>\n
      Here you have a complete chronology of my trials on the creation of a NuGet package with platform-specific API, and it would be useful to briefly list the main points (I promised the instructions after all):<\/p>\n
        \n
      1. \n
        create native binaries in 32-bit and 64-bit versions;<\/p>\n<\/li>\n
      2. \n
        place them near a library project (you can place them in any folder and specify the folder\u2019s path in .csproj and .targets files);<\/p>\n<\/li>\n
      3. \n
        add .targets file with the <CopyToOutputDirectory><\/code> element (with desired value) added for each native file;<\/p>\n<\/li>\n
      4. \n
        add elements for packing .targets file (should be placed in the build folder of a package) and all native binaries in the .csproj file;<\/p>\n<\/li>\n
      5. \n
        implement a way to select a native file based on the fact whether a process is 32-bit or 64-bit.<\/p>\n<\/li>\n<\/ol>\n
        Simple as that! The solution of our test library is available here: DualLibClassLibrary.zip<\/u><\/a>. The library was tested in the following scenarios on Windows and macOS:<\/p>\n
          \n
        1. \n
          .NET Framework application;<\/p>\n<\/li>\n
        2. \n
          .NET Core \/ .NET 5 application;<\/p>\n<\/li>\n
        3. \n
          Self-contained application.<\/p>\n<\/li>\n<\/ol>\n
          As for support of 32-bit and 64-bit processes \u2013 I\u2019ve checked only on Windows, I’m not sure how to check it on macOS. UPD:<\/strong> I have only 64-bit dylib file in the package.<\/p>\n
          It is worth noting that .NET currently supports only desktop operating systems<\/u><\/a>. However, support for mobile platforms is planned in .NET 6<\/u><\/a>. I’m not sure if the approach described above will work in that case too. I suppose a dylib file will work on iOS (or not?), but we definitely need to take care of Android support separately. Maybe someone has already done it and can share instructions in the comments? UPD:<\/strong> As .NET 6 and then .NET MAUI have been released you can apply the process in the article to mobile platforms too. Also for iOS you need to provide an a<\/strong> file instead of dylib one, please see details in this discussion<\/a>.<\/p>\n<\/p>\n<\/div>\n<\/div>\n<\/div>\n
          <\/div>\n

           \u0441\u0441\u044b\u043b\u043a\u0430 \u043d\u0430 \u043e\u0440\u0438\u0433\u0438\u043d\u0430\u043b \u0441\u0442\u0430\u0442\u044c\u0438            https:\/\/habr.com\/ru\/articles\/565908\/<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
          <\/div>\n
          \n
          \n
          \n
          \n
          It’s the English version of <\/em>this<\/em><\/a> article. Shout-out to <\/em>Viktor Fedotov<\/em><\/a> for helping with translation.<\/em><\/p>\n
          <\/figcaption><\/figure>\n
          When creating a .NET library with a partially platform-specific API, we should think about how to pack it into a NuGet package so that the installed library will work in various scenarios (.NET Framework, .NET Core, self-contained application and so on). Unfortunately, it is difficult to find a step-by-step instruction on the web that describes how to perform this task. This article is intended to be such an instruction.<\/p>\n
          I\u2019m developing a .NET library DryWetMIDI<\/u><\/a> which is used to work with MIDI files and MIDI devices. Most of the library API is cross-platform (within the operating systems supported by .NET of course), however the exact handling of MIDI devices is different for every operating system. Currently the corresponding API works on Windows only, but there is a strong desire to support other systems too. I\u2019m not rushing to support all the existing platforms from the start, so I\u2019m going to make the API to work on macOS first, since it\u2019s no less popular than Windows, but probably is the most popular one among music professionals.<\/p>\n
          Of course, it doesn’t make sense to implement the whole API right away and It\u2019s much easier to make sure that everything works on a small example. This is exactly what I did, and I am suggesting you to go through the whole path to the final solution along with me. The brief list of steps is at the end of the article.<\/p>\n
          First attempts<\/h2>\n
          As it\u2019s usually done in the .NET world the library is distributed through the NuGet package manager. That’s why I immediately knew that the package must contain native binaries to provide API for specific operating systems.<\/p>\n
          In C# we can write a declaration of an external function as follows:<\/p>\n
          [DllImport(\"test\")] public static extern int Foo();<\/code><\/pre>\n
          As you can see we don\u2019t need to specify the extension of a native library since .NET will use a suitable one based on the current operating system. In other words, if test.dll<\/em> and test.dylib<\/em> files are located alongside our application, the function Foo<\/code> will be called from test.dll on Windows, and from test.dylib on macOS. We can scale the solution to *nix systems by providing a test.so<\/em> file.<\/p>\n
          To move forward let\u2019s create a project for our test library. DryWetMIDI specifies netstandard2.0<\/em> and net45<\/em> TFM<\/u><\/a>s within its .csproj file, so in order to be as close as possible to the real conditions I specified those target platforms for the test project as well. The project will be called DualLibClassLibrary<\/em> and will contain a single file Class.cs<\/em>:<\/p>\n
          using System.Runtime.InteropServices;  namespace DualLibClassLibrary {     public static class Class     {         [DllImport(\"test\")]         public static extern int Foo();          public static int Bar()         {             return Foo() * 1000;         }     } }<\/code><\/pre>\n
          Of course we also need native binaries: test.dll and test.dylib. I compiled them from a simple C code (I\u2019m going to use the same approach for the real library):<\/p>\n
          for Windows<\/em><\/p>\n
          int Foo() { return 123; }<\/code><\/pre>\n
          for macOS<\/em><\/p>\n
          int Foo() { return 456; }<\/code><\/pre>\n
          If you\u2019re interested, test.dll and test.dylib files were created within an Azure DevOps test pipeline (in fact two pipelines: one for Windows and one for macOS). After all of that, I\u2019ll need to do all the required actions within CI builds, so right away I decided to see how it should be done for the DryWetMIDI. The pipeline is pretty simple and it consist of 3 steps:<\/p>\n
          1. generate a file containing C code (PowerShell task)<\/em><\/p>\n
          New-Item \"test.c\" -ItemType File -Value \"int Foo() { return 123; }\"<\/code><\/pre>\n
          (return 456;<\/code> for macOS);<\/p>\n
          2. build a library (Command Line task)<\/em><\/p>\n
          gcc -v -c test.c gcc -v -shared -o test.dll test.o<\/code><\/pre>\n
          (test.dylib for macOS);<\/p>\n
          3. publish an artifact with the library (Publish Pipeline Artifact task)<\/em><\/p>\n
          Here we have test.dll and test.dylib files implementing the same function Foo<\/code>, which returns 123<\/code> for Windows and 456<\/code> for macOS, this way we can always easily check if a result of a function call is correct. We\u2019ll place the files near DualLibClassLibrary.csproj<\/em>.<\/p>\n
          Now we need to figure out how to add the files to a NuGet package so they are copied to the output directory after each application build in order to guarantee that our test library will work as it should. Since the library is cross-platform and uses the new .csproj format (SDK style), it would be great to declare packing instructions there. After doing some research I came up with this .csproj:<\/p>\n
          <Project Sdk=\"Microsoft.NET.Sdk\">    <PropertyGroup>     <TargetFrameworks>netstandard2.0;net45<\/TargetFrameworks>     <LangVersion>6<\/LangVersion>     <Configurations>Debug;Release<\/Configurations>   <\/PropertyGroup>    <PropertyGroup>     <PackageId>DualLibClassLibrary<\/PackageId>     <Version>1.0.0<\/Version>     <Authors>melanchall<\/Authors>     <Owners>melanchall<\/Owners>     <Description>Dual-lib class library<\/Description>     <Copyright>Copyright \u200b Melanchall 2021<\/Copyright>     <AutoGenerateBindingRedirects>true<\/AutoGenerateBindingRedirects>   <\/PropertyGroup>    <ItemGroup>     <Content Include=\"test.dll\">       <Pack>true<\/Pack>       <CopyToOutputDirectory>Always<\/CopyToOutputDirectory>     <\/Content>     <Content Include=\"test.dylib\">       <Pack>true<\/Pack>       <CopyToOutputDirectory>Always<\/CopyToOutputDirectory>     <\/Content>   <\/ItemGroup>  <\/Project><\/code><\/pre>\n
          Building the package:<\/p>\n
          dotnet pack .\\DualLibClassLibrary.sln -c Release<\/code><\/p>\n
          To check the package installation let\u2019s create a folder somewhere, add it as a packages feed in Visual Studio and put the generated file DualLibClassLibrary.1.0.0.nupkg<\/em> to this folder. We are going to use classic .NET Framework on Windows to check the package installation. Now let\u2019s create a console application and install our library into it. After doing so we can see the two files have appeared in the project:<\/p>\n
          test.dll and test.dylib are fetched from the package<\/figcaption><\/figure>\n
          So good so far, let\u2019s write a simple code within the Program.cs<\/em>:<\/p>\n
          static void Main(string[] args) {     var result = DualLibClassLibrary.Class.Bar();     Console.WriteLine($\"Result = {result}. Press any key to exit...\");     Console.ReadKey(); }<\/code><\/pre>\n
          After running the application we see the unsatisfying picture:<\/p>\n
          The program was not able to find the test.dll<\/figcaption><\/figure>\n
          Well… let\u2019s take a look into bin\/Debug<\/em> folder:<\/p>\n
          test.dll and test.dylib files are missing in the application\u2019s output directory<\/figcaption><\/figure>\n
          Surprisingly enough the files are missing. It is indeed strange since we\u2019ve specified the <CopyToOutputDirectory><\/code> item for them and we do actually see the files within the project structure. But everything becomes clear after we take a look into the .csproj file:<\/p>\n
          Chaos in the .csproj<\/figcaption><\/figure>\n
          We have two weird things here. Firstly the <CopyToOutputDirectory><\/code> item is missing. And secondly, test.dylib has been added as <None><\/code> item but test.dll has been added as <Content><\/code> item. If we take a look into the .nupkg file with NuGet Package Explorer<\/u><\/a>, we\u2019ll see the following manifest:<\/p>\n
          <?xml version=\"1.0\" encoding=\"utf-8\"?> <package xmlns=\"http:\/\/schemas.microsoft.com\/packaging\/2012\/06\/nuspec.xsd\">   <metadata>     <id>DualLibClassLibrary<\/id>     <version>1.0.0<\/version>     <authors>melanchall<\/authors>     <owners><\/owners>     <requireLicenseAcceptance>false<\/requireLicenseAcceptance>     <description>Dual-lib class library<\/description>     <copyright>Copyright \u200b Melanchall 2021<\/copyright>     <dependencies>       <group targetFramework=\".NETFramework4.5\" \/>       <group targetFramework=\".NETStandard2.0\" \/>     <\/dependencies>     <contentFiles>       <files include=\"any\/net45\/test.dll\" buildAction=\"Content\" \/>       <files include=\"any\/netstandard2.0\/test.dll\" buildAction=\"Content\" \/>       <files include=\"any\/net45\/test.dylib\" buildAction=\"Content\" \/>       <files include=\"any\/netstandard2.0\/test.dylib\" buildAction=\"Content\" \/>     <\/contentFiles>   <\/metadata> <\/package><\/code><\/pre>\n
          As you can see, sadly, the files were added without the copyToOutput<\/code> attribute (you can read about the attribute here in the table: Using the contentFiles element for content files<\/u><\/a>).<\/p>\n
          Copying files to the application\u2019s output directory<\/h2>\n
          After looking through the web (including issues on GitHub, answers on StackOverflow and official Microsoft documentation), I modified the files packing elements in the library\u2019s .csproj:<\/p>\n
          <Content Include=\"test.dll\">   <Pack>true<\/Pack>   <CopyToOutputDirectory>Always<\/CopyToOutputDirectory>   <PackageCopyToOutput>true<\/PackageCopyToOutput>   <PackagePath>contentFiles;content<\/PackagePath> <\/Content> <Content Include=\"test.dylib\">   <Pack>true<\/Pack>   <CopyToOutputDirectory>Always<\/CopyToOutputDirectory>   <PackageCopyToOutput>true<\/PackageCopyToOutput>   <PackagePath>contentFiles;content<\/PackagePath> <\/Content><\/code><\/pre>\n
          The <PackageCopyToOutput><\/code> item is exactly what we need to make the copyToOutput<\/code> attribute to appear in the package manifest. Also we explicitly specified destination folders for the files to avoid directories like any<\/em>. If you\u2019re interested in this topic you can read more here: Including content in a package<\/u><\/a>.<\/p>\n
          Let\u2019s build the project one more time and check the manifest:<\/p>\n
          <?xml version=\"1.0\" encoding=\"utf-8\"?> <package xmlns=\"http:\/\/schemas.microsoft.com\/packaging\/2012\/06\/nuspec.xsd\">   <metadata>     <id>DualLibClassLibrary<\/id>     <version>1.0.1<\/version>     <authors>melanchall<\/authors>     <owners><\/owners>     <requireLicenseAcceptance>false<\/requireLicenseAcceptance>     <description>Dual-lib class library<\/description>     <copyright>Copyright \u200b Melanchall 2021<\/copyright>     <dependencies>       <group targetFramework=\".NETFramework4.5\" \/>       <group targetFramework=\".NETStandard2.0\" \/>     <\/dependencies>     <contentFiles>       <files include=\"test.dll\" buildAction=\"Content\" copyToOutput=\"true\" \/>       <files include=\"test.dylib\" buildAction=\"Content\" copyToOutput=\"true\" \/>     <\/contentFiles>   <\/metadata> <\/package><\/code><\/pre>\n
          copyToOutput didn\u2019t help<\/figcaption><\/figure>\n
          Another failure. If we are going to try the same thing in .NET5, we\u2019ll get:<\/p>\n
          Still no files in the application\u2019s output directory<\/figcaption><\/figure>\n
          Basically there\u2019s no difference<\/p>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[],"tags":[],"class_list":["post-385557","post","type-post","status-publish","format-standard","hentry"],"_links":{"self":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/posts\/385557","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=385557"}],"version-history":[{"count":0,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/posts\/385557\/revisions"}],"wp:attachment":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=385557"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=385557"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=385557"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}