Add usage samples

[Kralizek]

Examples of using the ensure-unique tool.

• Sample for .NET Core app
• Sample for .NET Framework app

Fixes #5

[Kralizek]

Right now I'm using dotnet/core/sdk image also in production because dotnet/core/runtime does not support dotnet tool.

I'll try to implement something from this article to use dotnet/core/runtime

[Kralizek]

So, the .NET Framework is a bit more complicated because the tool I created needs the .NET Core runtime to run. Furthermore so, the dotnet <tool> syntax is only supported when the SDK is installed, the runtime alone won't do. Note that dotnet/framework/sdk has the .NET Core SDK installed.

Here are two options:

Option 1

# escape=`

# BUILDER
FROM mcr.microsoft.com/dotnet/framework/sdk:4.8 as build
WORKDIR /src
COPY src/ ./
RUN dotnet restore ConsoleApp/ConsoleApp.csproj
RUN dotnet publish ConsoleApp/ConsoleApp.csproj -c Release -o /out

# TOOLS
FROM mcr.microsoft.com/dotnet/framework/sdk:4.8 as tools
RUN dotnet tool install EMG.Tools.EnsureUnique --tool-path C:\tools

# RUNNER
FROM mcr.microsoft.com/dotnet/framework/runtime:4.8 AS runtime
ADD https://dotnet.microsoft.com/download/dotnet-core/scripts/v1/dotnet-install.ps1 C:\temp\
RUN powershell C:\temp\dotnet-install.ps1 -Channel LTS -Runtime dotnet -InstallDir C:\dotnet
ARG DOTNET_PATH=C:\dotnet\
ARG DOTNET_TOOLS_PATH=C:\tools\
RUN SETX DOTNET_ROOT %DOTNET_PATH%
RUN SETX PATH %PATH%;%DOTNET_PATH%;%DOTNET_TOOLS_PATH%
ENV DotNetEnsureUnique__S3__BucketName= `
    DotNetEnsureUnique__S3__FilePrefix= `
    DOTNET_CLI_TELEMETRY_OPTOUT=1
COPY --from=tools C:\tools\ C:\tools\
WORKDIR /app
COPY --from=build /out .
ENTRYPOINT ["dotnet-ensure-unique", "exe", "ConsoleApp.exe"]

Option 1 in pills

• a distinct container (labeled tools) to fetch and install the tool in a well-known folder (C:\tools)
  • the image could be extracted and reused everywhere.
• the runtime container is built:
  • the .NET Core runtime is installed in a well-known folder (C:\dotnet\)
  • the folder is added to the PATH and to DOTNET_ROOT
  • the tools folder is added to the PATH
  • I copy the relevant folders from the tools and the builder containers
  • the entrypoint uses the full exe name of the tool (dotnet-ensure-unique)
• Shared size: 5.27 GB
• Unique size: 113 MB

Option 2

# escape=`

# BUILDER
FROM mcr.microsoft.com/dotnet/framework/sdk:4.8 as build
WORKDIR /src
COPY src/ ./
RUN dotnet restore ConsoleApp/ConsoleApp.csproj
RUN dotnet publish ConsoleApp/ConsoleApp.csproj -c Release -o /out

# RUNNER
FROM mcr.microsoft.com/dotnet/framework/runtime:4.8 AS runtime
ADD https://dotnet.microsoft.com/download/dotnet-core/scripts/v1/dotnet-install.ps1 C:\temp\
ARG DOTNET_PATH=C:\dotnet\
RUN powershell C:\temp\dotnet-install.ps1 -Channel LTS -InstallDir %DOTNET_PATH%
RUN SETX DOTNET_ROOT %DOTNET_PATH%
RUN SETX PATH %PATH%;%DOTNET_PATH%
ENV DotNetEnsureUnique__S3__BucketName= `
    DotNetEnsureUnique__S3__FilePrefix= `
    DOTNET_CLI_TELEMETRY_OPTOUT=1
RUN dotnet tool install -g EMG.Tools.EnsureUnique
WORKDIR /app
COPY --from=build /out .
ENTRYPOINT ["dotnet", "ensure-unique", "exe", "ConsoleApp.exe"]

Option 2 in pills:

• No distinct container for installing the tool
• the runtime container is built:
  • the .NET Core SDK is installed in a well-known folder (C:\dotnet\)
  • the folder is added to the PATH and to DOTNET_ROOT
  • the tool is installed globally
  • I copy the relevant folders from the builder container
  • the entrypoint uses the idiomatic syntax for using tools (dotnet ensure-unique)
• Shared size: 5.80 GB
• Unique size: 529 MB

Personally, I'd go for Option 1, even if using dotnet-ensure-unique annoys me a lot.

[Kralizek]

Running the containers:

The .NET Core and the .NET Framework containers can be run at the same time.

Using environmental variables

PS> docker run --rm -e DotNetEnsureUnique__S3__BucketName=my-bucket-name -e DotNetEnsureUnique__S3__FilePrefix=apps/console console-sample

Using parameters

PS> docker run --rm console-sample --bucket my-bucket-name --prefix apps/console

Local execution

To use the container locally, you can mount the .aws folder in the %USERPROFILE% folder (e.g. C:\Users\your.user\.aws).

This can be done by adding the following to the command: -v C:\Users\your.user\.aws\:C:\Users\ContainerAdministrator\.aws

[Kralizek]

@McDoit @simgu I welcome your opinion on this comment

[McDoit]

Personally, I'd go for Option 1, even if using dotnet-ensure-unique annoys me a lot.

Yeah i would go for option 1, BUT, maybe put the runtime/tools part into its own (public) image and just reference that one?

[Kralizek]

@McDoit you don't need to quote the whole message every time 😜 (I edited your comment removing the giga-quote)

We can definitely make a public image for the tool but in terms of dockerfile you wouldn't spare much. Also, it would be kind of a magic trick to use a COPY from a public image to get the binaries of the tool.

[simgu]

I vote for number 1 as well

[McDoit]

@Kralizek Was thinking to put the tools part in a image:

# escape=`

# TOOLS
FROM mcr.microsoft.com/dotnet/framework/sdk:4.8 as tools
RUN dotnet tool install EMG.Tools.EnsureUnique --tool-path C:\tools

# RUNNER
FROM mcr.microsoft.com/dotnet/framework/runtime:4.8 AS runtime
ADD https://dotnet.microsoft.com/download/dotnet-core/scripts/v1/dotnet-install.ps1 C:\temp\
RUN powershell C:\temp\dotnet-install.ps1 -Channel LTS -Runtime dotnet -InstallDir C:\dotnet
ARG DOTNET_PATH=C:\dotnet\
ARG DOTNET_TOOLS_PATH=C:\tools\
RUN SETX DOTNET_ROOT %DOTNET_PATH%
RUN SETX PATH %PATH%;%DOTNET_PATH%;%DOTNET_TOOLS_PATH%
ENV DotNetEnsureUnique__S3__BucketName= `
    DotNetEnsureUnique__S3__FilePrefix= `
    DOTNET_CLI_TELEMETRY_OPTOUT=1
COPY --from=tools C:\tools\ C:\tools\

and then this in the app dockerfile:

# escape=`

# BUILDER
FROM mcr.microsoft.com/dotnet/framework/sdk:4.8 as build
WORKDIR /src
COPY src/ ./
RUN dotnet restore ConsoleApp/ConsoleApp.csproj
RUN dotnet publish ConsoleApp/ConsoleApp.csproj -c Release -o /out

# RUNNER
FROM tools-image/framework:4.8
WORKDIR /app
COPY --from=build /out .
ENTRYPOINT ["dotnet", "ensure-unique", "exe", "ConsoleApp.exe"]

[Kralizek]

I'd make a difference between a conceptual sample and (like in this PR) and the operative best practices (that could be shown in a different sample).

Also, docker is changing their policy and limits for pulling images from docker hub.

https://www.docker.com/blog/what-you-need-to-know-about-upcoming-docker-hub-rate-limiting/#:~:text=The%20limits%20will%20be%20gradually,are%20exempt%20from%20rate%20limiting.