Skip to content

Commit 8d3b1c6

Browse files
sharpchensharpchen
committed
main
1 parent 53df3cb commit 8d3b1c6

File tree

4 files changed

+285
-77
lines changed

4 files changed

+285
-77
lines changed

‎docs/document/Modern CSharp/docs/Parallel Programming/Synchronization/4.Reader & Writer Lock.md‎

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -12,23 +12,16 @@ The primary advantage of a reader-writer lock is that it allows for higher concu
1212
> Use `TryEnter*` and `TryExit*` if a timeout is required.
1313
1414
```cs
15-
internal class Program
16-
{
15+
internal class Program {
1716
private static readonly ReaderWriterLockSlim _lock = new();
18-
private static void Main(string[] args)
19-
{
17+
private static void Main(string[] args) {
2018
var collection = Enumerable.Range(1, 10).ToArray();
21-
var tasks = Enumerable.Range(1, 10).Select(_ =>
22-
{
23-
return Task.Run(() =>
24-
{
25-
try
26-
{
19+
var tasks = Enumerable.Range(1, 10).Select(_ => {
20+
return Task.Run(() => {
21+
try {
2722
_lock.EnterWriteLock();
2823
collection[Random.Shared.Next(collection.Length)] = 111;
29-
}
30-
finally
31-
{
24+
} finally {
3225
_lock.ExitWriteLock();
3326
}
3427
});

‎docs/document/Modern CSharp/docs/Understanding Config Files.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Understanding Config Files
2+
3+
## `appsetting.json`

‎docs/document/Modern CSharp/docs/Understanding MSBuild.md‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
# Understanding MSBuild
2+
3+
## File Types
4+
5+
- `.*proj`: project file for each project
6+
- `.targets`: shared config for project within a same solution, can be imported to another.
7+
- `.props`:
8+
- `*.rsp`: msbuild response file,
9+
10+
### Recommended Usage
11+
12+
- `*.targets`
13+
- set dependent properties
14+
- override properties
15+
16+
## File Structure
17+
18+
- `<Project>`: Top element
19+
- `<PropertyGroup>`: static values can be determined before build.
20+
- child tag can be arbitrary or pre-defined tag
21+
- use `$(propName)` to retrieve value of a property in any expression-allowed attribute, returns empty string if undefined.
22+
- has some builtin properties preserved
23+
- `<ItemGroup>`: items to be included on build, generally are config files
24+
- each child represents a type of items even when only one item was contained
25+
- each item in the child **has well-known metadata**
26+
- children with the same tag name are within a same source(they're just declared separately)
27+
- use `@(itemType)` to retrieve a list of items from *existing* `<ItemGroup>`
28+
- has some builtin item types preserved
29+
- `<Target>`: section to **wrap sub-procedures** and to be invoked during build
30+
- name it like a function
31+
- use `Name` attribute to specify a name for it
32+
- use `DependsOnTargets`, `BeforeTargets`, `AfterTargets` attributes to hook to another target section
33+
34+
> [!NOTE]
35+
> `<PropertyGroup>`, `<ItemGroup>` and `<Target>` could have multiple declarations for better organization or conditional declaration using `Condition` attribute.
36+
37+
## Project Attributes
38+
39+
- `SDK`: sepcify a sdk so that msbuild can prepare dedicated builtin *targets* and *tasks* for corresponding type of project.
40+
> a project with specified `SDK` is sometimes referred as *SDK-style project*
41+
42+
> [!NOTE]
43+
> [Available SDKs](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/overview#available-sdks)
44+
45+
## Property Section
46+
47+
- reserved properties: pre-defined and cannot be overridden
48+
- well-known properties: pre-defined and can be overridden
49+
50+
> [!NOTE]
51+
> [Reserved & Well-Known Properties](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-reserved-and-well-known-properties?view=vs-2022#reserved-and-well-known-properties)
52+
53+
## Item Section
54+
55+
`<ItemGroup>` section is for specifying files to be included on build, one could use builtin.
56+
Attributes for child items are similar to parameters of item-cmdlet in PowerShell.
57+
58+
- `Include`: include items on declaration
59+
- `Exclude`: exclude items on declaration
60+
61+
```xml
62+
<ItemGroup>
63+
<Compile Include="one.cs;three.cs" />
64+
<Compile Exclude="*.fs" />
65+
</ItemGroup>
66+
```
67+
68+
- `Remove`: remove items after declaration, typically inside a `<Target>` section
69+
- optionally use `MatchOnMetadata` together to delete base on another type of items
70+
- optionally use ``
71+
```xml
72+
<ItemGroup>
73+
<CSFile Include="Programs.cs"/>
74+
<CSFile Include="Foo.cs"/>
75+
<CSFile Include="Bar.cs"/>
76+
<Proj Include="Foo.csproj"/>
77+
<Proj Include="bar.csproj"/>
78+
<Proj Include="Baz.csproj"/>
79+
</ItemGroup>
80+
<Target Name="Hello">
81+
<!-- Proj items are to be matched by metadata FileName -->
82+
<ItemGroup>
83+
<CSFile Remove="@(Proj)" <!-- [!code highlight] -->
84+
MatchOnMetadata="FileName" <!-- [!code highlight] -->
85+
MatchOnMetadataOptions="CaseSensitive" /> <!-- [!code highlight] -->
86+
</ItemGroup>
87+
<!-- Remained cs items: Programs.cs -->
88+
<Message Text="Remained cs items: %(CSFile.Identity)" Importance="high"></Message>
89+
</Target>
90+
```
91+
92+
### Default Filters
93+
94+
Builtin item tags like `Compile` has some default wildcards when `SDK` was sepcified.
95+
96+
> [!NOTE]
97+
> [Default Includes and Excludes](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/overview#default-includes-and-excludes)
98+
99+
### Item Metadata
100+
101+
Each item has pre-defined metadata can be accessed.
102+
103+
> [!NOTE]
104+
> [Well-Known Item Metadata](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-well-known-item-metadata?view=vs-2022)
105+
106+
## Expression Syntax
107+
108+
Expression syntax in msbuild has some flavor of Command Prompt and PowerShell.
109+
110+
- **Operators**
111+
- **metadata accessor** `%(itemType.metadataName)`: iterate through the metadata of items for a same action applied on the expression.
112+
- **reference accessor** `$(propName)`: access properties or environment variable or (property is preferred when names conflict)
113+
- access a property with its name
114+
- capture a value calculated from a method call in [a powershell syntax](https://learn.microsoft.com/en-us/visualstudio/msbuild/property-functions?view=vs-2022#msbuild-condition-functions)
115+
- access [registry item](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-properties?view=vs-2022#registry-properties) with its path
116+
- **item accessor** `@(itemType)`
117+
- use `@(itemType, '<sep>')` to concat items using separator
118+
- use `@(itemType->'<metadata_expr>')` to collected transformed values to a list
119+
```xml
120+
<ItemGroup>
121+
<MyFile Include="Programs.cs"/>
122+
<MyFile Include="*.csproj"/>
123+
</ItemGroup>
124+
125+
<Target Name="Hello">
126+
<!-- Collected metadata: Program.cs; ConsoleApp.csproj -->
127+
<Message Text="Collected metadata: @(MyFile->'%(FileName)%(Extension)')" <!-- [!code highlight] -->
128+
Importance="high" /> <!-- [!code highlight] -->
129+
</Target>
130+
```
131+
132+
### Escaping
133+
134+
For [special characters](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-special-characters?view=vs-2022#special-characters), you may figure out its ASCII representation by:
135+
136+
```ps1
137+
[System.Uri]::EscapeDataString('"') # %22
138+
```
139+
140+
```lua
141+
foo
142+
```
143+
144+
> [!TIP]
145+
> Notation like `&quot;` is also viable
146+
147+
## Conditional Component
148+
149+
[Some elements supports conditional include](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-conditions?view=vs-2022#supported-elements) using `Condition` attribute.
150+
So one could include dedicated part of the config for different build scenarios.
151+
152+
```xml
153+
<ItemGroup Condition="'$(DotNetBuildSourceOnly)' == 'true'"> <!-- [!code highlight] -->
154+
<PackageVersion Include="Microsoft.Build" Version="17.3.4" />
155+
<PackageVersion Include="Microsoft.Build.Framework" Version="17.3.4" />
156+
<PackageVersion Include="Microsoft.Build.Tasks.Core" Version="17.3.4" />
157+
<PackageVersion Include="Microsoft.Build.Utilities.Core" Version="17.3.4" />
158+
</ItemGroup>
159+
160+
<ItemGroup Condition="'$(DotNetBuildSourceOnly)' != 'true' and '$(TargetFramework)' != 'net472'"> <!-- [!code highlight] -->
161+
<PackageVersion Include="Microsoft.Build" Version="17.7.2" />
162+
<PackageVersion Include="Microsoft.Build.Framework" Version="17.7.2" />
163+
<PackageVersion Include="Microsoft.Build.Tasks.Core" Version="17.7.2" />
164+
<PackageVersion Include="Microsoft.Build.Utilities.Core" Version="17.7.2" />
165+
</ItemGroup>
166+
```
167+
168+
## Builtin Variables
169+
170+
## MSBuild Task
171+
172+
A task is a pre-defined procedure to be executed in `Target` section in their declared order.
173+
The containing `Target` is like a function which must have a name while a task is just named as its tag.
174+
MSBuild ships with some builtin task to be used out of box.
175+
176+
```xml
177+
<Target>
178+
<Csc
179+
Sources="@(Compile)"
180+
OutputAssembly="$(AppName).exe"
181+
EmitDebugInformation="true" />
182+
</Target>
183+
```
184+
185+
> [!NOTE]
186+
> See: [MSBuild Task Reference](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-task-reference?view=vs-2022#in-this-section)
187+
188+
### Task Hooks
189+
190+
- `DependsOnTargets`
191+
192+
### Custom Task
193+
194+
MSBuild tasks are defined in certain language like csharp. You can implement one or some as nuget package.
195+
Or you can implement one using [inline task](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-inline-tasks?view=vs-2022#the-structure-of-an-inline-task) directly within the config file.
196+
197+
> [!NOTE]
198+
> See: [Task Writing](https://learn.microsoft.com/en-us/visualstudio/msbuild/task-writing?view=vs-2022)
199+
200+
### Generating Items from Tasks
201+
202+
## Importing
203+
204+
- `*.props` should be imported in early stage
205+
- `*.targets`: should be imported in build stage
206+
207+
## Evaluation Order
208+
209+
MSBuild files are order sensitive, order matters when properties and items may dependent on each other.
210+
211+
212+
1. environment variables: they're stored as properties
213+
2. imports & properties: evaluated by their declaration order
214+
- so, the order between imports and properties matters if you inter-reference them on expression
215+
3. definition of items: how should item were filtered out and captured.
216+
4. items: execute the process to fetch items and their metadata
217+
5. inline tasks
218+
6. targets: as well as items inside targets
219+
220+
## Folder-Specific Config
221+
222+
`Directory.Build.props` and `Directory.Build.targets` are special config files that could be auto-imported by msbuild.
223+
Such file is a **template** rather than a static store for values, so the containing properties and tasks **could vary for each project**.
224+
MSBuild would search upward for each aforementioned config file **until one was found**, it doesn't stop on solution root until it reaches the **drive root**
225+
226+
```xml
227+
<!-- Directory.Build.props at solution root -->
228+
<Project>
229+
<PropertyGroup>
230+
<!-- MSBuildProjectName varies for each project -->
231+
<!-- so it's not static even as a property -->
232+
<OutDir>C:\output\$(MSBuildProjectName)</OutDir>
233+
</PropertyGroup>
234+
</Project>
235+
```
236+
237+
`Directory.Build.props` is imported early in `Microsoft.Common.props` which is the default config for sdk-style projects, so properties in `Directory.Build.props` should not be dependent on other
238+
239+
> [!TIP]
240+
> - use `dotnet new buildprops` to create `Directory.Build.props`
241+
> - use `dotnet new buildtargets` to create `Directory.Build.targets`
242+
243+
244+
## MSBuild CLI
245+
246+
MSBuild cli was wrapped as `dotnet msbuild [-options]`
247+
248+
- `-p:<prop>=<value>`: override a property value(namely global property)
249+
- `-t:<target>`: trigger a target(and its dependent hooks)

0 commit comments

Comments
 (0)