Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: Add DLL references support for file-based API metadata generation #9825

Merged
merged 1 commit into from
Apr 1, 2024
Merged

feat: Add DLL references support for file-based API metadata generation #9825

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions src/Docfx.Dotnet/CompilationHelper.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ public static bool CheckDiagnostics(this Compilation compilation, bool errorAsWa
return errorCount > 0;
}

public static Compilation CreateCompilationFromCSharpFiles(IEnumerable<string> files, IDictionary<string, string> msbuildProperties)
public static Compilation CreateCompilationFromCSharpFiles(IEnumerable<string> files, IDictionary<string, string> msbuildProperties, MetadataReference[] references)
{
var parserOption = GetCSharpParseOptions(msbuildProperties);
var syntaxTrees = files.Select(path => CS.CSharpSyntaxTree.ParseText(File.ReadAllText(path), parserOption, path: path));
Expand All @@ -63,7 +63,7 @@ public static Compilation CreateCompilationFromCSharpFiles(IEnumerable<string> f
assemblyName: null,
options: new CS.CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary, xmlReferenceResolver: XmlFileResolver.Default),
syntaxTrees: syntaxTrees,
references: GetDefaultMetadataReferences("C#"));
references: GetDefaultMetadataReferences("C#").Concat(references));
}

public static Compilation CreateCompilationFromCSharpCode(string code, IDictionary<string, string> msbuildProperties, string? name = null, params MetadataReference[] references)
Expand All @@ -75,10 +75,10 @@ public static Compilation CreateCompilationFromCSharpCode(string code, IDictiona
name,
options: new CS.CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary, xmlReferenceResolver: XmlFileResolver.Default),
syntaxTrees: [syntaxTree],
references: GetDefaultMetadataReferences("C#").Concat(references));
references: GetDefaultMetadataReferences("C#").Concat(references ?? []));
}

public static Compilation CreateCompilationFromVBFiles(IEnumerable<string> files, IDictionary<string, string> msbuildProperties)
public static Compilation CreateCompilationFromVBFiles(IEnumerable<string> files, IDictionary<string, string> msbuildProperties, MetadataReference[] references)
{
var parserOption = GetVisualBasicParseOptions(msbuildProperties);
var syntaxTrees = files.Select(path => VB.VisualBasicSyntaxTree.ParseText(File.ReadAllText(path), parserOption, path: path));
Expand All @@ -87,7 +87,7 @@ public static Compilation CreateCompilationFromVBFiles(IEnumerable<string> files
assemblyName: null,
options: new VB.VisualBasicCompilationOptions(OutputKind.DynamicallyLinkedLibrary, globalImports: GetVBGlobalImports(), xmlReferenceResolver: XmlFileResolver.Default),
syntaxTrees: syntaxTrees,
references: GetDefaultMetadataReferences("VB"));
references: GetDefaultMetadataReferences("VB").Concat(references));
}

public static Compilation CreateCompilationFromVBCode(string code, IDictionary<string, string> msbuildProperties, string? name = null, params MetadataReference[] references)
Expand All @@ -99,19 +99,19 @@ public static Compilation CreateCompilationFromVBCode(string code, IDictionary<s
name,
options: new VB.VisualBasicCompilationOptions(OutputKind.DynamicallyLinkedLibrary, globalImports: GetVBGlobalImports(), xmlReferenceResolver: XmlFileResolver.Default),
syntaxTrees: [syntaxTree],
references: GetDefaultMetadataReferences("VB").Concat(references));
references: GetDefaultMetadataReferences("VB").Concat(references ?? []));
}

public static (Compilation, IAssemblySymbol) CreateCompilationFromAssembly(string assemblyPath, IEnumerable<string>? references = null)
public static (Compilation, IAssemblySymbol) CreateCompilationFromAssembly(string assemblyPath, params MetadataReference[] references)
{
var metadataReference = CreateMetadataReference(assemblyPath);
var compilation = CS.CSharpCompilation.Create(
assemblyName: null,
options: new CS.CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary),
syntaxTrees: s_assemblyBootstrap,
references: GetReferenceAssemblies(assemblyPath)
.Concat(references ?? Enumerable.Empty<string>())
.Select(CreateMetadataReference)
.Concat(references ?? [])
.Append(metadataReference));

var assembly = (IAssemblySymbol)compilation.GetAssemblyOrModuleSymbol(metadataReference)!;
Expand Down
18 changes: 14 additions & 4 deletions src/Docfx.Dotnet/DotnetApiCatalog.Compile.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ partial class DotnetApiCatalog
_ => LoggerVerbosity.Quiet,
});

var workspace = MSBuildWorkspace.Create(msbuildProperties);
using var workspace = MSBuildWorkspace.Create(msbuildProperties);
workspace.WorkspaceFailed += (sender, e) => Logger.LogWarning($"{e.Diagnostic}");

if (files.TryGetValue(FileType.NotSupported, out var unsupportedFiles))
Expand Down Expand Up @@ -88,26 +88,36 @@ await LoadCompilationFromProject(project.AbsolutePath) is { } compilation)
assemblies.Add((compilation.Assembly, compilation));
}

var references = config.References ?? [];
var metadataReferences = references.Select(assemblyPath =>
{
var documentation = XmlDocumentationProvider.CreateFromFile(Path.ChangeExtension(assemblyPath, ".xml"));
return MetadataReference.CreateFromFile(assemblyPath, documentation: documentation);
}).ToArray();

// LoadCompilationFrom C# source files
if (files.TryGetValue(FileType.CSSourceCode, out var csFiles))
{
var compilation = CompilationHelper.CreateCompilationFromCSharpFiles(csFiles.Select(f => f.NormalizedPath), msbuildProperties);
var compilation = CompilationHelper.CreateCompilationFromCSharpFiles(csFiles.Select(f => f.NormalizedPath), msbuildProperties, metadataReferences);
hasCompilationError |= compilation.CheckDiagnostics(config.AllowCompilationErrors);
assemblies.Add((compilation.Assembly, compilation));
}

// LoadCompilationFrom VB source files
if (files.TryGetValue(FileType.VBSourceCode, out var vbFiles))
{
var compilation = CompilationHelper.CreateCompilationFromVBFiles(vbFiles.Select(f => f.NormalizedPath), msbuildProperties);
var compilation = CompilationHelper.CreateCompilationFromVBFiles(vbFiles.Select(f => f.NormalizedPath), msbuildProperties, metadataReferences);
hasCompilationError |= compilation.CheckDiagnostics(config.AllowCompilationErrors);
assemblies.Add((compilation.Assembly, compilation));
}

// Load Compilation from assembly files
if (files.TryGetValue(FileType.Assembly, out var assemblyFiles))
{
foreach (var assemblyFile in assemblyFiles)
{
Logger.LogInfo($"Loading assembly {assemblyFile.NormalizedPath}");
var (compilation, assembly) = CompilationHelper.CreateCompilationFromAssembly(assemblyFile.NormalizedPath, config.References);
var (compilation, assembly) = CompilationHelper.CreateCompilationFromAssembly(assemblyFile.NormalizedPath, metadataReferences);
hasCompilationError |= compilation.CheckDiagnostics(config.AllowCompilationErrors);
assemblies.Add((assembly, compilation));
}
Expand Down
30 changes: 28 additions & 2 deletions test/Docfx.Dotnet.Tests/GenerateMetadataFromCSUnitTest.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,9 @@ public class GenerateMetadataFromCSUnitTest
{
private static readonly Dictionary<string, string> EmptyMSBuildProperties = new();

private static MetadataItem Verify(string code, ExtractMetadataConfig config = null, IDictionary<string, string> msbuildProperties = null)
private static MetadataItem Verify(string code, ExtractMetadataConfig config = null, IDictionary<string, string> msbuildProperties = null, MetadataReference[] references = null)
{
var compilation = CompilationHelper.CreateCompilationFromCSharpCode(code, msbuildProperties ?? EmptyMSBuildProperties, "test.dll");
var compilation = CompilationHelper.CreateCompilationFromCSharpCode(code, msbuildProperties ?? EmptyMSBuildProperties, "test.dll", references);
var extensionMethods = compilation.Assembly.FindExtensionMethods(new(new(), new())).ToArray();
return compilation.Assembly.GenerateMetadataItem(compilation, config, extensionMethods: extensionMethods);
}
Expand Down Expand Up @@ -3771,4 +3771,30 @@ public void F1() {}
Assert.Empty(foo.Items);
}
}

[Fact]
public void TestGenerateMetadataWithReference()
{
string code = @"
namespace Test
{
public class Foo
{
public TupleLibrary.XmlTasks Tasks{ get;set; }
}
}
";
var references = new string[] { "TestData/TupleLibrary.dll" }.Select(assemblyPath =>
{
var documentation = XmlDocumentationProvider.CreateFromFile(Path.ChangeExtension(assemblyPath, ".xml"));
return MetadataReference.CreateFromFile(assemblyPath, documentation: documentation);
}).ToArray();

// Act
var output = Verify(code, references: references);

// Assert
Assert.Contains("TupleLibrary", output.References.Keys);
Assert.Contains("TupleLibrary.XmlTasks", output.References.Keys);
}
}
36 changes: 34 additions & 2 deletions test/Docfx.Dotnet.Tests/GenerateMetadataFromVBUnitTest.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,10 @@ public class GenerateMetadataFromVBUnitTest
{
private static readonly Dictionary<string, string> EmptyMSBuildProperties = new();

private static MetadataItem Verify(string code, ExtractMetadataConfig options = null, IDictionary<string, string> msbuildProperties = null, params MetadataReference[] references)
private static MetadataItem Verify(string code, ExtractMetadataConfig config = null, IDictionary<string, string> msbuildProperties = null, MetadataReference[] references = null)
{
var compilation = CompilationHelper.CreateCompilationFromVBCode(code, msbuildProperties ?? EmptyMSBuildProperties, "test.dll", references);
return compilation.Assembly.GenerateMetadataItem(compilation, options);
return compilation.Assembly.GenerateMetadataItem(compilation, config);
}

[Trait("Related", "Generic")]
Expand Down Expand Up @@ -1643,4 +1643,36 @@ End Namespace
Assert.Empty(foo.Items);
}
}

[Fact]
public void TestGenerateMetadataWithReference()
{
string code = @"
Namespace Test
Public Class Foo
Property Tasks As TupleLibrary.XmlTasks
End Class
End Namespace
namespace Test
{
public class Foo
{
public TupleLibrary.XmlTasks Tasks { get;set; }
}
}
";

var references = new string[] { "TestData/TupleLibrary.dll" }.Select(assemblyPath =>
{
var documentation = XmlDocumentationProvider.CreateFromFile(Path.ChangeExtension(assemblyPath, ".xml"));
return MetadataReference.CreateFromFile(assemblyPath, documentation: documentation);
}).ToArray();

// Act
var output = Verify(code, references: references);

// Assert
Assert.Contains("TupleLibrary", output.References.Keys);
Assert.Contains("TupleLibrary.XmlTasks", output.References.Keys);
}
}