Merge pull request #566 from Washi1337/development

6.0.0-beta.1

.editorconfig

@@ -13,6 +13,7 @@ csharp_preferred_modifier_order = public, private, protected, internal, new, abs
 csharp_style_var_elsewhere = true:suggestion
 csharp_style_var_for_built_in_types = false:suggestion
 csharp_style_var_when_type_is_apparent = true:suggestion
+csharp_new_line_before_open_brace = all
 dotnet_style_parentheses_in_arithmetic_binary_operators = never_if_unnecessary:none
 dotnet_style_parentheses_in_other_binary_operators = never_if_unnecessary:none
 dotnet_style_parentheses_in_relational_binary_operators = never_if_unnecessary:none

Directory.Build.props

@@ -7,7 +7,7 @@
         <RepositoryUrl>https://github.com/Washi1337/AsmResolver</RepositoryUrl>
         <RepositoryType>git</RepositoryType>
         <LangVersion>10</LangVersion>
-        <Version>5.5.1</Version>
+        <Version>6.0.0-beta.1</Version>
         <Deterministic>true</Deterministic>
         <UseArtifactsOutput>true</UseArtifactsOutput>
     </PropertyGroup>

LICENSE.md

@@ -1,7 +1,7 @@
 The MIT License (MIT)
 =====================
 
-Copyright © `2016-2021 Washi`
+Copyright © `2016-2024 Washi`
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation
@@ -23,4 +23,3 @@ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.
-

README.md

@@ -5,7 +5,7 @@
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  [![Discord](https://img.shields.io/discord/961647807591243796.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.gg/Y7DTBkbhJJ)
 
-AsmResolver is a Portable Executable (PE) inspection library that is able to read, modify and write executable files. This includes .NET modules as well as native images. The library exposes high-level representations of the PE, while still allowing the user to access low-level structures.
+AsmResolver is a library for reading, modifying and reconstructing Portable Executable (PE) files. It supports PE images running natively on Windows, as well as images containing managed (.NET) metadata.
 
 AsmResolver is released under the MIT license.
 
@@ -16,15 +16,19 @@ AsmResolver has a lot of features. Below is a non-exhaustive list of the highlig
 
 - [x] Create, read, modify, write and patch PE files.
   - [x] Full access to sections, data directories and their interpretations.
-- [x] Rich support for .NET modules with an intuitive API similar to `System.Reflection`.
+  - [x] Import Address Table (IAT) reconstruction and trampolining.
+  - [x] Full control over the layout of the final PE file output.
+- [x] Rich support for various Win32 resource types.
+- [x] Rich support for .NET metadata with an intuitive API similar to `System.Reflection`.
   - [x] Managed, native and dynamic method body support.
   - [x] Easy metadata importing and cloning.
   - [x] Managed resource file serializers and deserializers.
   - [x] Support for AppHost / SingleFileHost bundles.
-  - [x] Support for ReadyToRun binaries.
-- [x] Read PDB symbols.
+  - [x] Support for ReadyToRun (R2R) binaries.
+- [x] Rich read support for PDB and PortablePdb symbols.
   - [x] Fully managed cross-platform API (No DIA or similar required).
-- [x] .NET Standard 2.0 compatible.
+- [x] .NET 3.5 compatible.
+- [x] Cross-platform (Windows and *nix, .NET standard 2.0 and Mono compatible).
 - [x] Documented.
 - [x] Unit tested.
 
@@ -35,6 +39,12 @@ AsmResolver has a lot of features. Below is a non-exhaustive list of the highlig
 - [API Reference](https://docs.washi.dev/asmresolver/api/core/AsmResolver.html)
 
 
+## Support
+
+- [Issue Tracker](https://github.com/Washi1337/AsmResolver/issues)
+- [Discussion Board](https://github.com/washi1337/asmresolver/discussions)
+- [Discord](https://discord.gg/Y7DTBkbhJJ)
+
 ## Binaries
 
 Stable Builds:
@@ -54,7 +64,7 @@ Nightly Builds:
 
 ## Compiling
 
-The solution can be built using the .NET SDK or an IDE that works with it (e.g., Visual Studio and JetBrains Rider). The main packages target LTS versions of various .NET runtimes (.NET Standard 2.0, .NET Core 3.1 and .NET 6.0).
+The solution can be built using the .NET SDK or an IDE that works with it (e.g., Visual Studio and JetBrains Rider). The main packages target LTS versions of various .NET runtimes (.NET 3.5, .NET Standard 2.0, .NET Standard 2.1, .NET Core 3.1, .NET 6.0, .NET 8.0).
 
 To build the project from the command line, use:
 ```bash
@@ -65,26 +75,22 @@ To run all tests, use:
 ```bash
 $ dotnet test
 ```
-For running the tests successfully, you will need to have various versions of .NET installed (ranging from .NET Framework to .NET Core 3.1 and .NET 5+), as the unit tests verify reading binaries targeting various .NET runtimes.
+For running the tests successfully, you will need to have additional versions of .NET installed (including STS versions or versions declared EOL), as the unit tests verify reading binaries targeting various .NET runtimes.
+To run the tests successfully on MacOS and Linux, `mono` and `wine` are expected to be installed as well.
 
 
 ## Contributing
 
 - See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 
-## Support
-
-- [Issue Tracker](https://github.com/Washi1337/AsmResolver/issues)
-- [Discussion Board](github.com/washi1337/asmresolver/discussions)
-- [Discord](https://discord.gg/Y7DTBkbhJJ)
-
-
 ## Acknowledgments
 
 AsmResolver started as a hobby project but has grown into a community project with various contributors. Without these people, AsmResolver would not have been where it is today!
 
-- Special thanks to all the people who contributed [directly with code commits](https://github.com/Washi1337/AsmResolver/graphs/contributors).
+- Special thanks to all the people who contributed [directly with code commits](https://github.com/Washi1337/AsmResolver/graphs/contributors) or monetarily via [GitHub sponsors](https://github.com/sponsors/Washi1337).
+
+- Special thanks to the people at [@MonoMod](https://github.com/MonoMod) for helping with .NET 3.5 compatibility.
 
 - Another big thank you to all the people that suggested new features, provided feedback on the API design, have done extensive testing, and/or reported bugs on the [issue board](https://github.com/Washi1337/AsmResolver/issues), by e-mail, or through DMs.
 

appveyor.yml

@@ -4,7 +4,7 @@
       - master
 
   image: Visual Studio 2022
-  version: 5.5.1-master-build.{build}
+  version: 6.0.0-master-build.{build}
   configuration: Release
 
   skip_commits:
@@ -33,7 +33,7 @@
       - development
 
   image: Visual Studio 2022
-  version: 5.5.1-dev-build.{build}
+  version: 6.0.0-dev-build.{build}
   configuration: Release
 
   skip_commits:

docs/guides/dotnet/advanced-module-reading.md

@@ -1,8 +1,8 @@
 # Advanced Module Reading
 
 Advanced users might need to configure AsmResolver\'s module reader. For
-example, instead of letting the module reader throw exceptions upon
-reading invalid data, errors should be ignored and recovered from. Other
+example, instead of letting the module reader ignore exceptions upon
+reading invalid data, errors could be collected or thrown. Other
 uses might include changing the way the underlying PE or method bodies
 are read. These kinds of settings can be configured using the
 `ModuleReaderParameters` class.
@@ -33,23 +33,24 @@ parameters.PEReaderParameters = new PEReaderParameters
 };
 ```
 
-For example, this can be in particular useful if you want to let
-AsmResolver ignore and recover from invalid data in the input file:
+For example, this can be in particular useful if you want to customize the
+way AsmResolver deals with invalid data.
 
 ``` csharp
-parameters.PEReaderParameters.ErrorListener = EmptyErrorListener.Instance;
+parameters.PEReaderParameters.ErrorListener = ThrowErrorListener.Instance;
 ```
 
 Alternatively, this property can also be set through the constructor of
 the `ModuleReaderParameters` class directly:
 
 ``` csharp
-var parameters = new ModuleReaderParameters(EmptyErrorListener.Instance);
+var parameters = new ModuleReaderParameters(ThrowErrorListener.Instance);
 ```
 
 For more information on customizing the underlying PE image reading
 process, see [Advanced PE Image Reading](../peimage/advanced-pe-reading.md).
 
+
 ## Changing working directory
 
 Modules often depend on other assemblies. These assemblies often are
@@ -154,7 +155,7 @@ public class CustomFieldRvaDataReader : FieldRvaDataReader
     public override ISegment ResolveFieldData(
         IErrorListener listener,
         Platform platform,
-        IDotNetDirectory directory,
+        DotNetDirectory directory,
         in FieldRvaRow fieldRvaRow)
     {
         // ...

docs/guides/dotnet/basics.md

@@ -61,7 +61,7 @@ var module = ModuleDefinition.FromReader(reader);
 ```
 
 ``` csharp
-IPEImage peImage = ...
+PEImage peImage = ...
 var module = ModuleDefinition.FromImage(peImage);
 ```
 
@@ -90,6 +90,36 @@ IntPtr hInstance = Marshal.GetHINSTANCE(module);
 var module = ModuleDefinition.FromModuleBaseAddress(hInstance);
 ```
 
+For more information on customizing the reading process, see [Advanced Module Reading](advanced-module-reading.md).
+
+
+## Opening multiple .NET modules using Runtime Contexts
+
+By default, AsmResolver auto-detects the runtime the module originally targets, and each module assumes their own set of caches and resolved dependencies.
+
+To force a module to be loaded as a specific runtime, define a `RuntimeContext` with the provided runtime info:
+
+```csharp
+// Define a context targeting .NET Core 3.1.
+var context = new RuntimeContext(new DotNetRuntimeInfo(DotNetRuntimeInfo.NetCoreApp, new Version(3, 1)));
+
+// Load module within the context.
+var module = ModuleDefinition.FromFile(@"C:\Path\To\File.exe", new ModuleReaderParameters(context));
+```
+
+Modules can also be loaded explicitly into an existing context from another module:
+
+```csharp
+ModuleDefinition primaryModule = ...;
+
+// Load a module within the same context as the primary module.
+var secondaryModule = ModuleDefinition.FromFile("C:\Path\To\Dependency.dll", new ModuleReaderParameters(primaryModule.RuntimeContext));
+```
+
+Reusing an existing context ensures that the same target runtime is assumed, and that equivalent assembly references resolve to the same assembly definition instances.
+This provides additional caching performance, and avoids many problems when processing multiple files at once.
+
+
 ## Writing a .NET module
 
 Writing a .NET module can be done through one of the `Write` method
@@ -131,7 +161,7 @@ var assembly = AssemblyDefinition.FromFile(@"C:\myfile.exe");
 ```
 
 ``` csharp
-IPEFile peFile = ...
+PEFile peFile = ...
 var assembly = AssemblyDefinition.FromFile(peFile);
 ```
 
@@ -141,7 +171,7 @@ var assembly = AssemblyDefinition.FromReader(reader);
 ```
 
 ``` csharp
-IPEImage peImage = ...
+PEImage peImage = ...
 var assembly = AssemblyDefinition.FromImage(peImage);
 ```
 
@@ -153,6 +183,9 @@ using var service = new MemoryMappedFileService();
 var assembly = AssemblyDefinition.FromFile(service.OpenFile(@"C:\myfile.exe"));
 ```
 
+For more information on customizing the reading process, see [Advanced Module Reading](advanced-module-reading.md).
+
+
 ## Writing a .NET assembly
 
 Writing a .NET assembly can be done through one of the `Write` method

docs/guides/dotnet/bundles.md

@@ -153,7 +153,7 @@ manifest.WriteUsingTemplate(
 > [!NOTE]
 > `BundleManifest` and `BundlerParameters` also define overloads of the
 > `WriteUsingTemplate` and `FromTemplate` / `FromExistingBundle`
-> respectively, taking `byte[]`, `IDataSource` or `IPEImage` instances
+> respectively, taking `byte[]`, `IDataSource` or `PEImage` instances
 > instead of file paths.
 
 

docs/guides/dotnet/index.md

@@ -17,6 +17,6 @@ In short, this means the following:
 
 The third layer of abstraction is the highest level of abstraction for a
 .NET assembly that AsmResolver provides. All objects exposed by this
-layer are completely mutable and can be serialized back to a `IPEImage`
+layer are completely mutable and can be serialized back to a `PEImage`
 from the second layer, to a `PEFile` from the first layer, or to the
 disk.