Udostępnij za pośrednictwem

Testowanie wersji zapoznawczych SDK .NET lokalnie przy użyciu ścieżek global.json

Począwszy od .NET 10, plik global.json obsługuje właściwość sdk.paths, która informuje interfejs wiersza polecenia .NET, gdzie szukać instalacji zestawu SDK poza domyślną lokalizacją systemową. Ta funkcja umożliwia zainstalowanie zestawu SDK wersji wstępnej w folderze project-local i użycie go tylko wtedy, gdy pracujesz w tym projekcie. Proces nie modyfikuje instalacji w całym systemie i nie zmienia zmiennej środowiskowej na poziomie komputera ani na poziomie PATH użytkownika. (Skrypt instalacji może tymczasowo aktualizować PATH w bieżącej sesji powłoki, ale ta zmiana nie jest utrwalana).

Niezależnie od tego, czy chcesz wypróbować nową funkcję języka, ocenić wersję zapoznawczą dla swojego zespołu, czy zweryfikować bibliotekę open source przeciwko nadchodzącej wersji zestawu SDK w CI, sdk.paths zapewnia bezpieczny, odwracalny sposób, aby to zrobić. Jeśli coś pójdzie nie tak, usuniesz jeden folder i wrócisz do dokładnie tego, gdzie rozpoczęto.

Uwaga / Notatka

W tym artykule .NET 11 (aktualna wersja przedpremierowa w momencie pisania) używana jest jako przykład w całym artykule. Funkcja sdk.paths działa z dowolną wersją zestawu SDK, wersją wstępną lub stabilną, bieżącą lub przyszłością. Zastąp 11.0 i preview w poleceniach instalacji tą wersją i jakością, które są potrzebne.

Wymagania wstępne

  • .NET 10 lub nowszy zainstalowany w systemie, tak aby host dotnet na twoim PATH był w wersji 10.0 lub nowszej. Host jest plikiem wykonywalnym dla całego dotnet systemu dostępnym dla całej maszyny. Po uruchomieniu dowolnego dotnet polecenia ten host jest tym, co działa jako pierwsze: odczytuje global.json, decyduje, którą wersję zestawu SDK należy używać, i przekazuje sterowanie temu zestawowi SDK. W tym artykule z instrukcjami użyjesz tego hosta systemowego, aby przekierować CLI na lokalnie zainstalowany zestaw SDK w wersji zapoznawczej.
  • Terminal lub wiersz polecenia (bash, zsh, PowerShell lub wiersz polecenia).
  • (Opcjonalnie) Repozytorium Git, w którym chcesz określić zakres wersji wstępnej SDK.

Ważna

Funkcja sdk.paths wymaga .NET 10 lub nowszego środowiska uruchomieniowego (plik wykonywalny dotnet na PATH). Jeśli w całym systemie hostem jest .NET 8 lub .NET 9, nie rozpoznaje właściwości paths i powraca do domyślnego sposobu rozstrzygania. Możesz nadal używać lokalnego zestawu SDK, wywołując ./.dotnet/dotnet (lub .\.dotnet\dotnet na Windows) bezpośrednio, co pomija hosta systemu.

Aby zweryfikować wersję hosta, uruchom dotnet --info i poszukaj sekcji Host w górnej części danych wyjściowych:

Host:
  Version:      10.0.0
  Architecture: x64
  Commit:       abc123def4

Wiersz Version musi wskazywać 10.0 lub nowszy. Wersja hosta nie jest taka sama jak wersja zestawu SDK zgłoszona przez dotnet --version. Jeśli na hoście jest wyświetlana starsza wersja (na przykład 8.0.x lub 9.0.x), zainstaluj .NET 10+ w całym systemie, aby zaktualizować hosta dotnet na urządzeniu PATH.

Jak działa SDK.paths

Właściwość sdk.paths jest tablicą JSON ścieżek folderów, w których host .NET szuka instalacji zestawu SDK. Host przeszukuje te ścieżki w kolejności, w jakiej je wymieniasz, i używa pierwszego zestawu SDK spełniającego ograniczenia wersji w global.json.

Dwa kluczowe szczegóły:

  • Ścieżki są powiązane z lokalizacją global.json pliku, a nie z bieżącym katalogem roboczym. Jeśli twój global.json znajduje się w katalogu głównym repozytorium i określisz ".dotnet", host szuka SDK w folderze .dotnet w katalogu głównym — nawet jeśli uruchamiasz polecenia dotnet z podkatalogu.
  • $host$ jest specjalnym tokenem, który reprezentuje katalog instalacyjny .NET w całym systemie (to lokalizacja pliku wykonywalnego dotnet na PATH). Dołącz $host$ do tablicy, gdy chcesz, aby zestaw SDK systemu działał jako rozwiązanie zapasowe.

Uwaga / Notatka

Zarówno token $host$, jak i cała właściwość paths są rozpoznawane tylko przez hosty .NET 10+. Starsze hosty ignorują je całkowicie — nie generują błędu, po prostu pomijają właściwość i wracają do domyślnej rozdzielczości zestawu SDK.

Na przykład następująca konfiguracja nakazuje hostowi wyszukanie zestawu SDK najpierw w folderze lokalnym .dotnet , a następnie powrót do instalacji systemu:

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

Jeśli pominiesz $host$ w tablicy, host przeszukuje tylko określone przez Ciebie katalogi. Jeśli żaden z nich nie zawiera pasującego zestawu SDK, polecenie zakończy się niepowodzeniem — co może być przydatne, gdy chcesz wymusić, że określony zestaw SDK jest obecny.

Można wyświetlić więcej niż dwa wpisy. Na przykład można przechowywać oddzielne foldery dla wersji zapoznawczej i stabilnego zestawu SDK i przeszukiwać je w kolejności: [".dotnet-preview", ".dotnet-stable", "$host$"].

Krok 1. Lokalne instalowanie zestawu SDK wersji wstępnej

Użyj oficjalnych skryptów dotnet-install, aby pobrać SDK w wersji prerelease do katalogu lokalnego projektu. Te skrypty nie wymagają uprawnień administratora i nie modyfikują systemu PATH ani żadnej instalacji w całym systemie.

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

Parametr --install-dir (lub -InstallDir) umieszcza SDK w folderze .dotnet wewnątrz bieżącego katalogu. Żadne pliki nie są zapisywane nigdzie indziej na maszynie.

Wskazówka

Parametr akceptuje trzy wartości: (najnowsza --quality kompilacja nocna), daily (najnowsza oficjalna wersja zapoznawcza) i preview (najnowsza stabilna wersja). GA Możesz również użyć --version polecenia , aby zainstalować dokładną wersję zestawu SDK, taką jak --version 11.0.100-preview.2.26159.112.

Krok 2. Dodawanie pliku .dotnet/ do pliku gitignore

Lokalna instalacja zestawu SDK może być kilkaset megabajtów. Dodaj go do elementu .gitignore , aby zachować go poza kontrolą źródła:

echo '.dotnet/' >> .gitignore

Jeśli projekt ma już element .gitignore, przed zatwierdzeniem sprawdź, czy .dotnet/ nie jest śledzony.

git status --ignored

Uwaga / Notatka

Każdy deweloper (i każdy agent CI) uruchamia skrypt instalacyjny niezależnie. Folder .dotnet jest lokalną pamięcią podręczną, a nie artefaktem udostępnionym.

Krok 3. Konfigurowanie global.json

Utwórz lub zaktualizuj plik global.json na poziomie katalogu głównego repozytorium. Do rozpoczęcia wystarczy co najmniej właściwość paths.

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

Spowoduje to, że host będzie szukał zestawu SDK najpierw w folderze lokalnym .dotnet, a następnie wróci do instalacji systemowej. Nie jest wymagany numer wersji — host wybiera najnowszy zestaw SDK, który znajdzie.

Aby uzyskać większą kontrolę, możesz przypiąć minimalną wersję i skonfigurować zachowanie rolowania do przodu.

{
  "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."
  }
}

Oto, co robi każda właściwość:

Majątek Purpose
version Minimalna wersja zestawu SDK wymagana przez projekt.
allowPrerelease Umożliwia hostowi wybranie wersji wstępnej zestawu SDK podczas wprowadzania. Ustaw na true przy testowaniu wersji zapoznawczych.
rollForward Określa sposób, w jaki host wybiera nowszy zestaw SDK, gdy dokładna wersja nie jest dostępna. latestFeature umożliwia aktualizowanie do nowszego zakresu funkcjonalności w ramach tej samej wersji głównej i pomocniczej.
paths Katalogi do wyszukiwania instalacji pakietu SDK w kolejności. ".dotnet" jest folderem lokalnym; "$host$" jest wartością domyślną systemu.
errorMessage Komunikat niestandardowy wyświetlany, gdy nie znaleziono pasującego zestawu SDK. Użyj go, aby poinformować współautorów, jak dokładnie skonfigurować swoje środowisko.

Wskazówka

Wyświetlanie listy ".dotnet" przed "$host$" oznacza, że lokalny zestaw SDK wersji wstępnej ma priorytet. Odwróć kolejność, jeśli chcesz, aby zestaw SDK systemu wygrał, gdy spełnia on ograniczenie wersji.

Wskazówka

Zmienił zdanie? Zobacz Czyszczenie na końcu tego artykułu. Żadne pliki systemowe nie są dotykane.

Szybki start: polecenie kompleksowe

Teraz, gdy rozumiesz, co robi każdy krok, oto jedno polecenie, które wykonuje kroki od 1 do 3 w jednym kroku. Wklej komendę odpowiednią dla twojego systemu operacyjnego do terminalu przy katalogu głównym projektu.

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)"

Krok 4: Tworzenie skryptów instalacyjnych dla zespołu (opcjonalnie)

Gdy wiele osób pracuje nad tym samym repozytorium, skrypt wygody uniemożliwia wszystkim zapamiętanie poleceń instalacji. Utwórz jeden skrypt dla każdej platformy w katalogu głównym repozytorium. Te skrypty instalują zestaw SDK, tworzą global.json, aktualizują .gitignorei opcjonalnie instalują obciążenia — wszystko w jednym kroku.

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."

Nadaj uprawnienia do wykonywania skryptowi powłoki i dodaj oba skrypty do repozytorium.

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

Po zaewidencjonowaniu tych skryptów, errorMessage w global.json może nakierować współpracowników, aby uruchomili odpowiedni skrypt dla swojej platformy. Nowy członek zespołu klonuje repozytorium, uruchamia skrypt i jest gotowy do skompilowania — nie trzeba wykonywać ręcznych kroków instalacji zestawu SDK.

Krok 5. Weryfikowanie instalacji

W katalogu zawierającym global.json (lub dowolny podkatalog) uruchom następujące polecenia, aby potwierdzić, że host rozpozna lokalny zestaw SDK wersji wstępnej:

dotnet --version

Dane wyjściowe powinny pokazywać zainstalowaną wersję wstępną, na przykład:

11.0.100-preview.2.26159.112

Aby uzyskać bardziej szczegółowe informacje o tym, który zestaw SDK został rozwiązany i skąd został załadowany, uruchom:

dotnet --info

Wyszukaj wiersz Ścieżka podstawowa w danych wyjściowych. Powinien on wskazywać .dotnet folder względem projektu, potwierdzając, że instalacja lokalna jest używana.

Uwaga / Notatka

Jeśli dane wyjściowe zawierają wersję zestawu SDK systemu zamiast wersji wstępnej, sprawdź następujące elementy:

  • Wersja hosta a wersja zestawu SDK: Wersja hosta (wyświetlana w dotnet --info nagłówku Host ) określa, czy paths jest zrozumiałe. Musi to być wersja 10.0 lub nowsza. Wersja zestawu SDK (pokazana przez dotnet --version) jest wersją rozpoznaną po procesach global.jsonhosta.
  • Plik global.json znajduje się w katalogu nadrzędnym bieżącego katalogu roboczego.
  • Folder .dotnet zawiera pełną instalację zestawu SDK (sprawdź sdk podfolder wewnątrz niego).

Krok 6. Instalowanie obciążeń w lokalnym zestawie SDK (opcjonalnie)

Po zainstalowaniu lokalnego zestawu SDK można zainstalować opcjonalne obciążenia, takie jak .NET MAUI lub Blazor WebAssembly AOT. Obciążenia zainstalowane w lokalnym zestawie SDK są całkowicie niezależne od obciążeń w całej instalacji systemu.

Instalacja pakietu zadań

Upewnij się, że uruchamiasz to z folderu zawierającego global.json (lub jego podkatalogu). Użyj bezpośrednio lokalnego pliku binarnego dotnet, aby upewnić się, że obciążenie jest zainstalowane w lokalnym zestawie SDK, a nie w systemowej instalacji.

./.dotnet/dotnet workload install maui

Ważna

Zawsze używaj ./.dotnet/dotnet (lub .\.dotnet\dotnet w Windows) dla poleceń obciążeń. Funkcja global.jsonpaths poprawnie zarządza rozpoznawaniem zestawu SDK dla poleceń takich jak dotnet build i dotnet run, lecz polecenia dotyczące obciążenia przechowują metadane w odniesieniu do katalogu głównego dotnet hosta, który je uruchamia. W przypadku korzystania z hosta systemowego obciążenia kończą się instalacją systemu, a nie lokalną. Jest to znana luka w sposobie sdk.paths interakcji z DOTNET_ROOT. Bezpośrednie użycie lokalnego pliku binarnego gwarantuje, że zadania robocze są instalowane i śledzone we właściwym miejscu.

Uwaga / Notatka

W systemach macOS i Linux nie trzeba sudo instalować modułów podczas korzystania z lokalnego zestawu SDK. Folder .dotnet/ jest własnością użytkownika, więc wszystkie pliki obciążenia są zapisywane z normalnymi uprawnieniami użytkownika. Różni się to od instalacji w całym systemie, które mogą wymagać podniesionych uprawnień.

Typowe obciążenia

W poniższej tabeli wymieniono często używane obciążenia:

Obciążenie Zainstaluj polecenie
.NET MAUI ./.dotnet/dotnet workload install maui
ASP.NET Core (Blazor WASM AOT) ./.dotnet/dotnet workload install wasm-tools

W jednym poleceniu można zainstalować wiele obciążeń:

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

Weryfikowanie zainstalowanych obciążeń

Aby sprawdzić, które ładunki robocze są zainstalowane w lokalnym zestawie SDK:

./.dotnet/dotnet workload list

Wskazówka

Obciążenia zainstalowane w lokalnym zestawie SDK są przechowywane w .dotnet/ katalogu . Usunięcie katalogu powoduje usunięcie zestawu SDK i wszystkich jego obciążeń. Udostępnione pamięci podręczne pobierania (takie jak ~/.nuget/packages) mogą pozostać, ale nie mają wpływu na Twój system.

Krok 7. Korzystanie z zestawu SDK wersji wstępnej w ciągłej integracji (opcjonalnie)

To samo podejście działa w potokach ciągłej integracji. Jednak biegacze CI mogą nie mieć z góry zainstalowanego hosta .NET 10+, dlatego należy upewnić się, że host jest dostępny przed użyciem sdk.paths.

Przykład GitHub Actions

Poniższy przepływ pracy instaluje hosta .NET 10 przy użyciu actions/setup-dotnet, a następnie instaluje zestaw SDK .NET 11 w wersji zapoznawczej lokalnie. Krok setup-dotnet zapewnia, że aplikacja uruchamiająca ma host z .NET 10+ na PATH, który może odczytać właściwość paths w 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

Ponieważ w twoim repozytorium global.json już ma paths konfigurację, dotnet build i dotnet test kroki automatycznie pobierają lokalny zestaw SDK. Nie są wymagane żadne zmiany w systemowej instalacji agenta ciągłej integracji.

Wskazówka

Krok actions/cache buforuje katalog .dotnet/ między przebiegami, wykorzystując jako klucz system operacyjny i skrót global.json. Pamięć podręczna jest odświeżana automatycznie po zaktualizowaniu wersji zestawu SDK w programie global.json.

Uwaga / Notatka

Sekcja strategy.matrix uruchamia kompilację w wielu systemach operacyjnych. Macierz można rozszerzyć w celu przetestowania wielu wersji zestawu SDK, dodając nowy wymiar sdk-version i używając go podczas kroku instalacji.

Zapasowe rozwiązanie: użyj bezpośrednio lokalnego hosta.

Jeśli nie możesz zainstalować .NET 10+ globalnie na urządzeniu (na przykład w ograniczonym środowisku CI), wywołaj bezpośrednio własny host lokalnego zestawu SDK zamiast polegać na instalacji systemowej 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

Takie podejście całkowicie pomija hosta systemowego i nie wymaga rozstrzygania sdk.paths — lokalny plik wykonywalny dotnet wie, gdzie znajduje się własny zestaw SDK.

Ograniczenia

Funkcja sdk.paths ma kilka ograniczeń, o których należy pamiętać:

  • Wymaga hosta .NET 10 lub nowszego na PATH. Plik dotnet wykonywalny, który odczytuje global.json , musi mieć wersję 10.0 lub nowszą. Jeśli host systemu jest starszy, całkowicie ignoruje paths właściwość .
  • Dotyczy tylko poleceń zestawu SDK. Właściwość paths wpływa na rozpoznawanie zestawu SDK w odniesieniu do poleceń, takich jak dotnet build, dotnet run i dotnet test. Nie ma to wpływu na rozpoznawanie hostów aplikacji ani wykonywanie zależne od platformy (na przykład dotnet myapp.dll).
  • Ścieżki są powiązane z lokalizacją global.json. W przypadku przeniesienia pliku global.json należy odpowiednio zaktualizować ścieżki. Ścieżka bezwzględna również działa, ale zmniejsza przenośność między maszynami.

Czyszczenie

Usunięcie lokalnego zestawu SDK wersji wstępnej wymaga wykonania dwóch kroków:

  1. Usuń lokalny folder zestawu SDK:

    rm -rf .dotnet/
  1. Usuń właściwość paths z global.json lub usuń plik, jeśli nie jest już potrzebny. Projekt powraca do korzystania z zestawu SDK dla całego systemu.

Ponieważ wszystko jest projektem lokalnym — w tym wszystkie zainstalowane obciążenia — nie ma żadnych wpisów rejestru, zmiennych środowiskowych ani plików systemowych do wyczyszczenia. Usunięcie folderu i cofnięcie global.json to wszystko, co trzeba zrobić. Wszystkie obciążenia zainstalowane w lokalnym zestawie SDK są usuwane wraz z folderem .dotnet/ .

Następne kroki

  • global.json omówienie — pełna dokumentacja wszystkich global.json właściwości, w tym version, rollForward i allowPrerelease.
  • dotnet-install scripts reference — pełna lista parametrów skryptów instalacji międzyplatformowych.
  • Omówienie zestawu SDK .NET — dowiedz się więcej na temat wersjonowania zestawu SDK, zasad przesuwania wersji oraz jak host rozwiązuje zestawy SDK.
  • Jak wybrać wersję .NET do użycia — szczegóły dotyczące sposobu rozpoznawania wersji zestawu SDK i środowiska uruchomieniowego przez hosta .NET.
  • Co nowego w .NET 11 — Przegląd funkcji i ulepszeń w .NET 11.
  • Last updated on