Skip to content

Freshness for May #54091

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
adegeo wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Freshness for May #54091

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fd3e5a7
Freshness for May
adegeo May 28, 2026
d22b390
Feedback
adegeo May 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 24 additions & 18 deletions docs/core/additional-tools/self-signed-certificates-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@
title: Generate Self-Signed Certificates Overview
description: An overview of the dotnet dev-certs tool that adds functionality for .NET and ASP.NET Core projects, and other options for using self-signed certificates.
author: angee
ms.date: 12/06/2021
ms.date: 05/27/2026
ms.custom: sfi-ropc-nochange
---

# Generate self-signed certificates with the .NET CLI

There are different ways to create and use self-signed certificates for development and testing scenarios. This article covers using self-signed certificates with `dotnet dev-certs`, and other options like `PowerShell` and `OpenSSL`.

You can then validate that the certificate will load using an example such as an [ASP.NET Core app](https://github.com/dotnet/dotnet-docker/blob/main/samples/run-aspnetcore-https-development.md) hosted in a container.
You can then validate that the certificate loads using an example such as an [ASP.NET Core app](https://github.com/dotnet/dotnet-docker/blob/main/samples/run-aspnetcore-https-development.md) hosted in a container.

## Prerequisites

Expand All @@ -20,21 +20,21 @@ For `dotnet dev-certs`, be sure to have the appropriate version of .NET installe
* [Install .NET on Linux](../install/linux.md)
* [Install .NET on macOS](../install/macos.md)

This sample requires [Docker 17.06](https://docs.docker.com/release-notes/docker-ce) or later of the [Docker client](https://www.docker.com/products/docker).
This sample requires the [Docker client](https://www.docker.com/products/docker).

## Prepare sample app

For this guide, you'll use a [sample app](https://hub.docker.com/_/microsoft-dotnet-samples) and make changes where appropriate.
For this guide, you'll use a [sample app](https://hub.docker.com/r/microsoft/dotnet-samples) and make changes where appropriate.

Check that the sample app [Dockerfile](https://github.com/dotnet/dotnet-docker/blob/main/samples/aspnetapp/Dockerfile) is using .NET 8.
Check that the sample app [Dockerfile](https://github.com/dotnet/dotnet-docker/blob/main/samples/aspnetapp/Dockerfile) is using .NET 10.

Depending on the host OS, you might need to update the ASP.NET runtime. For example, to target the appropriate Windows runtime, change `mcr.microsoft.com/dotnet/aspnet:8.0-nanoservercore-2009 AS runtime` to `mcr.microsoft.com/dotnet/aspnet:8.0-windowsservercore-ltsc2022 AS runtime` in the Dockerfile.
Depending on the host OS, you might need to update the ASP.NET runtime. For example, to target the appropriate Windows runtime, change `mcr.microsoft.com/dotnet/aspnet:10.0-nanoservercore-2009 AS runtime` to `mcr.microsoft.com/dotnet/aspnet:10.0-windowsservercore-ltsc2022 AS runtime` in the Dockerfile.

For example, this will help with testing the certificates on Windows:

```Dockerfile
# https://hub.docker.com/_/microsoft-dotnet
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
# https://github.com/dotnet/dotnet-docker/blob/main/README.sdk.md
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /source

# copy csproj and restore as distinct layers
Expand All @@ -48,7 +48,7 @@ WORKDIR /source/aspnetapp
RUN dotnet publish -c release -o /app -r win-x64 --self-contained false --no-restore

# final stage/image
FROM mcr.microsoft.com/dotnet/aspnet:8.0-windowsservercore-ltsc2022 AS runtime
FROM mcr.microsoft.com/dotnet/aspnet:10.0-windowsservercore-ltsc2022 AS runtime
WORKDIR /app
COPY --from=build /app ./
ENTRYPOINT ["aspnetapp"]
Expand All @@ -62,7 +62,7 @@ Make sure the `aspnetapp.csproj` includes the appropriate target framework:
<Project Sdk="Microsoft.NET.Sdk.Web">

<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
<TargetFramework>net10.0</TargetFramework>
<!--Other Properties-->
</PropertyGroup>

Expand Down Expand Up @@ -97,22 +97,28 @@ You can create a self-signed certificate:
You can use `dotnet dev-certs` to work with self-signed certificates.

```powershell
dotnet dev-certs https -ep $env:USERPROFILE\.aspnet\https\aspnetapp.pfx -p crypticpassword
dotnet dev-certs https -ep $env:USERPROFILE\.aspnet\https\aspnetapp.pfx -p $CREDENTIAL_PLACEHOLDER$
dotnet dev-certs https --trust
```

> [!NOTE]
> The certificate name, in this case *aspnetapp*.pfx, must match the project assembly name. `crypticpassword` is used as a stand-in for a password of your own choosing. If console returns "A valid HTTPS certificate is already present.", a trusted certificate already exists in your store. It can be exported using MMC Console.
> The certificate name, in this case *aspnetapp*.pfx, must match the project assembly name. `$CREDENTIAL_PLACEHOLDER$` represents a password of your own choosing. If the console returns "A valid HTTPS certificate is already present.", a trusted certificate already exists in your store. You can export it using the MMC Console.
>
> In .NET 10 and later, if you run `dotnet dev-certs https --trust` inside a Windows Subsystem for Linux (WSL) instance, the command also trusts the certificate on the Windows host.
>
> In .NET 10 and later, the generated certificate includes subject alternative names (SANs) for `host.docker.internal` and `host.containers.internal`, which lets you use the certificate directly in container-based local development scenarios without extra configuration.
>
> To verify that a trusted development certificate is present, run `dotnet dev-certs https --check --trust`.

Configure application secrets, for the certificate:

```console
dotnet user-secrets -p aspnetapp\aspnetapp.csproj init
dotnet user-secrets -p aspnetapp\aspnetapp.csproj set "Kestrel:Certificates:Development:Password" "crypticpassword"
dotnet user-secrets -p aspnetapp\aspnetapp.csproj set "Kestrel:Certificates:Development:Password" "$CREDENTIAL_PLACEHOLDER$"
```

> [!NOTE]
> Note: The password must match the password used for the certificate.
> The password must match the password used for the certificate.

Run the container image with ASP.NET Core configured for HTTPS:

Expand Down Expand Up @@ -143,7 +149,7 @@ The certificate will be generated, but for the purposes of testing, should be pl

```powershell
$certKeyPath = "c:\certs\contoso.com.pfx"
$password = ConvertTo-SecureString 'password' -AsPlainText -Force
$password = ConvertTo-SecureString '$CREDENTIAL_PLACEHOLDER$' -AsPlainText -Force
$cert | Export-PfxCertificate -FilePath $certKeyPath -Password $password
$rootCert = $(Import-PfxCertificate -FilePath $certKeyPath -CertStoreLocation 'Cert:\LocalMachine\Root' -Password $password)
```
Expand All @@ -153,16 +159,16 @@ At this point, the certificates should be viewable from an [MMC snap-in](../../f
You can run the sample container in Windows Subsystem for Linux (WSL):

```console
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORT=8001 -e ASPNETCORE_ENVIRONMENT=Development -e ASPNETCORE_Kestrel__Certificates__Default__Password="password" -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/contoso.com.pfx -v /c/certs:/https/ mcr.microsoft.com/dotnet/samples:aspnetapp
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORT=8001 -e ASPNETCORE_ENVIRONMENT=Development -e ASPNETCORE_Kestrel__Certificates__Default__Password="$CREDENTIAL_PLACEHOLDER$" -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/contoso.com.pfx -v /c/certs:/https/ mcr.microsoft.com/dotnet/samples:aspnetapp
```

> [!NOTE]
> Note that with the volume mount, the file path could be handled differently based on host. For example, in WSL you might replace */c/certs* with */mnt/c/certs*.
> With the volume mount, the file path could be handled differently based on host. For example, in WSL you might replace */c/certs* with */mnt/c/certs*.

If you're using the container built earlier for Windows, the run command would look like the following:

```console
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORT=8001 -e ASPNETCORE_ENVIRONMENT=Development -e ASPNETCORE_Kestrel__Certificates__Default__Password="password" -e ASPNETCORE_Kestrel__Certificates__Default__Path=c:\https\contoso.com.pfx -v c:\certs:C:\https aspnetapp:my-sample
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORT=8001 -e ASPNETCORE_ENVIRONMENT=Development -e ASPNETCORE_Kestrel__Certificates__Default__Password="$CREDENTIAL_PLACEHOLDER$" -e ASPNETCORE_Kestrel__Certificates__Default__Path=c:\https\contoso.com.pfx -v c:\certs:C:\https aspnetapp:my-sample
```

Once the application is up, navigate to contoso.com:8001 in a browser.
Expand Down
112 changes: 68 additions & 44 deletions docs/core/additional-tools/uninstall-tool-cli-dry-run.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: dotnet-core-uninstall dry-run command
description: The dotnet-core-uninstall dry-run command simulates uninstalling the target .NET SDK or runtime. Status is reported for potential removal.
author: adegeo
ms.date: 08/04/2024
ms.date: 05/27/2026
zone_pivot_groups: operating-systems-set-three
---

Expand All @@ -22,89 +22,86 @@
::: zone pivot="os-windows"

```dotnetcli
dotnet-core-uninstall dry-run <TARGET> [--x64|--x86] <VERSION>...
[-v|--verbosity <LEVEL>] [--force]
dotnet-core-uninstall dry-run <TARGET> <FILTER> [-v|--verbosity <LEVEL>]
[--force] [-y|--yes]

dotnet-core-uninstall dry-run <TARGET> [--x64|--x86] <FILTER>
[-v|--verbosity <LEVEL>]

dotnet-core-uninstall dry-run -h|--help|-?
dotnet-core-uninstall dry-run -h|--help
```

::: zone-end

::: zone pivot="os-macos"

```dotnetcli
dotnet-core-uninstall dry-run <TARGET> <VERSION>...
[-v|--verbosity <LEVEL>] [--force] [-y|--yes]

dotnet-core-uninstall dry-run <TARGET> <FILTER>
[-v|--verbosity <LEVEL>] [--force] [-y|--yes]
dotnet-core-uninstall dry-run <TARGET> <FILTER> [-v|--verbosity <LEVEL>]
[--force] [-y|--yes] [--preserve-vs-for-mac-sdks]

dotnet-core-uninstall dry-run -h|--help|-?
dotnet-core-uninstall dry-run -h|--help
```

::: zone-end


Check failure on line 44 in docs/core/additional-tools/uninstall-tool-cli-dry-run.md

View workflow job for this annotation

GitHub Actions / lint

Multiple consecutive blank lines 

docs/core/additional-tools/uninstall-tool-cli-dry-run.md:44 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md012.md
## Description

The `dotnet-core-uninstall dry-run` command simulates .NET SDK and runtime removal. A status output is provided for each .NET SDK and runtime that would have been removed by the tool.

### Arguments

**`TARGET`**

The type you want to uninstall. Valid options are listed in the [Options - TARGET](#options---target) section.

**`VERSION`**

The version to uninstall. You can list several versions separated by a space. Response files are also supported.

> [!TIP]
> Response files are an alternative to placing all the versions on the command line. They're text files, typically with a *\*.rsp* extension, and each version is listed on a separate line. To specify a response file for the `VERSION` argument, use the \@ character immediately followed by the response file name.

**`FILTER`**

Specifies a value used to filter the `TARGET`. Valid options are listed in the [Options - FILTER](#options---filter) section.

## Options - TARGET

::: zone pivot="os-windows"

- **`--aspnet-runtime`**
Discovers all the ASP.NET Core runtimes that can be uninstalled with this tool.

Removes ASP.NET Core runtimes only.
Comment thread
adegeo marked this conversation as resolved.

- **`--hosting-bundle`**

Lists all the .NET hosting bundles that can be uninstalled with this tool.

::: zone-end
Removes .NET Core Runtime and Hosting Bundles only.

- **`--runtime`**

Lists all the .NET runtimes that can be uninstalled with this tool.
Removes .NET Core runtimes only.

- **`--sdk`**

Lists all the .NET SDKs that can be uninstalled with this tool.
Removes .NET Core SDKs only.

::: zone pivot="os-windows"
- **`--windows-desktop-runtime`**

- **`--x64`**
Removes Windows Desktop runtimes only.

Lists all the x64 .NET SDKs and runtimes that can be uninstalled with this tool.
- **`--arm64`**

> [!NOTE]
> If `--x64` or `--x86` isn't specified, then both x64 and x86 will be removed.
Use with `--sdk`, `--runtime`, `--aspnet-runtime`, and `--windows-desktop-runtime` to remove arm64.

- **`--x64`**

Use with `--sdk`, `--runtime`, `--aspnet-runtime`, and `--windows-desktop-runtime` to remove x64.

- **`--x86`**

Lists all the x86 .NET SDKs and runtimes that can be uninstalled with this tool.
Use with `--sdk`, `--runtime`, `--aspnet-runtime`, and `--windows-desktop-runtime` to remove x86.

> [!NOTE]
> If `--x64` or `--x86` isn't specified, then both x64 and x86 will be removed.
::: zone-end

::: zone pivot="os-macos"

- **`--runtime`**

Removes .NET Core runtimes only.

- **`--sdk`**

Removes .NET Core SDKs only.

::: zone-end

Expand Down Expand Up @@ -146,26 +143,56 @@

## Options

::: zone pivot="os-windows"

- **`--force`**

Forces removal of versions that might be used by Visual Studio.

::: zone-end

::: zone pivot="os-macos"

- **`--force`**

Forces removal of versions that might be used by Visual Studio for Mac or SDKs.

- **`--preserve-vs-for-mac-sdks`**

Prevents removal of SDKs and runtimes that have a high probability of being used by Visual Studio for Mac.

> [!NOTE]
> Visual Studio for Mac is out of support.

::: zone-end

- **`-v, --verbosity <LEVEL>`**

Sets the verbosity level. The default value is `normal`. Allowed values are:
Sets the verbosity level. Allowed values are:

- `q[uiet]`
- `m[inimal]`
- `n[ormal]`
- `d[etailed]`
- `diag[nostic]`.
- `diag[nostic]`

- **`-?|-h|--help`**

Shows help and usage information
Shows help and usage information.

::: zone pivot="os-windows"

> [!NOTE]
> By default, .NET SDKs and runtimes that might be required by Visual Studio or other SDKs aren't included in the `dotnet-core-uninstall dry-run` output. Also, depending on the state of the machine, some of the specified SDKs and runtimes might not be included in the output. To include all the SDKs and runtimes, list them explicitly as arguments or use the `--force` option.
> By default, SDKs and runtimes that have a high probability of being used by Visual Studio aren't removed. To remove these, specify them individually or use `--force`. If removing SDKs or runtimes causes issues with your Visual Studio installation, run Repair. SDKs and runtimes are available for download at [https://aka.ms/dotnet-core-download](https://aka.ms/dotnet-core-download).

::: zone-end

::: zone pivot="os-macos"

> [!NOTE]
> Use `--preserve-vs-for-mac-sdks` to prevent removal of SDKs and runtimes that have a high probability of being used by Visual Studio for Mac. Visual Studio for Mac is out of support. SDKs and runtimes are available for download at [https://aka.ms/dotnet-core-download](https://aka.ms/dotnet-core-download).

::: zone-end

- Dry run of removing all the .NET runtimes that have been superseded by higher patches:

Expand All @@ -176,12 +203,9 @@
- Dry run of removing all the .NET SDKs below the version `6.0.301`:

```console
dotnet-core-uninstall whatif --all-below 6.0.301 --sdk
dotnet-core-uninstall dry-run --all-below 6.0.301 --sdk
```

> [!TIP]
> The `dotnet-core-uninstall whatif` command is the same command as `dry-run`.

## See also

- [.NET uninstall tool overview](uninstall-tool-overview.md)
Expand Down
Loading
Loading