Skip to content

Commit 63e1cbf

Browse files
baronfelbaronfel
authored
Add help documentation to repo (#80)
* prevent Nerdbank from flowing through package dependencies * add package README and detailed help docs
1 parent ef188e8 commit 63e1cbf

File tree

5 files changed

+128
-2
lines changed

5 files changed

+128
-2
lines changed

‎Directory.Build.props

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<Project>
22
<ItemGroup>
3-
<PackageReference Include="Microsoft.VisualStudioEng.MicroBuild.Core" />
4-
<PackageReference Include="Nerdbank.GitVersioning" />
3+
<PackageReference Include="Nerdbank.GitVersioning" PrivateAssets="all" IncludeAssets="build; buildMultitargeting" />
4+
<PackageReference Include="Microsoft.VisualStudioEng.MicroBuild.Core" PrivateAssets="all" />
55
</ItemGroup>
66
</Project>

‎Microsoft.NET.Build.Containers/Microsoft.NET.Build.Containers.csproj

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
<RepositoryUrl>https://github.com/rainersigwald/containers</RepositoryUrl>
2929
<RepositoryType>git</RepositoryType>
3030
<PackageTags>containers;docker;Microsoft.NET.Build.Containers</PackageTags>
31+
<PackageReadmeFile>README.md</PackageReadmeFile>
3132
</PropertyGroup>
3233

3334
<ItemGroup>
@@ -37,6 +38,7 @@
3738
<ItemGroup>
3839
<Content Include="build\Microsoft.NET.Build.Containers.props" Pack="true" PackagePath="build\" />
3940
<Content Include="build\Microsoft.NET.Build.Containers.targets" Pack="true" PackagePath="build\" />
41+
<Content Include="README.md" Pack="true" PackagePath="" />
4042
</ItemGroup>
4143

4244
<!-- This target adds all of our PackageReference and ProjectReference's runtime assets to our package output. -->

‎Microsoft.NET.Build.Containers/README.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# .NET SDK Containers
2+
3+
This package lets you build container images from your projects with a single command.
4+
5+
## Getting Started
6+
7+
To build a container from the SDK, add this package and run the `publish` command,
8+
specifying the `DefaultContainer` PublishProfile. You can learn more about Publish Profiles [in the documentation](https://docs.microsoft.com/aspnet/core/host-and-deploy/visual-studio-publish-profiles?view=aspnetcore-6.0#publish-profiles).
9+
10+
```shell
11+
>dotnet add package Microsoft.NET.Build.Containers --prerelease
12+
>dotnet publish --os linux --arch x64 -p:ProfileName=DefaultContainer
13+
...
14+
Pushed container '<your app name>:<your app version>' to registry 'docker://'
15+
...
16+
```
17+
18+
Out of the box, this package will infer a number of properties about the generated container image, including which base image to use, which version of that image to use, and where to push the generated image. You have control over all of these properties, however. You can read more about these customizations [here](https://aka.ms/dotnet/containers/customization).
19+
20+
**Note**: This package only supports Linux containers in this version.

‎docs/ContainerCustomization.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Customizing your container
2+
3+
You can control many aspects of the generated container through MSBuild properties. In general, if you could use a command in a Dockerfile to set some configuration, you can do the same via MSBuild.
4+
5+
> **Note**
6+
> The only exception to this is `RUN` commands - due to the way we build containers, those cannot be emulated. If you need this functionality, you will need to use a Dockerfile to build your container images.
7+
8+
> **Note**
9+
> This package only supports Linux containers in this version.
10+
11+
## ContainerBaseImage
12+
13+
This property controls the image used as the basis for your image. By default, we will infer the following values for you based on the properties of your project:
14+
15+
* if your project is self-contained, we use the `mcr.microsoft.com/dotnet/runtime-deps` image as the base image
16+
* if your project is an ASP.NET Core project, we use the `mcr.microsoft.com/dotnet/aspnet` image as the base image
17+
* otherwise we use the `mcr.microsoft.com/dotnet/runtime` image as the base image
18+
19+
We infer the tag of the image to be the numeric component of your chosen `TargetFramework` - so a `.net6.0` project will use the `6.0` tag of the inferred base image, a `.net7.0-linux` project will use the `7.0` tag, and so on.
20+
21+
If you set a value here, you should set the fully-qualified name of the image to use as the base, including any tag you prefer:
22+
23+
```xml
24+
<ContainerBaseImage>mcr.microsoft.com/dotnet/runtime:6.0</ContainerBaseImage>
25+
```
26+
27+
## ContainerRegistry
28+
29+
This property controls the destination registry - the place that the newly-created image will be pushed to.
30+
31+
Be default, we push to the local Docker daemon (annotated by `docker://`), but for this release you can specify any _unauthenticated_ registry. For example:
32+
33+
```xml
34+
<ContainerRegistry>registry.mycorp.com:1234</ContainerRegistry>
35+
```
36+
37+
> **Note**
38+
> There is no authentication currently supported - that [will come in a future release](https://github.com/rainersigwald/containers/issues/70) - so make sure you're pointing to an unauthenticated registry
39+
40+
## ContainerImageName
41+
42+
This property controls the name of the image itself, e.g `dotnet/runtime` or `my-awesome-app`.
43+
44+
By default, the value used will be the `AssemblyName` of the project.
45+
46+
47+
```xml
48+
<ContainerImageName>my-super-awesome-app</ContainerImageName>
49+
```
50+
51+
> **Note**
52+
> Image names can only contain lowercase alphanumeric characters, periods, underscores, and dashes, and must start with a letter or number - any other characters will result in an error being thrown.
53+
54+
## ContainerImageTag
55+
56+
This property controls the tag that is generated for the image. Tags are often used to refer to different versions of an application, but they can also refer to different operating system distributions, or even just different baked-in configuration.
57+
58+
By default, the value used will be the `Version` of the project.
59+
60+
```xml
61+
<ContainerImageTag>1.2.3-alpha2</ContainerImageTag>
62+
```
63+
64+
> **Note**
65+
> Tags can only contain up to 127 alphanumeric characters, periods, underscores, and dashes. They must start with an alphanumeric character or an underscore. Any other form will result in an error being thrown.
66+
67+
## ContainerWorkingDirectory
68+
69+
This property controls the working directory of the container - the directory that commands are executed within if not other command is run.
70+
71+
By default, we use the `/app` directory as the working directory.
72+
73+
```xml
74+
<ContainerWorkingDirectory>/bin</ContainerWorkingDirectory>
75+
```
76+
77+
## Unsupported properties
78+
79+
There are many other properties and items that we want to add support for in subsequent previews:
80+
81+
* Entrypoints
82+
* Entrypoint Arguments
83+
* Ports
84+
* Environment Variables
85+
* Labels
86+
87+
We expect to add them in future versions, so watch this space!

‎docs/GettingStarted.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Getting Started
2+
3+
To build a container from the SDK, add this package and run the `publish` command,
4+
specifying the `DefaultContainer` PublishProfile. You can learn more about Publish Profiles [in the documentation](https://docs.microsoft.com/aspnet/core/host-and-deploy/visual-studio-publish-profiles?view=aspnetcore-6.0#publish-profiles).
5+
6+
```shell
7+
>dotnet add package Microsoft.NET.Build.Containers --prerelease
8+
>dotnet publish --os linux --arch x64 -p:ProfileName=DefaultContainer
9+
...
10+
Pushed container '<your app name>:<your app version>' to registry 'docker://'
11+
...
12+
```
13+
14+
Out of the box, this package will infer a number of properties about the generated container image, including which base image to use, which version of that image to use, and where to push the generated image. You have control over all of these properties, however. You can read more about customizing the container [here](./ContainerCustomization.md)
15+
16+
> **Note**
17+
> This package only supports Linux containers in this version.

0 commit comments

Comments
 (0)