Prerelease .NET SDK's lokaal testen met global.json paden

Vanaf .NET 10 ondersteunt het bestand global.json een eigenschap sdk.paths die aangeeft waar de .NET CLI moet zoeken naar SDK-installaties buiten de standaardsysteemlocatie. Met deze functie kunt u een prerelease-SDK installeren in een projectlocatiemap en deze alleen gebruiken wanneer u in dat project werkt. Het proces wijzigt geen systeembrede installaties en verandert niet de omgevingsvariabele op machine- of gebruikersniveau PATH . (Het installatiescript kan PATH tijdelijk bijwerken in de huidige shellsessie, maar die verandering blijft niet bestaan.)

Of u nu een nieuwe taalfunctie wilt uitproberen, een preview-versie voor uw team wilt evalueren of uw opensource-bibliotheek wilt valideren op basis van een toekomstige SDK-versie in CI, sdk.paths biedt u een veilige, omkeerbare manier om dit te doen. Als er iets misgaat, verwijdert u één map en bent u terug naar precies waar u bent begonnen.

Opmerking

In dit artikel wordt .NET 11 (de huidige voorlopige versie op het moment van schrijven) als voorbeeld gebruikt. De sdk.paths functie werkt met elke SDK-versie, voorlopige versie of stabiele, huidige of toekomstige versie. Vervang 11.0 en preview in de installatieopdrachten door de versie en kwaliteit die u nodig hebt.

Vereiste voorwaarden

  • .NET 10 of hoger geïnstalleerd op uw systeem, zodat de dotnet host op uw PATH versie 10.0 of hoger is. De host is het systeembrede uitvoerbare dotnet bestand dat beschikbaar is voor uw hele computer. Wanneer u een dotnet opdracht uitvoert, is deze host wat als eerste wordt geactiveerd: het leest global.json, bepaalt welke SDK-versie moet worden gebruikt en geeft de controle over aan die SDK. In dit artikel met instructies gebruikt u die host voor het hele systeem om de CLI naar een lokaal geïnstalleerde preview-SDK te sturen.
  • Een terminal- of opdrachtprompt (bash, zsh, PowerShell of opdrachtprompt).
  • (Optioneel) Een Git-opslagplaats waarin u het bereik van de prerelease-SDK wilt bepalen.

Belangrijk

De sdk.paths-functie vereist een .NET-versie 10 of hoger en een hostsysteem (de uitvoerbare toepassing dotnet op uw PATH). Als uw systeembrede host is .NET 8 of .NET 9, wordt de eigenschap paths niet herkend en wordt het standaardresolutiegedrag teruggezet. U kunt de lokale SDK nog steeds gebruiken door rechtstreeks ./.dotnet/dotnet (of .\.dotnet\dotnet op Windows) aan te roepen, waardoor de systeemhost wordt overgeslagen.

Als u de hostversie wilt controleren, voert u deze uit dotnet --info en zoekt u naar de sectie Host boven aan de uitvoer:

Host:
  Version:      10.0.0
  Architecture: x64
  Commit:       abc123def4

De Version regel moet 10.0 of later tonen. De hostversie is niet hetzelfde als de SDK-versie die door dotnet --version. Als op de host een oudere versie wordt weergegeven (bijvoorbeeld 8.0.x of 9.0.x), installeer .NET 10+ systeembreed om de dotnet-host op uw PATH bij te werken.

Hoe sdk.paths werkt

De eigenschap sdk.paths is een JSON-matrix met mappaden waarin de .NET host zoekt naar SDK-installaties. De host doorzoekt deze paden in de volgorde waarin u ze vermeldt en gebruikt de eerste SDK die voldoet aan de versiebeperkingen in global.json.

Twee belangrijke details:

  • Paden zijn relatief ten opzichte van de locatie van het global.json bestand, niet van uw huidige werkmap. Als uw global.json zich in de hoofdmap van de opslagplaats bevindt en u ".dotnet" opgeeft, zoekt de host naar een SDK in de .dotnet map in de hoofdmap van de opslagplaats, zelfs als u dotnet opdrachten uitvoert vanuit een submap.
  • $host$ is een speciaal token dat de installatiemap voor het .NET hele systeem vertegenwoordigt (de locatie van het dotnet uitvoerbaar bestand op uw PATH). Neem $host$ op in de matrix wanneer u de systeem-SDK als terugval wilt gebruiken.

Opmerking

Zowel het $host$-token als de hele eigenschap paths worden alleen herkend door .NET 10+ hosts. Oudere hosts negeren ze helemaal: ze produceren geen fout, ze slaan de eigenschap over en vallen terug op de standaard-SDK-resolutie.

Met de volgende configuratie moet de host bijvoorbeeld eerst zoeken naar een SDK in een lokale .dotnet map en vervolgens terugvallen op de systeeminstallatie:

{
  "sdk": {
    "paths": [".dotnet", "$host$"]
  }
}

Als u weglaat $host$ uit de matrix, doorzoekt de host alleen de mappen die u opgeeft. Als geen van deze sdk's een overeenkomende SDK bevat, mislukt de opdracht. Dit kan handig zijn als u wilt afdwingen dat er een specifieke SDK aanwezig is.

U kunt meer dan twee items weergeven. U kunt bijvoorbeeld afzonderlijke mappen bewaren voor een preview en een stabiele SDK en ze doorzoeken in de volgende volgorde: [".dotnet-preview", ".dotnet-stable", "$host$"]

Stap 1: Een prerelease-SDK lokaal installeren

Gebruik de officiële dotnet-install-scripts om een prerelease-SDK te downloaden naar een projectlokale map. Voor deze scripts zijn geen beheerdersbevoegdheden vereist en hoeft u uw systeem PATH of een systeembrede installatie niet te wijzigen.

curl -sSL https://dot.net/v1/dotnet-install.sh -o dotnet-install.sh
chmod +x dotnet-install.sh
./dotnet-install.sh --channel 11.0 --quality preview --install-dir .dotnet

De parameter --install-dir (of -InstallDir) plaatst de SDK in een .dotnet map binnen uw huidige directory. Er worden nergens anders bestanden op uw computer geschreven.

Aanbeveling

De --quality parameter accepteert drie waarden: daily (meest recente nightly build), preview (meest recente officiële preview) en GA (nieuwste stabiele release). U kunt ook --version gebruiken om een exacte SDK-versie te installeren, zoals --version 11.0.100-preview.2.26159.112.

Stap 2: .dotnet/ toevoegen aan .gitignore

De lokale SDK-installatie kan enkele honderden megabytes zijn. Voeg het toe aan uw .gitignore om het buiten broncodebeheer te houden:

echo '.dotnet/' >> .gitignore

Als uw project al een .gitignore heeft, controleer of .dotnet/ niet wordt bijgehouden voordat u committeert:

git status --ignored

Opmerking

Elke ontwikkelaar (en elke CI-agent) voert het installatiescript onafhankelijk uit. De .dotnet map is een lokale cache, geen gedeeld artefact.

Stap 3: global.json configureren

Maak of werk een global.json bestand bij in de hoofdmap van uw opslagplaats. U hebt minimaal de paths eigenschap nodig om aan de slag te gaan.

{
  "sdk": {
    "paths": [".dotnet", "$host$"]
  }
}

Hierdoor moet de host eerst zoeken naar een SDK in de lokale .dotnet map en vervolgens terugvallen op de systeeminstallatie. Er is geen versienummer vereist. De host kiest de meest recente SDK die wordt gevonden.

Voor meer controle kunt u een minimale versie vastmaken en gedrag voor roll-forward configureren:

{
  "sdk": {
    "version": "11.0.100-preview.2.26159.112",
    "allowPrerelease": true,
    "rollForward": "latestFeature",
    "paths": [".dotnet", "$host$"],
    "errorMessage": "Required .NET SDK not found. Run the install-dotnet script for your platform to install it locally."
  }
}

Hier ziet u wat elke eigenschap doet:

Vastgoed Purpose
version De minimale SDK-versie die is vereist voor het project.
allowPrerelease Hiermee kan de host prerelease-SDK-versies selecteren tijdens de implementatie. Ingesteld op true bij het testen van previews.
rollForward Hiermee bepaalt u hoe de host een nieuwere SDK selecteert wanneer de exacte versie niet beschikbaar is. latestFeature maakt het mogelijk om door te rollen naar een nieuwere featureband binnen dezelfde major.minor-versie.
paths Mappen om te zoeken naar SDK-installaties, in volgorde. ".dotnet" is de lokale map; "$host$" is de standaardinstelling van het systeem.
errorMessage Er wordt een aangepast bericht weergegeven wanneer er geen overeenkomende SDK wordt gevonden. Gebruik deze functie om inzenders precies te laten weten hoe ze hun omgeving kunnen instellen.

Aanbeveling

Vermelding ".dotnet" voordat "$host$" betekent dat de lokale prerelease-SDK prioriteit heeft. De volgorde omkeren als u wilt dat de systeem-SDK wint wanneer deze voldoet aan de versiebeperking.

Aanbeveling

Ben je van gedachten veranderd? Zie Opschonen aan het einde van dit artikel. Er worden geen systeembestanden aangeraakt.

Snel starten: alles-in-één-opdracht

Nu u begrijpt wat elke stap doet, is hier één opdracht die stap 1 tot en met 3 in één stap uitvoert. Plak de opdracht voor uw besturingssysteem in een terminal in de hoofdmap van uw project.

curl -sSL https://dot.net/v1/dotnet-install.sh -o /tmp/dotnet-install.sh \
  && bash /tmp/dotnet-install.sh --channel 11.0 --quality preview --install-dir .dotnet \
  && rm /tmp/dotnet-install.sh \
  && echo '.dotnet/' >> .gitignore \
  && cat > global.json << 'EOF'
{
  "sdk": {
    "paths": [".dotnet", "$host$"]
  }
}
EOF
echo "Installed: $(.dotnet/dotnet --version)"

Stap 4: Scripts voor teaminstallatie maken (optioneel)

Wanneer meerdere personen in dezelfde opslagplaats werken, voorkomt een handig script dat iedereen de installatieopdrachten moet onthouden. Maak één script voor elk platform in de hoofdmap van uw opslagplaats. Deze scripts installeren de SDK, maken global.json, bijwerken .gitignoreen eventueel workloads installeren, allemaal in één stap.

install-dotnet.sh (macOS/Linux):

#!/usr/bin/env bash
set -e

# -------- Configuration --------
CHANNEL="11.0"
QUALITY="preview"
# Uncomment the workloads your project needs:
# WORKLOADS="maui wasm-tools"
# --------------------------------

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
INSTALL_DIR="$SCRIPT_DIR/.dotnet"

echo "Installing .NET $CHANNEL ($QUALITY) SDK to $INSTALL_DIR ..."

curl -sSL https://dot.net/v1/dotnet-install.sh -o "$SCRIPT_DIR/dotnet-install.sh"
chmod +x "$SCRIPT_DIR/dotnet-install.sh"
"$SCRIPT_DIR/dotnet-install.sh" --channel "$CHANNEL" --quality "$QUALITY" --install-dir "$INSTALL_DIR"
rm -f "$SCRIPT_DIR/dotnet-install.sh"

# Auto-detect the installed SDK version
SDK_VERSION="$("$INSTALL_DIR/dotnet" --version)"

# Create global.json with the installed version
cat > "$SCRIPT_DIR/global.json" << EOF
{
  "sdk": {
    "version": "$SDK_VERSION",
    "allowPrerelease": true,
    "rollForward": "latestFeature",
    "paths": [".dotnet", "\$host\$"],
    "errorMessage": "Required .NET SDK not found. Run ./install-dotnet.sh (macOS/Linux) or .\\\\install-dotnet.ps1 (Windows) to install it locally."
  }
}
EOF

# Ensure .dotnet/ is in .gitignore
if ! grep -qxF '.dotnet/' "$SCRIPT_DIR/.gitignore" 2>/dev/null; then
    echo '.dotnet/' >> "$SCRIPT_DIR/.gitignore"
fi

# Install workloads if configured
if [ -n "${WORKLOADS:-}" ]; then
    echo "Installing workloads: $WORKLOADS"
    # shellcheck disable=SC2086
    "$INSTALL_DIR/dotnet" workload install $WORKLOADS
fi

echo ""
echo "Done! SDK $SDK_VERSION installed to $INSTALL_DIR"
echo "Run 'dotnet --version' to verify."

Maak het shell-script uitvoerbaar en voeg beide scripts toe aan uw opslagplaats:

chmod +x install-dotnet.sh
git add install-dotnet.sh install-dotnet.ps1

Wanneer deze scripts zijn ingecheckt, kunnen de errorMessage inzenders global.json de juiste uitvoeren voor hun platform. Een nieuw teamlid kloont de opslagplaats, voert het script uit en is klaar om te bouwen. Er hoeven geen handmatige SDK-installatiestappen te worden uitgevoerd.

Stap 5: De installatie controleren

Voer vanuit de map die uw global.json (of een submap) bevat de volgende opdrachten uit om te bevestigen dat de host de lokale prerelease-SDK oplost:

dotnet --version

In de uitvoer moet de voorlopige versie worden weergegeven die u hebt geïnstalleerd, bijvoorbeeld:

11.0.100-preview.2.26159.112

Voer de volgende opdracht uit voor meer gedetailleerde informatie over welke SDK is opgelost en waar deze is geladen:

dotnet --info

Zoek naar de regel met basispad in de uitvoer. Deze moet verwijzen naar de .dotnet map ten opzichte van uw project, waarbij wordt bevestigd dat de lokale installatie wordt gebruikt.

Opmerking

Als in de uitvoer de versie van uw systeem-SDK wordt weergegeven in plaats van de voorlopige versie, controleert u het volgende:

  • Hostversie versus SDK-versie: De hostversie (weergegeven onder dotnet --info de kop Host ) bepaalt of paths deze wordt begrepen. Dit moet 10,0 of hoger zijn. De SDK-versie (weergegeven door dotnet --version) is de versie die is bepaald na de verwerking door de host global.json.
  • Het global.json bestand bevindt zich in een bovenliggende map van uw huidige werkmap.
  • De .dotnet map bevat een volledige SDK-installatie (controleer op een sdk submap erin).

Stap 6: Workloads installeren op de lokale SDK (optioneel)

Nadat u een lokale SDK hebt geïnstalleerd, kunt u optionele workloads zoals .NET MAUI of Blazor WebAssembly AOT erop installeren. Workloads die op de lokale SDK zijn geïnstalleerd, zijn volledig onafhankelijk van workloads op uw systeembrede installatie.

Een workload installeren

Zorg ervoor dat u dit uitvoert vanuit de map die uw global.json (of een submap) bevat. Gebruik het lokale dotnet binaire bestand rechtstreeks om ervoor te zorgen dat de workload is geïnstalleerd in de SDK op uw lokale systeem en niet van uw systeeminstallatie.

./.dotnet/dotnet workload install maui

Belangrijk

Gebruik altijd ./.dotnet/dotnet (of .\.dotnet\dotnet op Windows) voor werkbelastingopdrachten. De global.jsonpaths-functie routeert de SDK-resolutie correct voor opdrachten zoals dotnet build en dotnet run, maar workloads slaan metagegevens op ten opzichte van de dotnet root van de host waarop ze worden uitgevoerd. Wanneer u de systeemhost gebruikt, eindigen workloads in de systeeminstallatie in plaats van de lokale. Dit is een bekend gat in de sdk.paths interactie met DOTNET_ROOT. Door het lokale binaire bestand rechtstreeks te gebruiken, zorgt u ervoor dat workloads op de juiste plaats worden geïnstalleerd en bijgehouden.

Opmerking

Op macOS en Linux hoeft u sudo workload te installeren wanneer u een lokale SDK gebruikt. De .dotnet/ map is eigendom van de gebruiker, dus alle workloadbestanden worden geschreven met uw normale gebruikersmachtigingen. Dit verschilt van installaties voor het hele systeem, waarvoor mogelijk verhoogde bevoegdheden zijn vereist.

Algemene workloads

De volgende tabel bevat veelgebruikte workloads:

Werklast Opdracht Installeren
.NET MAUI ./.dotnet/dotnet workload install maui
ASP.NET Core (Blazor WASM AOT) ./.dotnet/dotnet workload install wasm-tools

U kunt meerdere workloads installeren in één opdracht:

./.dotnet/dotnet workload install maui wasm-tools

Geïnstalleerde workloads controleren

Ga als volgt te werk om te zien welke workloads zijn geïnstalleerd op de lokale SDK:

./.dotnet/dotnet workload list

Aanbeveling

Workloads die zijn geïnstalleerd op de lokale SDK, worden opgeslagen in de .dotnet/ map. Als u de map verwijdert, worden de SDK en alle bijbehorende workloads verwijderd. Gedeelde downloadcaches (zoals ~/.nuget/packages) blijven mogelijk behouden, maar hebben geen invloed op uw systeem.

Stap 7: De prerelease-SDK gebruiken in CI (optioneel)

Dezelfde benadering werkt in pijplijnen voor continue integratie. CI-runners hebben echter mogelijk geen .NET 10+ host vooraf geïnstalleerd, dus u moet ervoor zorgen dat de host beschikbaar is voordat u vertrouwt op sdk.paths.

GitHub Actions voorbeeld

De volgende werkstroom installeert een .NET 10-host met behulp van actions/setup-dotnet en installeert vervolgens de .NET 11 preview SDK lokaal. De setup-dotnet stap zorgt ervoor dat de runner een .NET 10+ host heeft op PATH die de eigenschap paths kan lezen in global.json.

name: Build with preview SDK

on: [push, pull_request]

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]

    steps:
      - uses: actions/checkout@v4

      - name: Install .NET 10 host
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'
          dotnet-quality: 'preview'

      - name: Cache local SDK
        uses: actions/cache@v4
        with:
          path: .dotnet
          key: dotnet-local-${{ matrix.os }}-${{ hashFiles('global.json') }}

      - name: Install .NET 11 preview SDK locally
        # Use bash shell explicitly — Windows runners default to PowerShell,
        # which doesn't support the curl/chmod/shell-script syntax below.
        shell: bash
        run: |
          curl -sSL https://dot.net/v1/dotnet-install.sh -o dotnet-install.sh
          chmod +x dotnet-install.sh
          ./dotnet-install.sh --channel 11.0 --quality preview --install-dir .dotnet

      - name: Build
        run: dotnet build

      - name: Test
        run: dotnet test

Omdat de global.json configuratie al in uw opslagplaats aanwezig is, gebruiken de dotnet build en dotnet test stappen automatisch de lokale SDK. Er zijn geen wijzigingen nodig in de systeembrede installatie van de CI-agent.

Aanbeveling

Met actions/cache de stap wordt de map tussen uitvoeringen in de .dotnet/ cache opgeslagen, gesleuteld in het besturingssysteem en de hash van global.json. De cache wordt automatisch vernieuwd wanneer u de SDK-versie bijwerkt in global.json.

Opmerking

De strategy.matrix sectie voert de build uit op meerdere besturingssystemen. U kunt de matrix uitbreiden om te testen op meerdere SDK-versies door een sdk-version dimensie toe te voegen en deze te gebruiken in de installatiestap.

Terugval: de lokale host rechtstreeks gebruiken

Als u .NET 10+ systeembreed niet kunt installeren op de runner (bijvoorbeeld in een vergrendelde CI-omgeving), roept u de lokale SDK's eigen host rechtstreeks aan in plaats van te vertrouwen op het systeem dotnet:

- name: Install .NET 11 preview SDK locally
  run: |
    curl -sSL https://dot.net/v1/dotnet-install.sh -o dotnet-install.sh
    chmod +x dotnet-install.sh
    ./dotnet-install.sh --channel 11.0 --quality preview --install-dir .dotnet

- name: Build using local host
  run: ./.dotnet/dotnet build

- name: Test using local host
  run: ./.dotnet/dotnet test

Deze aanpak omzeilt de systeemhost volledig en vereist geen sdk.paths oplossing — het lokale dotnet uitvoerbare bestand weet waar zijn eigen SDK zich bevindt.

Beperkingen

De sdk.paths functie heeft enkele beperkingen waarmee u rekening moet houden:

  • Vereist een .NET 10 of hoger host op PATH. Het dotnet uitvoerbare bestand dat global.json leest, moet versie 10.0 of hoger zijn. Als de systeemhost ouder is, wordt de paths eigenschap volledig genegeerd.
  • Alleen van toepassing op SDK-opdrachten. De paths eigenschap is van invloed op SDK-resolutie voor opdrachten zoals dotnet build, dotnet runen dotnet test. Dit heeft geen invloed op de resolutie van de app-host of op framework-afhankelijke uitvoering (bijvoorbeeld dotnet myapp.dll).
  • Paden zijn relatief ten opzichte van de global.json locatie. Als u het global.json bestand verplaatst, werkt u de paden dienovereenkomstig bij. Een absoluut pad werkt ook, maar vermindert de draagbaarheid tussen computers.

Schoonmaken

Als u een lokale prerelease-SDK verwijdert, moet u twee stappen uitvoeren:

  1. Verwijder de lokale SDK-map:

    rm -rf .dotnet/
  1. Verwijder de paths eigenschap uit global.jsonof verwijder het bestand als u deze niet meer nodig hebt. Uw project wordt teruggezet naar het gebruik van de systeembrede SDK.

Omdat alles project-lokaal is, inclusief alle workloads die u hebt geïnstalleerd, zijn er geen registervermeldingen, omgevingsvariabelen of systeembestanden die moeten worden opgeschoond. Het verwijderen van de map en het terugdraaien global.json is alles wat nodig is. Alle workloads die op de lokale SDK zijn geïnstalleerd, worden samen met de .dotnet/ map verwijderd.

Volgende stappen 

  • Last updated on