Skip to content

Commit 80c428f

Browse files
baronfelbaronfel
authored
Merge pull request #426 from vlada-shubina/dev-doc
Updated development documentation
2 parents 8f00d24 + 9e6325e commit 80c428f

File tree

3 files changed

+123
-9
lines changed

3 files changed

+123
-9
lines changed

‎DEVGUIDE.md‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ For easiness, please use [containers.slnf](https://github.com/dotnet/sdk/blob/ma
3333
If you would like to contribute by creating a pull request, please refer to [dotnet/sdk contributing guide](https://github.com/dotnet/sdk#how-do-i-engage-and-contribute).
3434
Ideally, prior starting the effort find a corresponding issue in [this repo](https://github.com/dotnet/sdk-container-builds/issues) and let us and others know in a comment. If you plan to address the problem that is not reflected in any issue, please create one. Consider helping us triaging the pull request by adding 'Area-Containers' repo.
3535

36+
Development documentation is available [here](./docs/DevelopmentDocumentation.md)
37+
3638
## License
3739

3840
This project is licensed with the [MIT license](LICENSE).

‎docs/DevelopmentDocumentation.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Development guide
2+
3+
## Implementation details
4+
5+
The source code for the project is stored in [dotnet/sdk](https://github.com/dotnet/sdk/tree/main/src/Containers) repo.
6+
7+
It contains the following projects:
8+
|Project|Description|
9+
|---|---|
10+
|[`Microsoft.NET.Build.Containers`](https://github.com/dotnet/sdk/tree/main/src/Containers/Microsoft.NET.Build.Containers)|The project contains MSBuild tasks for publishing .NET containers.|
11+
|[`containerize`](https://github.com/dotnet/sdk/tree/main/src/Containers/containerize)|.NET CLI app used for container publishing from .NET Framework environment (as Visual Studio).|
12+
|[`packaging`](https://github.com/dotnet/sdk/tree/main/src/Containers/packaging)|The project contains MSBuild targets and used for packaging the project to NuGet package.|
13+
14+
`Microsoft.NET.Build.Containers` contains the following tasks:
15+
- [`CreateNewImage`](https://github.com/dotnet/sdk/blob/main/src/Containers/Microsoft.NET.Build.Containers/Tasks/CreateNewImage.cs) - creates the container image (note different implementation for .NET Framework).
16+
- [`ComputeDotnetBaseImageTag`](https://github.com/dotnet/sdk/blob/main/src/Containers/Microsoft.NET.Build.Containers/Tasks/ComputeDotnetBaseImageTag.cs) - computes the base image Tag for a Microsoft-authored container image based on the tagging scheme from various SDK versions.
17+
- [`ParseContainerProperties`](https://github.com/dotnet/sdk/blob/main/src/Containers/Microsoft.NET.Build.Containers/Tasks/ParseContainerProperties.cs) - parses certain container properties: base image name, container registry, container image name, image tags.
18+
19+
To simplify the work in dotnet/sdk repo, there is the [containers](https://github.com/dotnet/sdk/blob/main/containers.slnf) solution filter. It loads all the projects needed.
20+
Please note the [details](https://github.com/dotnet/sdk/blob/main/documentation/project-docs/developer-guide.md) for working with dotnet/sdk repo:
21+
- the project should be build using command-line build scripts (build.cmd/build.sh)
22+
- before opening solution/solution filter in Visual Studio `artifacts\sdk-build-env.bat` and `eng\dogfood.cmd` should be run.
23+
24+
### Insertion to `Microsoft.NET.Sdk.Publish`
25+
26+
The container targets are inserted to `Microsoft.NET.Sdk.Publish`.
27+
Main insertions points are:
28+
- [`Microsoft.NET.Sdk.Publish.props`](TBD)
29+
- [`Microsoft.NET.Sdk.Publish.targets`](TBD)
30+
31+
Required artifacts are [included](TBD) to .NET SDK.
32+
33+
### Error messages
34+
35+
All error messages should have a dedicated code starting from `CONTAINER`.
36+
The output from `containerize` should comply with [MSBuild canonical format](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-diagnostic-format-for-tasks?view=vs-2022).
37+
All non-debug output should be localized.
38+
39+
## Use cases
40+
41+
### .NET SDK / `dotnet publish`
42+
43+
- for web project:
44+
```shell
45+
>dotnet publish --os linux --arch x64 -c Release /p:PublishProfile=DefaultContainer
46+
...
47+
Pushed container '<your app name>:<your app version>' to registry 'docker://'
48+
...
49+
```
50+
51+
- for non-web project:
52+
```shell
53+
>dotnet publish --os linux --arch x64 -c Release /t:PublishContainer
54+
...
55+
Pushed container '<your app name>:<your app version>' to registry 'docker://'
56+
...
57+
```
58+
59+
### Visual Studio
60+
61+
It is possible to publish both web project and non-web project using `Publish` dialog.
62+
See the details in [the article](https://learn.microsoft.com/en-us/visualstudio/containers/deploy-containerized?view=vs-2022).
63+
64+
Note: Visual Studio is using .NET Framework version of .NET containers MSBuild task.
65+
66+
## Automated and manual tests
67+
68+
### Automated tests
69+
The following automated tests are available:
70+
- [`containerize.UnitTests`](https://github.com/dotnet/sdk/tree/main/src/Tests/containerize.UnitTests) - contains unit tests for `containerize`.
71+
- [`Microsoft.NET.Build.Containers.UnitTests`](https://github.com/dotnet/sdk/tree/main/src/Tests/Microsoft.NET.Build.Containers.UnitTests) - contains unit tests for `Microsoft.NET.Build.Containers`.
72+
- [`Microsoft.NET.Build.Containers.IntegrationTests`](https://github.com/dotnet/sdk/tree/main/src/Tests/Microsoft.NET.Build.Containers.IntegrationTests) - contains integration tests for `Microsoft.NET.Build.Containers`. Majority of integration tests requires `docker` to be installed. On CI they run on `Ubuntu` only. It is possible to run those tests in Windows environment if Docker Desktop is installed.
73+
74+
Note: if `docker` is not detected, majority of integration tests will be skipped due to custom [fact and theory attributes](https://github.com/dotnet/sdk/blob/main/src/Tests/Microsoft.NET.Build.Containers.UnitTests/DockerDaemonAvailableUtils.cs).
75+
76+
All the integration tests are run for `linux` containers. The integration tests are covering only .NET SDK use cases.
77+
78+
#### [sdk-container-demo](https://github.com/baronfel/sdk-container-demo)
79+
80+
This is the testing project run by @baronfel.
81+
It runs full end-to-end tests to well-known registries. The tests are covering only .NET SDK use case for web application.
82+
The tests are run once a day.
83+
84+
### Manual tests
85+
86+
The following scenarios are not covered by automated tests and should be checked manually:
87+
- publishing of web project in Visual Studio
88+
- publishing of non-web project in Visual Studio
89+
- publishing windows container (details TBD)
90+
91+
To test new build of dotnet/sdk repo in VS, ensure that `eng\dogfood.cmd` is run before. This script configures the environment to use `dotnet` from build artifacts folder.
92+
93+
## Release cadence
94+
95+
Starting .NET SDK 7.0.300, the artifacts are released together with .NET SDK.
96+
`Microsoft.NET.Build.Containers` NuGet package is released to nuget.org at the day of .NET SDK release. Versioning matches .NET SDK version.
97+
98+
Note: `Microsoft.NET.Build.Containers` NuGet package will be deprecated soon, potentially with .NET 8.
99+
It is planned that functionality is fully available from .NET SDK since then.
100+
For web projects, package reference to `Microsoft.NET.Build.Containers` is already not needed as targets are available from `Microsoft.NET.Sdk.Publish`. In case the package reference is added, the warning appears during publishing (starting .NET SDK 7.0.400).
101+
For non-web projects, as of .NET SDK 7.0.300 package reference to NuGet package is still needed, but we are working towards simplifying that.
102+
103+
## Short and long term vision for the project
104+
See https://github.com/dotnet/sdk-container-builds/issues/428 for details.
105+
106+
## Troubleshooting
107+
108+
### Troubleshooting issues in VS.
109+
MSBuild binlog may be used to see if `PublishContainer` target was run.
110+
In case it was run, likely `containerize` app was launched by `CreateNewImage` task.
111+
The command that was run is logged in Build Output window.
112+
113+
To troubleshoot the issues, you may want to run this command from CLI - it provides more output.
114+
If needed it can be also debugged.
115+
116+
## Resources
117+
* [Tutorial: Containerize a .NET app with dotnet publish](https://learn.microsoft.com/en-us/dotnet/core/docker/publish-as-container)
118+
* [Release notes](https://github.com/dotnet/sdk/tree/main/src/Containers/docs/ReleaseNotes)
119+
* [OCI Image Format spec](https://github.com/opencontainers/image-spec/blob/main/spec.md)
120+
* [Docker Registry API docs](https://docs.docker.com/registry/spec/api/)
121+
* [Setting up a local Docker registry](https://docs.docker.com/registry/)

0 commit comments

Comments
 (0)