Skip to content

Latest commit

 

History

History
121 lines (87 loc) · 7.08 KB

DevelopmentDocumentation.md

File metadata and controls

121 lines (87 loc) · 7.08 KB
Raw

Development guide

Implementation details

The source code for the project is stored in dotnet/sdk repo.

It contains the following projects:

Project Description
Microsoft.NET.Build.Containers The project contains MSBuild tasks for publishing .NET containers.
containerize .NET CLI app used for container publishing from .NET Framework environment (as Visual Studio).
packaging The project contains MSBuild targets and used for packaging the project to NuGet package.

Microsoft.NET.Build.Containers contains the following tasks:

  • CreateNewImage - creates the container image (note different implementation for .NET Framework).
  • ComputeDotnetBaseImageTag - computes the base image Tag for a Microsoft-authored container image based on the tagging scheme from various SDK versions.
  • ParseContainerProperties - parses certain container properties: base image name, container registry, container image name, image tags.

To simplify the work in dotnet/sdk repo, there is the containers solution filter. It loads all the projects needed. Please note the details for working with dotnet/sdk repo:

  • the project should be build using command-line build scripts (build.cmd/build.sh)
  • before opening solution/solution filter in Visual Studio artifacts\sdk-build-env.bat and eng\dogfood.cmd should be run.

Insertion to Microsoft.NET.Sdk.Publish

The container targets are inserted to Microsoft.NET.Sdk.Publish. Main insertions points are:

Required artifacts are included to .NET SDK.

Error messages

All error messages should have a dedicated code starting from CONTAINER. The output from containerize should comply with MSBuild canonical format. All non-debug output should be localized.

Use cases

.NET SDK / dotnet publish

  • for web project:
>dotnet publish --os linux --arch x64 -c Release /p:PublishProfile=DefaultContainer
...
Pushed container '<your app name>:<your app version>' to registry 'docker://'
...
  • for non-web project:
>dotnet publish --os linux --arch x64 -c Release /t:PublishContainer
...
Pushed container '<your app name>:<your app version>' to registry 'docker://'
...

Visual Studio

It is possible to publish both web project and non-web project using Publish dialog. See the details in the article.

Note: Visual Studio is using .NET Framework version of .NET containers MSBuild task.

Automated and manual tests

Automated tests

The following automated tests are available:

Note: if docker is not detected, majority of integration tests will be skipped due to custom fact and theory attributes.

All the integration tests are run for linux containers. The integration tests are covering only .NET SDK use cases.

sdk-container-demo

This is the testing project run by @baronfel. It runs full end-to-end tests to well-known registries. The tests are covering only .NET SDK use case for web application. The tests are run once a day.

Manual tests

The following scenarios are not covered by automated tests and should be checked manually:

  • publishing of web project in Visual Studio
  • publishing of non-web project in Visual Studio
  • publishing windows container (details TBD)

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.

Release cadence

Starting .NET SDK 7.0.300, the artifacts are released together with .NET SDK. Microsoft.NET.Build.Containers NuGet package is released to nuget.org at the day of .NET SDK release. Versioning matches .NET SDK version.

Note: Microsoft.NET.Build.Containers NuGet package will be deprecated soon, potentially with .NET 8. It is planned that functionality is fully available from .NET SDK since then. 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). 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.

Short and long term vision for the project

See #428 for details.

Troubleshooting

Troubleshooting issues in VS.

MSBuild binlog may be used to see if PublishContainer target was run. In case it was run, likely containerize app was launched by CreateNewImage task. The command that was run is logged in Build Output window.

To troubleshoot the issues, you may want to run this command from CLI - it provides more output. If needed it can be also debugged.

Resources