Please add information on how to upgrade from v1

[Symbai]

The release notes list changes but not API changes. I wanted to upgrade from v1 and noticed a lot of compiling issues I have no idea how to fix them so I get the same result as before:

DataTarget.AttachToProcess => AttachFlag is gone, as well as the timeout parameter. Why? And what should I use now when I was previously using AttachFlag.Passive? ClrInfo.LocalMatchingDac => is gone. What's the new API for this? ClrRuntime.Flush => is gone. What's the new API for this? ClrRuntime.GetMethodByAddress => is gone. What's the new API for this?

Please update the docs and list up all API changes and alternatives when upgrading from v1.

[adamsitnik]

I was not able to find any docs on migrating from v1 to v2 but I was able to migrate BenchmarkDotNet in https://github.com/dotnet/BenchmarkDotNet/pull/2040.

Short summary:

• DataTarget does not support timeout anymore, the AttachFlag enum has been replaced with boolean:

using (var dataTarget = DataTarget.AttachToProcess(
    settings.ProcessId,
-    (uint)TimeSpan.FromSeconds(5).TotalMilliseconds,
-    AttachFlag.Passive))
+    suspend: false))

• There is no need to call dataTarget.DataReader.Flush(); to workaround https://github.com/microsoft/clrmd/issues/303 as the bug has been solved.
• Runtime.Heap does not expose GetTypeByName anymore, instead we need to iterate over the modules and use module.GetTypeByName

+ var typeWithBenchmark = state.Runtime.EnumerateModules().Select(module => module.GetTypeByName(settings.TypeName)).First(type => type != null);
- var typeWithBenchmark = state.Runtime.Heap.GetTypeByName(settings.TypeName);

• We can still configure symbol path, but in a way more easy way:

private static void ConfigureSymbols(DataTarget dataTarget)
{
-    // code copied from https://github.com/Microsoft/clrmd/issues/34#issuecomment-161926535
-    var symbols = dataTarget.DebuggerInterface as IDebugSymbols;
-    symbols?.SetSymbolPath("http://msdl.microsoft.com/download/symbols");
-    var control = dataTarget.DebuggerInterface as IDebugControl;
-    control?.Execute(DEBUG_OUTCTL.NOT_LOGGED, ".reload", DEBUG_EXECUTE.NOT_LOGGED);
+    dataTarget.SetSymbolPath("http://msdl.microsoft.com/download/symbols");
}

• Few properties like ILOffsetMap are no longer using an array, but ImmutableArray instead. Since ImmutableArray is a struct all null checks emit a warning.

• method.GetFullSignature() has been replaced with method.Signature property

• Runtime.DataTarget.ReadProcessMemory has been replaced with Runtime.DataTarget.DataReader.Read

- Runtime.DataTarget.ReadProcessMemory(startAddress, code, code.Length, out int bytesRead)
+ bytesRead = Runtime.DataTarget.DataReader.Read(startAddress, code)

• Runtime.PointerSize has been replaced with Runtime.DataTarget.DataReader.PointerSize
• runtime.GetMethodTableName has been replaced with runtime.DacLibrary.SOSDacInterface.GetMethodTableName
• runtime.GetMethodByAddress has been replaced with runtime.GetMethodByInstructionPointer
• PdbReader type no longer exists, but we can use SymbolReader from TraceEvent to read the symbols

We need to create SymbolReader and configure it to use MS symbol server:

SymbolReader symbolReader = new SymbolReader(TextWriter.Null) { SymbolPath = SymbolPath.MicrosoftSymbolServerPath }

PdbInfo exposes Path property which can be used to open symbol file (there is no need to use Runtime.DataTarget.SymbolLocator):

+ reader = symbolReader.OpenSymbolFile(pdbPath);
- reader = new PdbReader(pdbPath);

There were few other things I had to do to be able to repalce SymbolReader, you can take a look at this source file to get the overall idea