Megosztás a következőn keresztül:

.NET-eszközök használati problémáinak elhárítása

  • Cikk

Előfordulhat, hogy problémákat tapasztal egy .NET-eszköz telepítésekor vagy futtatásakor, amely lehet globális vagy helyi eszköz. Ez a cikk ismerteti a gyakori kiváltó okokat és néhány lehetséges megoldást.

A telepített .NET-eszköz nem fut

Ha egy .NET-eszköz nem fut, valószínűleg a következő problémák egyikével ütközött:

Nem található végrehajtható fájl

Ha a végrehajtható fájl nem található, a következőhöz hasonló üzenet jelenik meg:

Could not execute because the specified command or file was not found.
Possible reasons for this include:
  * You misspelled a built-in dotnet command.
  * You intended to execute a .NET program, but dotnet-xyz does not exist.
  * You intended to run a global tool, but a dotnet-prefixed executable with this name could not be found on the PATH.

A végrehajtható fájl neve határozza meg, hogyan hívja meg az eszközt. Az alábbi táblázat a formátumot ismerteti:

Végrehajtható névformátum Meghívás formátuma
dotnet-<toolName>.exe dotnet <toolName>
<toolName>.exe <toolName>

Globális eszközök

A globális eszközök az alapértelmezett könyvtárban vagy egy adott helyen telepíthetők. Az alapértelmezett könyvtárak a következők:

Operációs rendszer Ösvény
Linux/macOS $HOME/.dotnet/tools
Windows %USERPROFILE%\.dotnet\tools

Ha globális eszközt próbál futtatni, ellenőrizze, hogy a PATH környezeti változó tartalmazza-e azt az elérési utat, ahová a globális eszközt telepítette, és hogy a végrehajtható fájl ezen az elérési úton található-e.

A .NET CLI megpróbálja hozzáadni az alapértelmezett helyet a PATH környezeti változóhoz az első használatkor. Vannak azonban olyan esetek, amikor előfordulhat, hogy a hely nem lesz automatikusan hozzáadva a PATH-hoz:

  • Ha Linuxot használ, és a .NET SDK-t .tar.gz fájlokkal telepítette, és nem apt-get vagy rpm használatával.
  • Ha macOS 10.15 "Catalina" vagy újabb verziót használ.
  • Ha a macOS 10.14 "Mojave" vagy korábbi verziót használja, és a .NET SDK-t .tar.gz fájlokkal telepítette, nem pedig .pkg.
  • Ha telepítette a .NET Core 3.0 SDK-t, és beállította a DOTNET_ADD_GLOBAL_TOOLS_TO_PATH környezeti változót false.
  • Ha telepítette a .NET Core 2.2 SDK-t vagy korábbi verzióit, és a DOTNET_SKIP_FIRST_TIME_EXPERIENCE környezeti változót trueértékre állította.

Ezekben a forgatókönyvekben, vagy ha a dotnetes eszköz telepítésekor --tool-path beállítást adta meg, a PATH környezeti változó nem tartalmazza automatikusan azt az útvonalat, amelyen a globális eszközt telepítette. Ebben az esetben fűzze hozzá az eszköz helyét (például $HOME/.dotnet/tools) a PATH környezeti változóhoz, bármilyen módszerrel, amelyet a rendszerhéj biztosít a környezeti változók frissítéséhez. További információ: .NET-eszközök.

Helyi eszközök

Ha helyi eszközt próbál futtatni, ellenőrizze, hogy van-e dotnet-tools.json nevű jegyzékfájl az aktuális könyvtárban vagy annak szülőkönyvtáraiban. Ez a fájl a gyökérmappa helyett a projektmappák hierarchiájának bármely pontján .config nevű mappa alatt is élhet. Ha dotnet-tools.json létezik, nyissa meg, és keresse meg a futtatni kívánt eszközt. Ha a fájl nem tartalmaz "isRoot": truebejegyzést, akkor további eszközjegyzékfájlokat is kereshet a fájlhierarchiában.

Ha egy megadott elérési úttal telepített .NET-eszközt próbál futtatni, az eszköz használatakor ezt az elérési utat kell megadnia. Az eszközútvonalra telepített eszközök használatára példa:

..\<toolDirectory>\dotnet-<toolName>

A futtatókörnyezet nem található

A .NET-eszközök keretrendszerfüggő alkalmazások, ami azt jelenti, hogy a számítógépen telepített .NET-futtatókörnyezetre támaszkodnak. Ha a várt futtatókörnyezet nem található, a normál .NET-futtatókörnyezeti roll-forward szabályokat követik, például:

  • Az alkalmazás a megadott fő- és alverzió legmagasabb javítócsomag-kiadására frissül.
  • Ha nincs egyező futtatókörnyezet egyező fő- és alverziószámmal, a rendszer a következő magasabb alverziót használja.
  • Az előrelépés nem történik meg a futtatókörnyezet előzetes verziói, illetve az előzetes verziók és a kiadási verziók között. Ezért az előzetes verziókkal létrehozott .NET-eszközöket újra kell létrehoznia és újra közzé kell tennie a szerzőnek, és újra kell telepítenie.

Az előretekerés alapértelmezés szerint nem történik meg két gyakori forgatókönyvben:

  • Csak a futtatókörnyezet alacsonyabb verziói érhetők el. Az előretekerés csak a futtatókörnyezet későbbi verzióit jelöli ki.
  • Csak a futtatókörnyezet magasabb főverziói érhetők el. Az előrehaladás nem lépi át a főverzió határait.

Ha egy alkalmazás nem talál megfelelő futtatókörnyezetet, nem fut, és hibát jelez.

Az alábbi parancsok egyikével megtudhatja, hogy mely .NET-futtatókörnyezetek vannak telepítve a számítógépen:

dotnet --list-runtimes
dotnet --info

Ha úgy gondolja, hogy az eszköznek támogatnia kellene a jelenleg telepített futtatókörnyezeti verziót, lépjen kapcsolatba az eszköz szerzőjével, és érdeklődjön, hogy frissíthetik-e a verziószámot, vagy elérhetővé tudják-e tenni több cél számára is. Miután újra lefordították és újra közzétették az eszközcsomagot a NuGetben egy frissített verziószámmal, frissítheti a másolatot. Bár ez nem történik meg, a leggyorsabb megoldás a futtatókörnyezet olyan verziójának telepítése, amely a futtatni kívánt eszközzel működik. Egy adott .NET-futtatókörnyezeti verzió letöltéséhez látogasson el a .NET letöltési oldalára.

Ha a .NET SDK-t nem alapértelmezett helyre telepíti, a DOTNET_ROOT környezeti változót a végrehajtható dotnet tartalmazó könyvtárra kell beállítania.

A .NET-eszköz telepítése sikertelen

A .NET globális vagy helyi eszköz telepítése több okból is meghiúsulhat. Ha az eszköz telepítése sikertelen, az alábbihoz hasonló üzenet jelenik meg:

Tool '{0}' failed to install. This failure may have been caused by:

* You are attempting to install a preview release and did not use the --version option to specify the version.
* A package by this name was found, but it was not a .NET tool.
* The required NuGet feed cannot be accessed, perhaps because of an Internet connection problem.
* You mistyped the name of the tool.

For more reasons, including package naming enforcement, visit https://aka.ms/failure-installing-tool

A hibák diagnosztizálásához a NuGet-üzenetek közvetlenül a felhasználó számára jelennek meg az előző üzenettel együtt. A NuGet-üzenet segíthet a probléma azonosításában.

Csomagelnevezési követelmények betartása

A Microsoft módosította az eszközök csomagazonosítójára vonatkozó útmutatóját, így számos eszköz nem található az előrejelzett névvel. Az új útmutató az, hogy az összes Microsoft-eszköz előtagja a "Microsoft" lesz. Ez az előtag fenntartott, és csak a Microsoft által hitelesített tanúsítvánnyal aláírt csomagokhoz használható.

Az átmenet során egyes Microsoft-eszközök a csomagazonosító régi formájával, míg mások az új formátummal rendelkeznek:

dotnet tool install -g Microsoft.<toolName>
dotnet tool install -g <toolName>

A csomagazonosítók frissítése során a legújabb frissítések beszerzéséhez át kell váltania az új csomagazonosítóra. Az egyszerűsített eszköznévvel rendelkező csomagok elavultak lesznek.

Előzetes kiadások

  • Egy előzetes kiadást próbál telepíteni, és nem használta a --version beállítást a verzió megadásához.

Az előzetes verzióban lévő .NET-eszközöket a név egy részével kell megadni, hogy jelezzék, hogy előzetes verzióban vannak. Nem kell a teljes előnézetet belefoglalnia. Feltételezve, hogy a verziószámok a várt formátumban vannak, az alábbi példához hasonlót használhat:

dotnet tool install -g --version 1.1.0-pre <toolName>

A csomag nem .NET-eszköz

  • Egy ilyen nevű NuGet-csomag található, de az nem .NET-eszköz.

Ha olyan NuGet-csomagot próbál telepíteni, amely normál NuGet-csomag, és nem .NET-eszköz, az alábbihoz hasonló hibaüzenet jelenik meg:

NU1212: Érvénytelen projektcsomag-kombináció <toolName>esetében. A DotnetToolReference projektstílus csak DotnetTool típusú hivatkozásokat tartalmazhat.

A NuGet-hírcsatorna nem érhető el

  • A szükséges NuGet-hírcsatorna nem érhető el, talán internetkapcsolati probléma miatt.

Az eszköztelepítéshez hozzá kell férnie az eszközcsomagot tartalmazó NuGet-hírcsatornához. Sikertelen, ha a hírcsatorna nem érhető el. Módosíthatja a hírcsatornákat nuget.config, kérhet egy adott nuget.config fájlt, vagy további hírcsatornákat adhat meg a --add-source kapcsolóval. Alapértelmezés szerint a NuGet hibát jelez minden olyan hírcsatorna esetében, amely nem tud csatlakozni. A jelölő --ignore-failed-sources kihagyhatja ezeket a nem elérhető forrásokat.

A csomagazonosító helytelen

  • Helytelenül írta be az eszköz nevét.

A hiba gyakori oka, hogy az eszköz neve nem helyes. ** Ez azért történhet, mert elgépelés történt, vagy mert az eszközt áthelyezték, vagy megszüntették. A NuGet.org eszközeivel kapcsolatban az egyik módja annak, hogy megbizonyosodjon a név helyességéről, ha megkeresi az eszközt a NuGet.org-on, és lemásolja a telepítési parancsot.

401 (Jogosulatlan)

Valószínűleg egy másik NuGet-hírcsatornát adott meg, és ez a hírcsatorna hitelesítést igényel. Ezt többféleképpen is megoldhatja:

  • Adja hozzá a --ignore-failed-sources paramétert, hogy megkerülje a hibát a magáncsatornából, és használja a nyilvános Microsoft-hírcsatornát.

    Ha egy eszközt a Microsoft NuGet-adatcsatornából telepít, az egyéni adatcsatorna ezt a hibát adja vissza, mielőtt a Microsoft NuGet-adatcsatorna eredményt adna vissza. A hiba megszakítja a kérést, és törli a többi függőben lévő hírcsatorna-kérést, amely lehet, hogy a Microsoft NuGet-csatornája. A --ignore-failed-sources beállítás hozzáadása miatt a parancs figyelmeztetésként kezeli ezt a hibát, és lehetővé teszi, hogy más hírcsatornák feldolgozzák a kérést.

    dotnet tool install -g --ignore-failed-sources <toolName>

  • Kényszerítsd a Microsoft NuGet-hírcsatornát a --add-source paraméterrel.

    Előfordulhat, hogy a globális vagy helyi NuGet-konfigurációs fájlból hiányzik a nyilvános Microsoft NuGet-hírcsatorna. A --add-source és --ignore-failed-sources paraméterek kombinációjával elkerülheti a hibás hírcsatornát, és a nyilvános Microsoft-hírcsatornára támaszkodhat.

    dotnet tool install -g --add-source 'https://api.nuget.org/v3/index.json' --ignore-failed-sources <toolName>

  • Használjon egyéni NuGet-konfigurációt, --configfile <FILE> paramétert.

    Hozzon létre egy helyi nuget.config fájlt, amely kizárólag a nyilvános Microsoft NuGet-hírcsatornát tartalmazza, és hivatkozzon rá a --configfile paraméterrel:

    dotnet tool install -g --configfile "./nuget.config" <toolName>

    Íme egy példa konfigurációs fájl:

    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
  </packageSources>
</configuration>

    További információ: nuget.config referencia.

  • Adja hozzá a szükséges hitelesítő adatokat a konfigurációs fájlhoz.

    Ha tudja, hogy a csomag megtalálható a konfigurált hírcsatornában, adja meg a bejelentkezési hitelesítő adatokat a NuGet konfigurációs fájljában. A NuGet-konfigurációs fájlok hitelesítő adatairól további információt a nuget.config hivatkozás a packageSourceCredentials szakaszábantalálhat.

Lásd még:

  • .NET-eszközök