dnlib-master.zip

# dnlib [](https://www.nuget.org/packages/dnlib/) [](https://github.com/0xd4d/dnlib/actions) .NET module/assembly reader/writer library Opening a .NET assembly/module ------------------------------ First of all, the important namespaces are `dnlib.DotNet` and `dnlib.DotNet.Emit`. `dnlib.DotNet.Emit` is only needed if you intend to read/write method bodies. All the examples below assume you have the appropriate using statements at the top of each source file: ```C# using dnlib.DotNet; using dnlib.DotNet.Emit; ``` ModuleDefMD is the class that is created when you open a .NET module. It has several `Load()` methods that will create a ModuleDefMD instance. If it's not a .NET module/assembly, a `BadImageFormatException` will be thrown. Read a .NET module from a file: ```C# // Create a default assembly resolver and type resolver and pass it to Load(). // If it's a .NET Core assembly, you'll need to disable GAC loading and add // .NET Core reference assembly search paths. ModuleContext modCtx = ModuleDef.CreateModuleContext(); ModuleDefMD module = ModuleDefMD.Load(@"C:\path\to\file.exe", modCtx); ``` Read a .NET module from a byte array: ```C# byte[] data = System.IO.File.ReadAllBytes(@"C:\path\of\file.dll"); // See comment above about the assembly resolver ModuleContext modCtx = ModuleDef.CreateModuleContext(); ModuleDefMD module = ModuleDefMD.Load(data, modCtx); ``` You can also pass in a Stream instance, an address in memory (HINSTANCE) or even a System.Reflection.Module instance: ```C# System.Reflection.Module reflectionModule = typeof(void).Module; // Get mscorlib.dll's module // See comment above about the assembly resolver ModuleContext modCtx = ModuleDef.CreateModuleContext(); ModuleDefMD module = ModuleDefMD.Load(reflectionModule, modCtx); ``` To get the assembly, use its Assembly property: ```C# AssemblyDef asm = module.Assembly; Console.WriteLine("Assembly: {0}", asm); ``` If it's an obfuscated Unity/Mono assembly, you need to create a `ModuleCreationOptions` instance and write `CLRRuntimeReaderKind.Mono` to `ModuleCreationOptions.Runtime` and pass in this `ModuleCreationOptions` instance to one of the `ModuleDefMD.Load(...)` methods. Saving a .NET assembly/module ----------------------------- Use `module.Write()`. It can save the assembly to a file or a Stream. ```C# module.Write(@"C:\saved-assembly.dll"); ``` If it's a C++/CLI assembly, you should use `NativeWrite()` ```C# module.NativeWrite(@"C:\saved-assembly.dll"); ``` To detect it at runtime, use this code: ```C# if (module.IsILOnly) { // This assembly has only IL code, and no native code (eg. it's a C# or VB assembly) module.Write(@"C:\saved-assembly.dll"); } else { // This assembly has native code (eg. C++/CLI) module.NativeWrite(@"C:\saved-assembly.dll"); } ``` PDB files --------- PDB files are read from disk by default. You can change this behaviour by creating a `ModuleCreationOptions` and passing it in to the code that creates a module. To save a PDB file, create a `ModuleWriterOptions` / `NativeModuleWriterOptions` and set its `WritePdb` property to `true`. By default, it will create a PDB file with the same name as the output assembly but with a `.pdb` extension. You can override this by writing the PDB file name to `PdbFileName` or writing your own stream to `PdbStream`. If `PdbStream` is initialized, `PdbFileName` should also be initialized because the name of the PDB file will be written to the PE file. ```C# // Create a default assembly resolver and type resolver ModuleContext modCtx = ModuleDef.CreateModuleContext(); var mod = ModuleDefMD.Load(@"C:\myfile.dll", modCtx); // ... var wopts = new dnlib.DotNet.Writer.ModuleWriterOptions(mod); wopts.WritePdb = true; // wopts.PdbFileName = @"C:\out2.pdb"; // Set other file name mod.Write(@"C:\out.dll", wopts); ``` dnlib supports Windows PDBs, portable PDBs and embedded portable PDBs. Windows PDBs ------------ It's only possible to write Windows PDBs on Windows (portable PDBs can be written on any OS). dnlib has a managed Windows PDB reader that supports all OSes. There are two *native* Windows PDB reader and writer implementations, the old `diasymreader.dll` that ships with .NET Framework and `Microsoft.DiaSymReader.Native` which has been updated with more features and bug fixes. dnlib will use `Microsoft.DiaSymReader.Native` if it exists and fall back to `diasymreader.dll` if needed. `PdbReaderOptions` and `PdbWriterOptions` can be used to disable one of them. `Microsoft.DiaSymReader.Native` is a NuGet package with 32-bit and 64-bit native DLLs. You have to add a reference to this NuGet package if you want dnlib to use it. dnlib doesn't add a reference to it. Strong name signing an assembly ------------------------------- Use the following code to strong name sign the assembly when saving it: ```C# using dnlib.DotNet.Writer; ... // Open or create an assembly ModuleDef mod = ModuleDefMD.Load(.....); // Create writer options var opts = new ModuleWriterOptions(mod); // Open or create the strong name key var signatureKey = new StrongNameKey(@"c:\my\file.snk"); // This method will initialize the required properties opts.InitializeStrongNameSigning(mod, signatureKey); // Write and strong name sign the assembly mod.Write(@"C:\out\file.dll", opts); ``` Enhanced strong name signing an assembly ---------------------------------------- See this [MSDN article](http://msdn.microsoft.com/en-us/library/hh415055.aspx) for info on enhanced strong naming. Enhanced strong name signing without key migration: ```C# using dnlib.DotNet.Writer; ... // Open or create an assembly ModuleDef mod = ModuleDefMD.Load(....); // Open or create the signature keys var signatureKey = new StrongNameKey(....); var signaturePubKey = new StrongNamePublicKey(....); // Create module writer options var opts = new ModuleWriterOptions(mod); // This method will initialize the required properties opts.InitializeEnhancedStrongNameSigning(mod, signatureKey, signaturePubKey); // Write and strong name sign the assembly mod.Write(@"C:\out\file.dll", opts); ``` Enhanced strong name signing with key migration: ```C# using dnlib.DotNet.Writer; ... // Open or create an assembly ModuleDef mod = ModuleDefMD.Load(....); // Open or create the identity and signature keys var signatureKey = new StrongNameKey(....); var signaturePubKey = new StrongNamePublicKey(....); var identityKey = new StrongNameKey(....); var identityPubKey = new StrongNamePublicKey(....); // Create module writer options var opts = new ModuleWriterOptions(mod); // This method will initialize the required properties and add // the required attribute to the assembly. opts.InitializeEnhancedStrongNameSigning(mod, signatureKey, signaturePubKey, identityKey, identityPubKey); // Write and strong name sign the assembly mod.Write(@"C:\out\file.dll", opts); ``` Exporting managed methods (DllExport) ------------------------------------- dnlib supports exporting managed methods so the managed DLL file can be loaded by native code and then executed. .NET Framework supports this feature, but there's no guarantee that other CLRs (eg. .NET Core or Mono/Unity) support this feature. In case of .NET Core please be aware that `ijwhost.dll` has to be loaded prior to calling your exported method and that ijwhost currently (as of .NET Core 3.0) does not work if the calling app is self-contained. The `MethodDef` class has an `ExportInfo` property. If it gets initialized, the method gets exported when saving the module. At most