Debian Codegraph @

external/api-doc-tools/mdoc/Mono.Documentation/Updater/Frameworks/MDocResolver.cs

raw
1 using System;
2 using System.Collections.Generic;
3 using System.IO;
4 using System.Linq;
5 using System.Text;
6 using Mono.Cecil;
7 using Mono.Collections.Generic;
8
9 namespace Mono.Documentation.Updater.Frameworks
10 {
11 /// <summary>resolver to handle assembly lookups</summary>
12 /// <remarks><para>This resolver handles two scenarios. First is UWP
13 /// references to 'mscorlib' (which simply picks up the 4.5 version,
14 /// or whatever you have installed). And second, it tries its
15 /// best to match on version. If it can't find the exact version, it
16 /// will try to find the next highest version, and if that fails,
17 /// a lower version if available.</para>
18 /// <para>Please note that you will need to provide a reference
19 /// to the UWP framework directory, if you are trying to document
20 /// a UWP library. </para></remarks>
21 public class MDocResolver : MDocBaseResolver
22 {
23 public bool MatchHighestVersionOnZeroVersion { get; private set; }
24
25 public class TypeForwardEventArgs : EventArgs
26 {
27 public AssemblyNameReference From { get; private set; }
28 public AssemblyNameReference To { get; private set; }
29 /// <summary>The Type's FullName</summary>
30 public string ForType { get; set; }
31
32 public TypeForwardEventArgs(AssemblyNameReference from, AssemblyNameReference to, string forType)
33 {
34 From = from;
35 To = to;
36 ForType = forType;
37 }
38
39 public override string ToString()
40 {
41 return $"forward {ForType} from {From} to {To}";
42 }
43 }
44
45 public MDocResolver() : base()
46 {
47 try
48 {
49 this.RemoveSearchDirectory(".");
50 this.RemoveSearchDirectory("bin");
51 }
52 catch { }
53 }
54
55 public override AssemblyDefinition Resolve(AssemblyNameReference name, ReaderParameters parameters)
56 {
57 return Resolve(name, parameters, null, null);
58 }
59
60 public event EventHandler<TypeForwardEventArgs> TypeExported;
61
62 internal AssemblyDefinition Resolve(AssemblyNameReference name, ReaderParameters r, TypeReference forType, List<string> exportedFiles)
63 {
64 if (exportedFiles == null)
65 exportedFiles = new List<string>();
66
67 var a = this.ResolveCore(name, r, exportedFiles);
68
69 if (forType != null && a.MainModule.HasExportedTypes)
70 {
71 var etype = a.MainModule.ExportedTypes.SingleOrDefault(t => t.FullName == forType.FullName) as ExportedType;
72 if (etype != null)
73 {
74 string file = a.MainModule.FileName;
75 AssemblyNameReference exportedTo = (AssemblyNameReference)etype.Scope;
76 Console.WriteLine($"resolving {forType.FullName} in {name.FullName}. Found {file}, but it's exported to {exportedTo.FullName}");
77 if (forType != null)
78 TypeExported?.Invoke(this, new TypeForwardEventArgs(name, exportedTo, forType?.FullName));
79
80 exportedFiles.Add(file);
81 return Resolve(exportedTo, r, forType, exportedFiles);
82 }
83 }
84
85 return a;
86 }
87
88 AssemblyDefinition ResolveCore(AssemblyNameReference name, ReaderParameters parameters, IEnumerable<string> assembliesToIgnore)
89 {
90 var ver = name.Version;
91 if (ver.Major == 255 && ver.Minor == 255 && ver.Revision == 255 && name.Name == "mscorlib")
92 {
93 var v = new Version(4, 5, 0);
94 var anr = new AssemblyNameReference(name.Name, v);
95 return base.Resolve(anr, parameters, assembliesToIgnore);
96 }
97 else
98 return base.Resolve(name, parameters, assembliesToIgnore);
99 }
100
101 IEnumerable<AssemblyDefinition> GetInstalledAssemblies(AssemblyNameReference name, ReaderParameters parameters, IEnumerable<string> filesToIgnore)
102 {
103 AssemblyDefinition assembly;
104 if (name.IsRetargetable)
105 {
106 // if the reference is retargetable, zero it
107 name = new AssemblyNameReference(name.Name, MDocResolverMixin.ZeroVersion)
108 {
109 PublicKeyToken = Empty<byte>.Array,
110 };
111 }
112
113 string[] framework_dirs = GetFrameworkPaths();
114
115 if (IsZero(name.Version))
116 {
117 assembly = base.SearchDirectory(name, framework_dirs, parameters, filesToIgnore);
118 if (assembly != null)
119 yield return assembly;
120 }
121
122 if (name.Name == "mscorlib")
123 {
124 assembly = base.GetCorlib(name, parameters);
125 if (assembly != null)
126 yield return assembly;
127 }
128
129 assembly = base.GetAssemblyInGac(name, parameters);
130 if (assembly != null)
131 yield return assembly;
132
133 assembly = base.SearchDirectory(name, framework_dirs, parameters, filesToIgnore);
134 if (assembly != null)
135 yield return assembly;
136 }
137
138 protected override AssemblyDefinition SearchDirectory(AssemblyNameReference name, IEnumerable<string> directories, ReaderParameters parameters, IEnumerable<string> filesToIgnore)
139 {
140 // look in all sub directies for assemblies
141 var namedPaths = GetAssemblyPaths(name, directories, filesToIgnore, true).ToArray();
142
143 if (!namedPaths.Any()) return null;
144
145 Func<Version, int> aggregateVersion = version => version.Major * 100000 +
146 version.Minor * 10000 +
147 version.Build * 10 +
148 version.Revision;
149
150 Func<string, AssemblyDefinition> getAssemblies = (path) => {
151 return GetAssembly(path, parameters);
152 };
153
154 var applicableVersions = namedPaths
155 .Select(getAssemblies)
156 .Concat(GetInstalledAssemblies(name, parameters, filesToIgnore))
157 .Select(a => new
158 {
159 Assembly = a,
160 SuppliedDependency = namedPaths.Any(np => np == a.MainModule.FileName),
161 VersionSort = aggregateVersion(a.Name.Version),
162 VersionDiff = aggregateVersion(a.Name.Version) - aggregateVersion(name.Version),
163 MajorMatches = a.Name.Version.Major == name.Version.Major
164 });
165
166 AssemblyDefinition assemblyToUse = null;
167
168 // If the assembly has all zeroes, just grab the latest assembly
169 if (IsZero(name.Version))
170 {
171 if (!this.MatchHighestVersionOnZeroVersion)
172 return applicableVersions.First().Assembly;
173 else
174 {
175 var possibleSet = applicableVersions;
176 if (applicableVersions.Any(s => s.SuppliedDependency))
177 possibleSet = applicableVersions.Where(av => av.SuppliedDependency).ToArray();
178
179 var sorted = possibleSet.OrderByDescending(v => v.VersionSort).ToArray();
180
181 var highestMatch = sorted.FirstOrDefault();
182 if (highestMatch != null)
183 {
184 assemblyToUse = highestMatch.Assembly;
185 goto TheReturn;
186 }
187 }
188 }
189
190 applicableVersions = applicableVersions.ToArray();
191
192 // Perfect Match
193 var exactMatch = applicableVersions.FirstOrDefault(v => v.VersionDiff == 0);
194 if (exactMatch != null)
195 {
196 assemblyToUse = exactMatch.Assembly;
197 goto TheReturn;
198 }
199
200 // closest high version
201 var newerVersions = applicableVersions
202 .Where(v => v.VersionDiff > 0)
203 .OrderBy(a => a.VersionSort)
204 .Select(v => v.Assembly)
205 .ToArray();
206 if (newerVersions.Any())
207 {
208 assemblyToUse = newerVersions.First();
209 goto TheReturn;
210 }
211
212 // Are there any lower versions as a last resort?
213 var olderVersions = applicableVersions
214 .Where(v => v.VersionDiff < 0)
215 .OrderByDescending(v => v.VersionSort)
216 .Select(v => v.Assembly)
217 .ToArray();
218 if (olderVersions.Any())
219 {
220 assemblyToUse = olderVersions.First();
221 goto TheReturn;
222 }
223
224 // return null if you don't find anything
225 TheReturn:
226 foreach (var assemblyToDisposeOf in applicableVersions.Where(a => a.Assembly != assemblyToUse))
227 {
228 assemblyToDisposeOf.Assembly.Dispose();
229 }
230 return assemblyToUse;
231
232 }
233
234 // some helper classes
235 static class Empty<T>
236 {
237 public static readonly T[] Array = new T[0];
238 }
239
240 class MDocResolverMixin
241 {
242 public static Version ZeroVersion = new Version(0, 0, 0, 0);
243 }
244 }
245
246 /// <summary>
247 /// Wraps a resolver, and caches assemblies to avoid excessive calls to disk
248 /// </summary>
249 /// <remarks>
250 /// Inspired by Mono.Cecil's DefaultAssemblyResolver (<see href="https://github.com/jbevain/cecil/blob/master/Mono.Cecil/DefaultAssemblyResolver.cs"/>).
251 /// The big difference with this implementation, is one of using composition over inheritance.
252 /// </remarks>
253 public class CachedResolver : IAssemblyResolver
254 {
255 readonly IDictionary<string, AssemblyDefinition> cache;
256
257 public IAssemblyResolver Resolver { get; private set; }
258
259 public CachedResolver(IAssemblyResolver resolver)
260 {
261 Resolver = resolver;
262 cache = new Dictionary<string, AssemblyDefinition>(StringComparer.Ordinal);
263 }
264
265 public AssemblyDefinition Resolve(AssemblyNameReference name)
266 {
267 return Resolve(name, new ReaderParameters() { AssemblyResolver = this });
268 }
269
270 float lastAverageStackLength = 0;
271 int stackTraceIncrease = 0;
272 Dictionary<string, int> dict = new Dictionary<string, int>();
273 Queue<float> traces = new Queue<float>(10);
274
275 public AssemblyDefinition Resolve(AssemblyNameReference name, ReaderParameters parameters)
276 {
277 return ResolveCore(name, parameters, null);
278 }
279
280 internal AssemblyDefinition ResolveCore(AssemblyNameReference name, ReaderParameters parameters, TypeReference forType)
281 {
282 string cacheKey = name.FullName;
283 AssemblyDefinition assembly;
284
285 if (cache.TryGetValue(cacheKey, out assembly))
286 {
287 if (forType != null && assembly.MainModule.HasExportedTypes)
288 {
289 // check to see if the type is in the exported assemblies
290 var etype = assembly.MainModule.ExportedTypes.SingleOrDefault(et => et.FullName == forType.FullName);
291 if (etype != null)
292 {
293 var escope = (AssemblyNameReference)etype.Scope;
294 if (cache.TryGetValue(escope.FullName, out assembly))
295 {
296 return assembly;
297 }
298 else
299 {
300 assembly = ((MDocResolver)this.Resolver).Resolve(escope, parameters, forType, null);
301 cache[escope.FullName] = assembly;
302 }
303 }
304 }
305 return assembly;
306 }
307
308 assembly = ((MDocResolver)this.Resolver).Resolve(name, parameters, forType, null);
309 cache[cacheKey] = assembly;
310
311 return assembly;
312 }
313
314 protected void RegisterAssembly(AssemblyDefinition assembly)
315 {
316 if (assembly == null)
317 throw new ArgumentNullException(nameof(assembly));
318
319 var name = assembly.Name.FullName;
320 if (cache.ContainsKey(name))
321 return;
322
323 cache[name] = assembly;
324 }
325
326 bool disposed = false;
327 public void Dispose()
328 {
329 if (disposed) return;
330
331 foreach (var assembly in cache.Values)
332 assembly.Dispose();
333
334 cache.Clear();
335
336 Resolver.Dispose();
337
338 disposed = true;
339 }
340
341 }
342
343 /// <summary>
344 /// Sourced from Mono.Cecil's BaseAssemblyResolver: <see href="https://github.com/jbevain/cecil/blob/master/Mono.Cecil/BaseAssemblyResolver.cs" />
345 /// </summary>
346 /// <remarks>
347 /// There are two changes made from the original source
348 /// </remarks>
349 public abstract class MDocBaseResolver : BaseAssemblyResolver
350 {
351 static readonly bool on_mono = Type.GetType("Mono.Runtime") != null;
352
353 Collection<string> gac_paths;
354
355 protected AssemblyDefinition GetAssembly(string file, ReaderParameters parameters)
356 {
357 if (parameters.AssemblyResolver == null)
358 parameters.AssemblyResolver = this;
359
360 return ModuleDefinition.ReadModule(file, parameters).Assembly;
361 }
362
363 public override AssemblyDefinition Resolve(AssemblyNameReference name)
364 {
365 return this.Resolve(name, new ReaderParameters());
366 }
367
368 string[] emptyStringArray = new string[0];
369
370 public override AssemblyDefinition Resolve(AssemblyNameReference name, ReaderParameters parameters)
371 {
372 return Resolve(name, parameters, emptyStringArray);
373 }
374
375 internal AssemblyDefinition Resolve(AssemblyNameReference name, ReaderParameters parameters, IEnumerable<string> filesToIgnore)
376 {
377 var directories = this.GetSearchDirectories();
378
379 var assembly = SearchDirectory(name, directories, parameters, filesToIgnore);
380 if (assembly != null)
381 return assembly;
382
383 if (name.IsRetargetable)
384 {
385 // if the reference is retargetable, zero it
386 name = new AssemblyNameReference(name.Name, MDocResolverMixin.ZeroVersion)
387 {
388 PublicKeyToken = Empty<byte>.Array,
389 };
390 }
391
392 string[] framework_dirs = GetFrameworkPaths();
393
394 if (IsZero(name.Version))
395 {
396 assembly = SearchDirectory(name, framework_dirs, parameters, filesToIgnore);
397 if (assembly != null)
398 return assembly;
399 }
400
401 if (name.Name == "mscorlib")
402 {
403 assembly = GetCorlib(name, parameters);
404 if (assembly != null)
405 return assembly;
406 }
407
408 assembly = GetAssemblyInGac(name, parameters);
409 if (assembly != null)
410 return assembly;
411
412 assembly = SearchDirectory(name, framework_dirs, parameters, filesToIgnore);
413 if (assembly != null)
414 return assembly;
415
416 throw new AssemblyResolutionException(name);
417 }
418
419 protected virtual AssemblyDefinition SearchDirectory(AssemblyNameReference name, IEnumerable<string> directories, ReaderParameters parameters, IEnumerable<string> filesToIgnore)
420 {
421 // just look in the current directory for a matching assembly
422 foreach (var file in GetAssemblyPaths(name, directories, filesToIgnore, false))
423 {
424 try
425 {
426 return GetAssembly(file, parameters);
427 }
428 catch (BadImageFormatException)
429 {
430 continue;
431 }
432 }
433
434 return null;
435 }
436
437 internal static bool IsZero(Version version)
438 {
439 return version.Major == 0 && version.Minor == 0 && version.Build == 0 && version.Revision == 0;
440 }
441
442 internal AssemblyDefinition GetCorlib(AssemblyNameReference reference, ReaderParameters parameters)
443 {
444 var version = reference.Version;
445 var corlib = typeof(object).Assembly.GetName();
446
447 if (corlib.Version == version || IsZero(version))
448 return GetAssembly(typeof(object).Module.FullyQualifiedName, parameters);
449
450 var path = Directory.GetParent(
451 Directory.GetParent(
452 typeof(object).Module.FullyQualifiedName).FullName
453 ).FullName;
454
455 if (on_mono)
456 {
457 if (version.Major == 1)
458 path = Path.Combine(path, "1.0");
459 else if (version.Major == 2)
460 {
461 if (version.MajorRevision == 5)
462 path = Path.Combine(path, "2.1");
463 else
464 path = Path.Combine(path, "2.0");
465 }
466 else if (version.Major == 4)
467 path = Path.Combine(path, "4.0");
468 else
469 throw new NotSupportedException("Version not supported: " + version);
470 }
471 else
472 {
473 switch (version.Major)
474 {
475 case 1:
476 if (version.MajorRevision == 3300)
477 path = Path.Combine(path, "v1.0.3705");
478 else
479 path = Path.Combine(path, "v1.0.5000.0");
480 break;
481 case 2:
482 path = Path.Combine(path, "v2.0.50727");
483 break;
484 case 4:
485 path = Path.Combine(path, "v4.0.30319");
486 break;
487 default:
488 throw new NotSupportedException("Version not supported: " + version);
489 }
490 }
491
492 var file = Path.Combine(path, "mscorlib.dll");
493 if (File.Exists(file))
494 return GetAssembly(file, parameters);
495
496 // if we haven't found mscorlib so far, let's just fall back on the currently executing version:
497 return GetAssembly(typeof(object).Module.FullyQualifiedName, parameters);
498 }
499
500 protected static Collection<string> GetGacPaths()
501 {
502 if (on_mono)
503 return GetDefaultMonoGacPaths();
504
505 var paths = new Collection<string>(2);
506 var windir = Environment.GetEnvironmentVariable("WINDIR");
507 if (windir == null)
508 return paths;
509
510 paths.Add(Path.Combine(windir, "assembly"));
511 paths.Add(Path.Combine(windir, Path.Combine("Microsoft.NET", "assembly")));
512 return paths;
513 }
514
515 protected static string[] GetFrameworkPaths()
516 {
517 var framework_dir = Path.GetDirectoryName(typeof(object).Module.FullyQualifiedName);
518 var framework_dirs = on_mono
519 ? new[] { framework_dir, Path.Combine(framework_dir, "Facades") }
520 : new[] { framework_dir };
521
522 if (!on_mono)
523 {
524 framework_dirs = framework_dirs
525 .Concat(new[]
526 {
527 @"C:\Program Files\dotnet\sdk",
528 @"C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework",
529 @"C:\Program Files\Reference Assemblies\Microsoft\Framework\.NETFramework"
530 })
531 .Where(Directory.Exists)
532 .ToArray();
533 }
534 return framework_dirs;
535 }
536
537 static Collection<string> GetDefaultMonoGacPaths()
538 {
539 var paths = new Collection<string>(1);
540 var gac = GetCurrentMonoGac();
541 if (gac != null)
542 paths.Add(gac);
543
544 var gac_paths_env = Environment.GetEnvironmentVariable("MONO_GAC_PREFIX");
545 if (string.IsNullOrEmpty(gac_paths_env))
546 return paths;
547
548 var prefixes = gac_paths_env.Split(Path.PathSeparator);
549 foreach (var prefix in prefixes)
550 {
551 if (string.IsNullOrEmpty(prefix))
552 continue;
553
554 var gac_path = Path.Combine(Path.Combine(Path.Combine(prefix, "lib"), "mono"), "gac");
555 if (Directory.Exists(gac_path) && !paths.Contains(gac))
556 paths.Add(gac_path);
557 }
558
559 return paths;
560 }
561
562 static string GetCurrentMonoGac()
563 {
564 return Path.Combine(
565 Directory.GetParent(
566 Path.GetDirectoryName(typeof(object).Module.FullyQualifiedName)).FullName,
567 "gac");
568 }
569
570 internal AssemblyDefinition GetAssemblyInGac(AssemblyNameReference reference, ReaderParameters parameters)
571 {
572 if (reference.PublicKeyToken == null || reference.PublicKeyToken.Length == 0)
573 return null;
574
575 if (gac_paths == null)
576 gac_paths = GetGacPaths();
577
578 if (on_mono)
579 return GetAssemblyInMonoGac(reference, parameters);
580
581 return GetAssemblyInNetGac(reference, parameters);
582 }
583
584 AssemblyDefinition GetAssemblyInMonoGac(AssemblyNameReference reference, ReaderParameters parameters)
585 {
586 for (int i = 0; i < gac_paths.Count; i++)
587 {
588 var gac_path = gac_paths[i];
589 var file = GetAssemblyFile(reference, string.Empty, gac_path);
590 if (File.Exists(file))
591 return GetAssembly(file, parameters);
592 }
593
594 return null;
595 }
596
597 AssemblyDefinition GetAssemblyInNetGac(AssemblyNameReference reference, ReaderParameters parameters)
598 {
599 var gacs = new[] { "GAC_MSIL", "GAC_32", "GAC_64", "GAC" };
600 var prefixes = new[] { string.Empty, "v4.0_" };
601
602 for (int i = 0; i < 2; i++)
603 {
604 for (int j = 0; j < gacs.Length; j++)
605 {
606 var gac = Path.Combine(gac_paths[i], gacs[j]);
607 var file = GetAssemblyFile(reference, prefixes[i], gac);
608 if (Directory.Exists(gac) && File.Exists(file))
609 return GetAssembly(file, parameters);
610 }
611 }
612
613 return null;
614 }
615
616 static string GetAssemblyFile(AssemblyNameReference reference, string prefix, string gac)
617 {
618 var gac_folder = new StringBuilder()
619 .Append(prefix)
620 .Append(reference.Version)
621 .Append("__");
622
623 for (int i = 0; i < reference.PublicKeyToken.Length; i++)
624 gac_folder.Append(reference.PublicKeyToken[i].ToString("x2"));
625
626 return Path.Combine(
627 Path.Combine(
628 Path.Combine(gac, reference.Name), gac_folder.ToString()),
629 reference.Name + ".dll");
630 }
631
632 Dictionary<string, string[]> allDirectories = new Dictionary<string, string[]>();
633
634 internal IEnumerable<string> GetAssemblyPaths(AssemblyNameReference name, IEnumerable<string> directories, IEnumerable<string> filesToIgnore, bool subdirectories)
635 {
636 var extensions = name.IsWindowsRuntime ? new[] { ".winmd", ".dll", ".exe" } : new[] { ".exe", ".dll", ".winmd" };
637
638 string[] darray = directories.Distinct().ToArray();
639 string dkey = string.Join("|", darray);
640
641 if (!allDirectories.ContainsKey(dkey))
642 {
643 if (subdirectories)
644 {
645 darray = GetAllDirectories(darray).Distinct().ToArray();
646 }
647
648 // filter out directories that don't have any assemblies
649 darray = darray
650 .Where(d => Directory.Exists(d) && Directory.EnumerateFiles(d, "*.*").Any(f => extensions.Any(e => f.EndsWith(e, StringComparison.OrdinalIgnoreCase))))
651 .ToArray();
652
653 allDirectories.Add(dkey, darray);
654 }
655
656 foreach (var dir in allDirectories[dkey])
657 {
658 foreach (var extension in extensions)
659 {
660 var file = Path.Combine(dir, name.Name + extension);
661
662 if (!File.Exists(file) || filesToIgnore.Any(f => f == file))
663 continue;
664
665 yield return file;
666 }
667 }
668 }
669
670 internal IEnumerable<string> GetAllDirectories(IEnumerable<string> directories)
671 {
672 foreach (var dir in directories)
673 {
674 if (!Directory.Exists(dir))
675 continue;
676
677 yield return dir;
678
679 foreach (var sub in Directory.EnumerateDirectories(dir, "*", SearchOption.AllDirectories))
680 {
681 yield return sub;
682 }
683 }
684 }
685
686 // some helper classes
687 static class Empty<T>
688 {
689 public static readonly T[] Array = new T[0];
690 }
691
692 class MDocResolverMixin
693 {
694 public static Version ZeroVersion = new Version(0, 0, 0, 0);
695 }
696 }
697 }