Skip to content

Commit 5afc064

Browse files
MSDN-WhiteKnightViktorHofer
MSDN-WhiteKnight
and
ViktorHofer
authored
Add docs for Microsoft.Extensions.DependencyModel.Library and subclasses (#8327)
* Add initial content * Fix descriptions * Add more docs * Apply suggestions from code review --------- Co-authored-by: Viktor Hofer <[email protected]>
1 parent 7b55041 commit 5afc064

File tree

6 files changed

+213
-101
lines changed

6 files changed

+213
-101
lines changed

‎snippets/csharp/Microsoft.Extensions.DependencyModel/CompilationLibrary/Overview/CompilationLibrarySnippets.cs

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
using System;
2+
using Microsoft.Extensions.DependencyModel;
3+
4+
namespace CompilationLibrarySnippets
5+
{
6+
static class CompilationLibrarySnippets
7+
{
8+
public static void SnippetPrintLibraries()
9+
{
10+
//<SnippetPrintLibraries>
11+
foreach (CompilationLibrary lib in DependencyContext.Default.CompileLibraries)
12+
{
13+
Console.WriteLine($"Library: {lib.Name} {lib.Version}");
14+
Console.WriteLine($"Type: {lib.Type}");
15+
Console.WriteLine("Reference paths:");
16+
17+
foreach (string path in lib.ResolveReferencePaths())
18+
{
19+
Console.WriteLine(path);
20+
}
21+
}
22+
//</SnippetPrintLibraries>
23+
}
24+
}
25+
}

‎snippets/csharp/Microsoft.Extensions.DependencyModel/CompilationLibrary/Overview/CompilationLibrarySnippets.csproj

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>Exe</OutputType>
5+
<TargetFramework>net8.0</TargetFramework>
6+
<PreserveCompilationContext>true</PreserveCompilationContext>
7+
</PropertyGroup>
8+
9+
<ItemGroup>
10+
<PackageReference Include="Microsoft.Extensions.DependencyModel" Version="8.0.0" />
11+
</ItemGroup>
12+
13+
</Project>

‎snippets/csharp/Microsoft.Extensions.DependencyModel/CompilationLibrary/Overview/Program.cs

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
using System;
2+
3+
namespace CompilationLibrarySnippets
4+
{
5+
class Program
6+
{
7+
static void Main()
8+
{
9+
CompilationLibrarySnippets.SnippetPrintLibraries();
10+
}
11+
}
12+
}

‎xml/Microsoft.Extensions.DependencyModel/CompilationLibrary.xml

Lines changed: 53 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,22 @@
2929
</Attribute>
3030
</Attributes>
3131
<Docs>
32-
<summary>To be added.</summary>
33-
<remarks>To be added.</remarks>
32+
<summary>Represents a compile time library dependency in a dependency manifest.</summary>
33+
<remarks>
34+
<format type="text/markdown"><![CDATA[
35+
36+
## Remarks
37+
38+
A compile time library dependency is a library used to compile an application. It can be a [reference assembly](/dotnet/standard/assembly/reference-assemblies) or an implementation assembly. You can use the <xref:Microsoft.Extensions.DependencyModel.DependencyContext.CompileLibraries> property to get the list of compile time library dependencies for a dependency context. This is useful when you need to dynamically compile code (for example, using Roslyn Emit API) referencing the same dependencies as your main application.
39+
40+
## Examples
41+
42+
The following example shows how to display the list of libraries used to compile the current application. Include `<PreserveCompilationContext>true</PreserveCompilationContext>` in your project file to run this example.
43+
44+
:::code language="csharp" source="~/snippets/csharp/Microsoft.Extensions.DependencyModel/CompilationLibrary/Overview/CompilationLibrarySnippets.cs" id="SnippetPrintLibraries":::
45+
46+
]]></format>
47+
</remarks>
3448
</Docs>
3549
<Members>
3650
<Member MemberName=".ctor">
@@ -63,15 +77,19 @@
6377
<Parameter Name="serviceable" Type="System.Boolean" />
6478
</Parameters>
6579
<Docs>
66-
<param name="type">To be added.</param>
67-
<param name="name">To be added.</param>
68-
<param name="version">To be added.</param>
69-
<param name="hash">To be added.</param>
70-
<param name="assemblies">To be added.</param>
71-
<param name="dependencies">To be added.</param>
72-
<param name="serviceable">To be added.</param>
73-
<summary>To be added.</summary>
80+
<param name="type">The library's type.</param>
81+
<param name="name">The library's name.</param>
82+
<param name="version">The library's version.</param>
83+
<param name="hash">The library package's hash.</param>
84+
<param name="assemblies">The library's assemblies.</param>
85+
<param name="dependencies">The library's dependencies.</param>
86+
<param name="serviceable">Whether the library is serviceable.</param>
87+
<summary>Initializes a new instance of the <see cref="T:Microsoft.Extensions.DependencyModel.CompilationLibrary"/> class using the specified library properties.</summary>
7488
<remarks>To be added.</remarks>
89+
<exception cref="T:System.ArgumentException">
90+
<paramref name="type" />, or <paramref name="name" />, or <paramref name="version" /> is <see langword="null" /> or an empty string.</exception>
91+
<exception cref="T:System.ArgumentNullException">
92+
<paramref name="dependencies" /> or <paramref name="assemblies" /> is <see langword="null" />.</exception>
7593
</Docs>
7694
</Member>
7795
<Member MemberName=".ctor">
@@ -120,17 +138,21 @@
120138
</Parameter>
121139
</Parameters>
122140
<Docs>
123-
<param name="type">To be added.</param>
124-
<param name="name">To be added.</param>
125-
<param name="version">To be added.</param>
126-
<param name="hash">To be added.</param>
127-
<param name="assemblies">To be added.</param>
128-
<param name="dependencies">To be added.</param>
129-
<param name="serviceable">To be added.</param>
130-
<param name="path">To be added.</param>
131-
<param name="hashPath">To be added.</param>
132-
<summary>To be added.</summary>
141+
<param name="type">The library's type.</param>
142+
<param name="name">The library's name.</param>
143+
<param name="version">The library's version.</param>
144+
<param name="hash">The library package's hash.</param>
145+
<param name="assemblies">The library's assemblies.</param>
146+
<param name="dependencies">The library's dependencies.</param>
147+
<param name="serviceable">Whether the library is serviceable.</param>
148+
<param name="path">The library package's path.</param>
149+
<param name="hashPath">The library package's hash path.</param>
150+
<summary>Initializes a new instance of the <see cref="T:Microsoft.Extensions.DependencyModel.CompilationLibrary"/> class using the specified library properties and path.</summary>
133151
<remarks>To be added.</remarks>
152+
<exception cref="T:System.ArgumentException">
153+
<paramref name="type" />, or <paramref name="name" />, or <paramref name="version" /> is <see langword="null" /> or an empty string.</exception>
154+
<exception cref="T:System.ArgumentNullException">
155+
<paramref name="dependencies" /> or <paramref name="assemblies" /> is <see langword="null" />.</exception>
134156
</Docs>
135157
</Member>
136158
<Member MemberName="Assemblies">
@@ -150,8 +172,8 @@
150172
<ReturnType>System.Collections.Generic.IReadOnlyList&lt;System.String&gt;</ReturnType>
151173
</ReturnValue>
152174
<Docs>
153-
<summary>To be added.</summary>
154-
<value>To be added.</value>
175+
<summary>Gets the list of assemblies for this library.</summary>
176+
<value>The list of assemblies for this library.</value>
155177
<remarks>To be added.</remarks>
156178
</Docs>
157179
</Member>
@@ -173,9 +195,11 @@
173195
</ReturnValue>
174196
<Parameters />
175197
<Docs>
176-
<summary>To be added.</summary>
177-
<returns>To be added.</returns>
198+
<summary>Gets the collection of absolute reference paths for this library.</summary>
199+
<returns>The collection of absolute reference paths for this library.</returns>
178200
<remarks>To be added.</remarks>
201+
<exception cref="T:System.InvalidOperationException">
202+
Library location is not found.</exception>
179203
</Docs>
180204
</Member>
181205
<Member MemberName="ResolveReferencePaths">
@@ -205,10 +229,12 @@
205229
</Parameter>
206230
</Parameters>
207231
<Docs>
208-
<param name="customResolvers">To be added.</param>
209-
<summary>To be added.</summary>
210-
<returns>To be added.</returns>
232+
<param name="customResolvers">The array of custom assembly resolvers.</param>
233+
<summary>Gets the collection of absolute reference paths for this library using specified custom resolvers.</summary>
234+
<returns>The collection of absolute reference paths for this library.</returns>
211235
<remarks>To be added.</remarks>
236+
<exception cref="T:System.InvalidOperationException">
237+
Library location is not found.</exception>
212238
</Docs>
213239
</Member>
214240
</Members>

‎xml/Microsoft.Extensions.DependencyModel/Library.xml

Lines changed: 64 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
</Attribute>
3030
</Attributes>
3131
<Docs>
32-
<summary>To be added.</summary>
32+
<summary>Represents a library dependency in a dependency manifest.</summary>
3333
<remarks>To be added.</remarks>
3434
</Docs>
3535
<Members>
@@ -62,13 +62,13 @@
6262
<Parameter Name="serviceable" Type="System.Boolean" />
6363
</Parameters>
6464
<Docs>
65-
<param name="type">To be added.</param>
66-
<param name="name">To be added.</param>
67-
<param name="version">To be added.</param>
68-
<param name="hash">To be added.</param>
69-
<param name="dependencies">To be added.</param>
70-
<param name="serviceable">To be added.</param>
71-
<summary>To be added.</summary>
65+
<param name="type">The library's type.</param>
66+
<param name="name">The library's name.</param>
67+
<param name="version">The library's version.</param>
68+
<param name="hash">The library package's hash.</param>
69+
<param name="dependencies">The library's dependencies.</param>
70+
<param name="serviceable">Whether the library is serviceable.</param>
71+
<summary>Initializes a new instance of the <see cref="T:Microsoft.Extensions.DependencyModel.Library"/> class using the specified library properties.</summary>
7272
<remarks>To be added.</remarks>
7373
</Docs>
7474
</Member>
@@ -117,16 +117,20 @@
117117
</Parameter>
118118
</Parameters>
119119
<Docs>
120-
<param name="type">To be added.</param>
121-
<param name="name">To be added.</param>
122-
<param name="version">To be added.</param>
123-
<param name="hash">To be added.</param>
124-
<param name="dependencies">To be added.</param>
125-
<param name="serviceable">To be added.</param>
126-
<param name="path">To be added.</param>
127-
<param name="hashPath">To be added.</param>
128-
<summary>To be added.</summary>
120+
<param name="type">The library's type.</param>
121+
<param name="name">The library's name.</param>
122+
<param name="version">The library's version.</param>
123+
<param name="hash">The library package's hash.</param>
124+
<param name="dependencies">The library's dependencies.</param>
125+
<param name="serviceable">Whether the library is serviceable.</param>
126+
<param name="path">The library package's path.</param>
127+
<param name="hashPath">The library package's hash path.</param>
128+
<summary>Initializes a new instance of the <see cref="T:Microsoft.Extensions.DependencyModel.Library"/> class using the specified library properties and path.</summary>
129129
<remarks>To be added.</remarks>
130+
<exception cref="T:System.ArgumentException">
131+
<paramref name="type" />, or <paramref name="name" />, or <paramref name="version" /> is <see langword="null" /> or an empty string.</exception>
132+
<exception cref="T:System.ArgumentNullException">
133+
<paramref name="dependencies" /> is <see langword="null" />.</exception>
130134
</Docs>
131135
</Member>
132136
<Member MemberName=".ctor">
@@ -181,17 +185,21 @@
181185
</Parameter>
182186
</Parameters>
183187
<Docs>
184-
<param name="type">To be added.</param>
185-
<param name="name">To be added.</param>
186-
<param name="version">To be added.</param>
187-
<param name="hash">To be added.</param>
188-
<param name="dependencies">To be added.</param>
189-
<param name="serviceable">To be added.</param>
190-
<param name="path">To be added.</param>
191-
<param name="hashPath">To be added.</param>
192-
<param name="runtimeStoreManifestName">To be added.</param>
193-
<summary>To be added.</summary>
188+
<param name="type">The library's type.</param>
189+
<param name="name">The library's name.</param>
190+
<param name="version">The library's version.</param>
191+
<param name="hash">The library package's hash.</param>
192+
<param name="dependencies">The library's dependencies.</param>
193+
<param name="serviceable">Whether the library is serviceable.</param>
194+
<param name="path">The library package's path.</param>
195+
<param name="hashPath">The library package's hash path.</param>
196+
<param name="runtimeStoreManifestName">The library's runtime store manifest name.</param>
197+
<summary>Initializes a new instance of the <see cref="T:Microsoft.Extensions.DependencyModel.Library"/> class using the specified library properties, path and runtime store manifest.</summary>
194198
<remarks>To be added.</remarks>
199+
<exception cref="T:System.ArgumentException">
200+
<paramref name="type" />, or <paramref name="name" />, or <paramref name="version" /> is <see langword="null" /> or an empty string.</exception>
201+
<exception cref="T:System.ArgumentNullException">
202+
<paramref name="dependencies" /> is <see langword="null" />.</exception>
195203
</Docs>
196204
</Member>
197205
<Member MemberName="Dependencies">
@@ -211,8 +219,8 @@
211219
<ReturnType>System.Collections.Generic.IReadOnlyList&lt;Microsoft.Extensions.DependencyModel.Dependency&gt;</ReturnType>
212220
</ReturnValue>
213221
<Docs>
214-
<summary>To be added.</summary>
215-
<value>To be added.</value>
222+
<summary>Gets the list of dependencies of this library.</summary>
223+
<value>The list of dependencies of this library.</value>
216224
<remarks>To be added.</remarks>
217225
</Docs>
218226
</Member>
@@ -243,8 +251,8 @@
243251
<ReturnType>System.String</ReturnType>
244252
</ReturnValue>
245253
<Docs>
246-
<summary>To be added.</summary>
247-
<value>To be added.</value>
254+
<summary>Gets the hash of the package, if this library is a package.</summary>
255+
<value>The hash of the package, if this library is a package.</value>
248256
<remarks>To be added.</remarks>
249257
</Docs>
250258
</Member>
@@ -275,8 +283,8 @@
275283
<ReturnType>System.String</ReturnType>
276284
</ReturnValue>
277285
<Docs>
278-
<summary>To be added.</summary>
279-
<value>To be added.</value>
286+
<summary>Gets the relative path to the library package hash file, if this library is a package.</summary>
287+
<value>The relative path to the library package hash file, if this library is a package.</value>
280288
<remarks>To be added.</remarks>
281289
</Docs>
282290
</Member>
@@ -297,8 +305,8 @@
297305
<ReturnType>System.String</ReturnType>
298306
</ReturnValue>
299307
<Docs>
300-
<summary>To be added.</summary>
301-
<value>To be added.</value>
308+
<summary>Gets the library name.</summary>
309+
<value>The library name.</value>
302310
<remarks>To be added.</remarks>
303311
</Docs>
304312
</Member>
@@ -329,8 +337,8 @@
329337
<ReturnType>System.String</ReturnType>
330338
</ReturnValue>
331339
<Docs>
332-
<summary>To be added.</summary>
333-
<value>To be added.</value>
340+
<summary>Gets the relative path to package assets, if this library is a package.</summary>
341+
<value>The relative path to package assets, if this library is a package.</value>
334342
<remarks>To be added.</remarks>
335343
</Docs>
336344
</Member>
@@ -383,8 +391,8 @@
383391
<ReturnType>System.Boolean</ReturnType>
384392
</ReturnValue>
385393
<Docs>
386-
<summary>To be added.</summary>
387-
<value>To be added.</value>
394+
<summary>Gets a value that indicates whether this library can be serviced, if this library is a package.</summary>
395+
<value><c>true</c> if this library can be serviced; otherwise, <c>false</c></value>
388396
<remarks>To be added.</remarks>
389397
</Docs>
390398
</Member>
@@ -405,9 +413,21 @@
405413
<ReturnType>System.String</ReturnType>
406414
</ReturnValue>
407415
<Docs>
408-
<summary>To be added.</summary>
409-
<value>To be added.</value>
410-
<remarks>To be added.</remarks>
416+
<summary>Gets the type of this library.</summary>
417+
<value>The type of this library.</value>
418+
<remarks>
419+
<format type="text/markdown"><![CDATA[
420+
421+
## Remarks
422+
423+
The common library type values are:
424+
425+
- `package` - NuGet package
426+
- `project` - Project reference
427+
- `referenceassembly` - Reference assembly
428+
429+
]]></format>
430+
</remarks>
411431
</Docs>
412432
</Member>
413433
<Member MemberName="Version">
@@ -427,8 +447,8 @@
427447
<ReturnType>System.String</ReturnType>
428448
</ReturnValue>
429449
<Docs>
430-
<summary>To be added.</summary>
431-
<value>To be added.</value>
450+
<summary>Gets the version of this library.</summary>
451+
<value>The version of this library.</value>
432452
<remarks>To be added.</remarks>
433453
</Docs>
434454
</Member>

0 commit comments

Comments
 (0)