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

OS Elérési út
Linux/macOS $HOME/.dotnet/tools
Ablakok %USERPROFILE%\.dotnet\tools

Ha globális eszközt próbál futtatni, ellenőrizze, hogy a számítógépen található 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 macOS 10.14 "Mojave" vagy korábbi verziót használ, és a .NET SDK-t .tar.gz fájlokkal telepítette, a .pkg-t nem.
  • Ha telepítette a .NET Core 3.0 SDK-t, és a környezeti változót a DOTNET_ADD_GLOBAL_TOOLS_TO_PATH következőre falseállította be: .
  • Ha telepítette a .NET Core 2.2 SDK-t vagy korábbi verzióit, és beállította a DOTNET_SKIP_FIRST_TIME_EXPERIENCE környezeti változót true.

Ezekben a forgatókönyvekben, vagy ha dotnetes eszköz telepítésekor adta meg a --tool-path beállítást, a PATH számítógépen lévő környezeti változó nem tartalmazza automatikusan azt az elérési utat, amelyen a globális eszközt telepítette. Ebben az esetben fűzze hozzá az eszköz helyét (például) a PATH környezeti változóhoz bármilyen módszerrel, $HOME/.dotnet/toolsamelyet 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ában bárhol a .config nevű mappa alatt is élhet. Ha létezik dotnet-tools.json , nyissa meg, és keresse meg a futtatni kívánt eszközt. Ha a fájl nem tartalmaz bejegyzést "isRoot": true, 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 patch kiadására kerü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őretekeré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őretekeré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 kell a telepített futtatókörnyezeti verziót, forduljon az eszköz szerzőjéhez, és ellenőrizze, hogy frissíthetik-e a verziószámot vagy a többpéldányos verziót. 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 környezeti változót DOTNET_ROOT a végrehajtható fájlt tartalmazó dotnet 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ényszerítés

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 áttűnés során egyes Microsoft-eszközök a csomagazonosító régi formájával, míg mások az új űrlappal 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 verziók

  • Megkísérli telepíteni az előzetes verziójú kiadást, és nem adta meg a --version verziót.

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 nem .NET-eszköz volt.

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ó a következőhöz <toolName>: . 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 egy adott nuget.config fájllalnuget.config, vagy további hírcsatornákat is megadhat 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 történhet helytelenül, vagy az eszköz áthelyezése vagy elavultsága miatt. Az NuGet.org eszközeinek egyik módja annak biztosítása, hogy a név helyes legyen, ha megkeresi az eszközt a NuGet.org, és má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 paramétert, --ignore-failed-sources hogy megkerülje a hibát a privát hírcsatornából, és használja a nyilvános Microsoft-hírcsatornát.

    Ha egy eszközt a Microsoft NuGet-hírcsatornából telepít, az egyéni hírcsatorna ezt a hibát adja vissza, mielőtt a Microsoft NuGet-hírcsatornája eredményül ad vissza. A hiba megszakítja a kérést, és megszakítja a többi függőben lévő hírcsatorna-kérést, amely lehet 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ítse 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. Használja a hibás hírcsatorna és --ignore-failed-sources a --add-source paraméterek kombinációját, és támaszkodjon a nyilvános Microsoft-hírcsatornára.

    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 csak a nyilvános Microsoft NuGet-hírcsatornával, és hivatkozzon rá a --configfile következő 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 reference

  • 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ő adataival kapcsolatos további információkért tekintse meg a nuget.config referencia packageSourceCredentials szakaszát.

Kapcsolódó információk