.NET-eszközök használati problémáinak elhárítása
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:
- Az eszköz végrehajtható fájlja nem található.
- A .NET-futtatókörnyezet megfelelő verziója nem található.
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ótfalse
. - 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óttrue
é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": true
bejegyzé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ényszerítése
- előzetes verziójú kiadások
- A csomag nem .NET-eszköz
- NuGet-hírcsatorna nem érhető el
- csomagazonosító helytelen
- 401 (Jogosulatlan)
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.