Sorun Giderme .NET Core araç kullanım sorunlarıTroubleshoot .NET Core tool usage issues

Genel bir araç veya yerel bir araç olabilecek bir .NET Core aracını yüklemeye veya çalıştırmaya çalışırken sorunlarla karşılaşabilirsiniz.You might come across issues when trying to install or run a .NET Core tool, which can be a global tool or a local tool. Bu makalede, ortak kök nedenleri ve bazı olası çözümler açıklanır.This article describes the common root causes and some possible solutions.

Yüklü .NET Core aracı çalışmazInstalled .NET Core tool fails to run

Bir .NET Core aracı çalışmadığında, büyük olasılıkla aşağıdaki sorunlardan biriyle karşılaştınız:When a .NET Core tool fails to run, most likely you ran into one of the following issues:

  • Araç için çalıştırılabilir dosya bulunamadı.The executable file for the tool wasn't found.
  • .NET Core çalışma zamanının doğru sürümü bulunamadı.The correct version of the .NET Core runtime wasn't found.

Çalıştırılabilir dosya bulunamadıExecutable file not found

Çalıştırılabilir dosya bulunamazsa, aşağıdakilere benzer bir ileti görürsünüz:If the executable file isn't found, you'll see a message similar to the following:

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

Yürütülebilir adı aracı nasıl çağırdığınızı belirler.The name of the executable determines how you invoke the tool. Aşağıdaki tabloda biçim açıklanmaktadır:The following table describes the format:

Çalıştırılabilir ad biçimiExecutable name format Çağırma biçimiInvocation format
dotnet-<toolName>.exe dotnet <toolName>
<toolName>.exe <toolName>
  • Genel araçlarGlobal tools

    Genel araçlar varsayılan dizine veya belirli bir konuma yüklenebilir.Global tools can be installed in the default directory or in a specific location. Varsayılan dizinler şunlardır:The default directories are:

    İşletim SistemiOS YolPath
    Linux/macOSLinux/macOS $HOME/.dotnet/tools
    WindowsWindows %USERPROFILE%\.dotnet\tools

    Genel bir araç çalıştırmaya çalışıyorsanız, makinenizdeki ortam değişkeninin PATH genel aracı yüklediğiniz yolu içerdiğinden ve yürütülebilir aracın bu yolda olduğundan denetleyin.If you're trying to run a global tool, check that the PATH environment variable on your machine contains the path where you installed the global tool and that the executable is in that path.

    .NET Core CLI, ilk kullanımında PATH ortamı değişkenine varsayılan konumu eklemeye çalışır.The .NET Core CLI tries to add the default location to the PATH environment variable on its first usage. Ancak, konumun PATH'e otomatik olarak eklenemeyebildiği bazı senaryolar vardır:However, there are some scenarios where the location might not be added to PATH automatically:

    • Linux kullanıyorsanız ve .NET Core SDK'yı .tar.gz dosyalarını kullanarak yüklediyseniz ve apt-get veya rpm değil.If you're using Linux and you've installed the .NET Core SDK using .tar.gz files and not apt-get or rpm.
    • macOS 10.15 "Catalina" veya daha sonraki sürümleri kullanıyorsanız.If you're using macOS 10.15 "Catalina" or later versions.
    • macOS 10.14 "Mojave" veya önceki sürümleri kullanıyorsanız ve .tar.gz dosyalarını kullanarak .NET Core SDK'yı yüklediyseniz.pkg . .pkgIf you're using macOS 10.14 "Mojave" or earlier versions, and you've installed the .NET Core SDK using .tar.gz files and not .pkg.
    • .NET Core 3.0 SDK'yı yüklediyseniz ve ortam DOTNET_ADD_GLOBAL_TOOLS_TO_PATH değişkenini '' olarak falseayarladıysanızIf you've installed the .NET Core 3.0 SDK and you've set the DOTNET_ADD_GLOBAL_TOOLS_TO_PATH environment variable to false.
    • .NET Core 2.2 SDK veya önceki sürümlerini yüklediyseniz ve DOTNET_SKIP_FIRST_TIME_EXPERIENCE ortam truedeğişkenini ' olarak ayarladıysanız.If you've installed .NET Core 2.2 SDK or earlier versions, and you've set the DOTNET_SKIP_FIRST_TIME_EXPERIENCE environment variable to true.

    Bu senaryolarda veya --tool-path seçeneği belirttiyseniz, PATH makinenizdeki ortam değişkeni genel aracı yüklediğiniz yolu otomatik olarak içermez.In these scenarios or if you specified the --tool-path option, the PATH environment variable on your machine doesn't automatically contain the path where you installed the global tool. Bu durumda, shell'inizin çevre değişkenlerini güncelleştirmek için sağladığı yöntemi kullanarak araç konumunu (örneğin, $HOME/.dotnet/toolsçevre değişkenine) PATH ekleyerek ortam değişkenine eklayın.In that case, append the tool location (for example, $HOME/.dotnet/tools) to the PATH environment variable by using whatever method your shell provides for updating environment variables. Daha fazla bilgi için bkz.For more information, see .NET Core tools.

  • Yerel araçlarLocal tools

    Yerel bir aracı çalıştırmaya çalışıyorsanız, geçerli dizinde veya ana dizinde dotnet-tools.json adında bir bildirim dosyası olduğundan doğrulayın.If you're trying to run a local tool, verify that there's a manifest file called dotnet-tools.json in the current directory or any of its parent directories. Bu dosya, kök klasör ü yerine proje klasörü hiyerarşisinde herhangi bir yerde .config adlı bir klasör altında da yaşayabilir.This file can also live under a folder named .config anywhere in the project folder hierarchy, instead of the root folder. Dotnet-tools.json varsa açın ve çalıştırmaya çalıştığınız aracı kontrol edin.If dotnet-tools.json exists, open it and check for the tool you're trying to run. Dosya için "isRoot": truebir giriş içermiyorsa, ek araç bildirimi dosyaları için dosya hiyerarşisini daha da yukarı kontrol edin.If the file doesn't contain an entry for "isRoot": true, then also check further up the file hierarchy for additional tool manifest files.

    Belirli bir yol ile yüklenmiş bir .NET Core aracını çalıştırmaya çalışıyorsanız, aracı kullanırken bu yolu eklemeniz gerekir.If you're trying to run a .NET Core tool that was installed with a specified path, you need to include that path when using the tool. Bir araç yolu yüklü araç kullanma nın bir örneği:An example of using a tool-path installed tool is:

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

Çalışma süresi bulunamadıRuntime not found

.NET Core araçları çerçeveye bağımlı uygulamalardır,bu da makinenize yüklenen bir .NET Core çalışma süresine güvendikleri anlamına gelir..NET Core tools are framework-dependent applications, which means they rely on a .NET Core runtime installed on your machine. Beklenen çalışma süresi bulunamazsa, aşağıdakiler gibi normal .NET Core runtime roll-forward kurallarına uyarlar:If the expected runtime isn't found, they follow normal .NET Core runtime roll-forward rules such as:

  • Bir uygulama, belirtilen ana ve küçük sürümün en yüksek yama sürümüne doğru ilerler.An application rolls forward to the highest patch release of the specified major and minor version.
  • Eşleşen bir büyük ve küçük sürüm numarasıyla eşleşen çalışma zamanı yoksa, bir sonraki yüksek küçük sürüm kullanılır.If there's no matching runtime with a matching major and minor version number, the next higher minor version is used.
  • Roll forward, çalışma zamanının önizleme sürümleri veya önizleme sürümleri ve sürüm sürümleri arasında gerçekleşmez.Roll forward doesn't occur between preview versions of the runtime or between preview versions and release versions. Bu nedenle, önizleme sürümleri kullanılarak oluşturulan .NET Core araçlarının yazar tarafından yeniden oluşturulup yeniden yayımlanmalıdır ve yeniden yüklenmelidir.So, .NET Core tools created using preview versions must be rebuilt and republished by the author and reinstalled.

Roll-forward varsayılan olarak iki yaygın senaryoda oluşmaz:Roll-forward won't occur by default in two common scenarios:

  • Yalnızca çalışma zamanının daha düşük sürümleri kullanılabilir.Only lower versions of the runtime are available. Roll-forward yalnızca çalışma zamanının sonraki sürümlerini seçer.Roll-forward only selects later versions of the runtime.
  • Yalnızca çalışma zamanının daha yüksek ana sürümleri kullanılabilir.Only higher major versions of the runtime are available. Roll-forward ana sürüm sınırlarını geçmez.Roll-forward doesn't cross major version boundaries.

Bir uygulama uygun bir çalışma zamanı bulamazsa, çalışmaz ve bir hata bildirir.If an application can't find an appropriate runtime, it fails to run and reports an error.

Aşağıdaki komutlardan birini kullanarak makinenize hangi .NET Core çalışma saatlerinin takıldığı öğrenebilirsiniz:You can find out which .NET Core runtimes are installed on your machine using one of the following commands:

dotnet --list-runtimes
dotnet --info

Aracın şu anda yüklediğiniz çalışma zamanı sürümünü desteklemesi gerektiğini düşünüyorsanız, araç yazarına başvurabilir ve sürüm numarasını veya çoklu hedefi güncelleştirip güncelleştiremediklerini görebilirsiniz.If you think the tool should support the runtime version you currently have installed, you can contact the tool author and see if they can update the version number or multi-target. Araç paketlerini güncelleştirilmiş bir sürüm numarasıyla NuGet'e yeniden derleyip yeniden yayımladıktan sonra kopyanızı güncelleştirebilirsiniz.Once they've recompiled and republished their tool package to NuGet with an updated version number, you can update your copy. Bu gerçekleşmese de, sizin için en hızlı çözüm, çalıştırmaya çalıştığınız araçla çalışacak çalışma zamanının bir sürümünü yüklemektir.While that doesn't happen, the quickest solution for you is to install a version of the runtime that would work with the tool you're trying to run. Belirli bir .NET Core çalışma zamanı sürümünü indirmek için .NET Core indirme sayfasınıziyaret edin.To download a specific .NET Core runtime version, visit the .NET Core download page.

.NET Core SDK'yı varsayılan olmayan bir konuma yüklerseniz, ortam DOTNET_ROOT değişkenini dotnet yürütülebilir içeren dizine ayarlamanız gerekir.If you install the .NET Core SDK to a non-default location, you need to set the environment variable DOTNET_ROOT to the directory that contains the dotnet executable.

.NET Core araç kurulumu başarısız oldu.NET Core tool installation fails

.NET Core global veya yerel bir aracın yüklenmesinin başarısız olmasının birkaç nedeni vardır.There are a number of reasons the installation of a .NET Core global or local tool may fail. Araç yüklemesi başarısız olduğunda, aşağıdakine benzer bir ileti görürsünüz:When the tool installation fails, you'll see a message similar to the following one:

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 Core 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

Bu hataları tanılamaya yardımcı olmak için, NuGet iletileri önceki iletiyle birlikte doğrudan kullanıcıya gösterilir.To help diagnose these failures, NuGet messages are shown directly to the user, along with the previous message. NuGet iletisi sorunu belirlemenize yardımcı olabilir.The NuGet message may help you identify the problem.

Paket adlandırma zorlamaPackage naming enforcement

Microsoft, araçlar için Paket Kimliği kılavuzunu değiştirerek, bir dizi araçta öngörülen adla birlikte bulunamadı.Microsoft has changed its guidance on the Package ID for tools, resulting in a number of tools not being found with the predicted name. Yeni kılavuz, tüm Microsoft araçlarının "Microsoft" ile önceden belirlenmiş olmasıdır.The new guidance is that all Microsoft tools be prefixed with "Microsoft." Bu önek ayrılmıştır ve yalnızca Microsoft yetkili sertifikasıyla imzalanmış paketler için kullanılabilir.This prefix is reserved and can only be used for packages signed with a Microsoft authorized certificate.

Geçiş sırasında, bazı Microsoft araçları paket kimliğinin eski biçimine sahip olurken, diğerleri yeni forma sahip olur:During the transition, some Microsoft tools will have the old form of the package ID, while others will have the new form:

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

Paket kimlikleri güncelleştirildikçe, en son güncelleştirmeleri almak için yeni paket kimliğine değiştirmeniz gerekir.As package IDs are updated, you'll need to change to the new package ID to get the latest updates. Basitleştirilmiş araç adı taşıyan paketler amortismana sokulacaktır.Packages with the simplified tool name will be deprecated.

Önizleme bültenleriPreview releases

  • Bir önizleme sürümü yüklemeye çalışıyorsunuz ve sürümü --version belirtme seçeneğini kullanmadınız.You're attempting to install a preview release and didn't use the --version option to specify the version.

.NET Core araçları önizlemede olduklarını belirtmek için adın bir bölümüyle belirtilmelidir..NET Core tools that are in preview must be specified with a portion of the name to indicate that they are in preview. Önizlemenin tamamını eklemeniz gerekmez.You don't need to include the entire preview. Sürüm numaralarının beklenen biçimde olduğunu varsayarsak, aşağıdaki örnek gibi bir şey kullanabilirsiniz:Assuming the version numbers are in the expected format, you can use something like the following example:

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

Paket bir .NET Core aracı değildirPackage isn't a .NET Core tool

  • Bu ada göre bir NuGet paketi bulundu, ancak bir .NET Core aracı değildi.A NuGet package by this name was found, but it wasn't a .NET Core tool.

Bir .NET Core aracı değil de normal bir NuGet paketi yüklemeye çalışırsanız, aşağıdakilere benzer bir hata görürsünüz:If you try to install a NuGet package that is a regular NuGet package and not a .NET Core tool, you'll see an error similar to the following:

NU1212: Geçersiz proje paketi <ToolName>kombinasyonu.NU1212: Invalid project-package combination for <ToolName>. DotnetToolReference proje stili yalnızca DotnetTool türüne ait referanslar içerebilir.DotnetToolReference project style can only contain references of the DotnetTool type.

NuGet akışına erişilenemiyorNuGet feed can't be accessed

  • Gerekli NuGet akışına, internet bağlantısı sorunu nedeniyle erişilememektedir.The required NuGet feed can't be accessed, perhaps because of an Internet connection problem.

Araç yükleme, araç paketini içeren NuGet akışına erişim gerektirir.Tool installation requires access to the NuGet feed that contains the tool package. Özet akışı kullanılamıyorsa başarısız olur.It fails if the feed isn't available. Akışlarını nuget.configdeğiştirebilir, belirli nuget.config bir dosya yı isteyebilir veya --add-source anahtarla ek akışlar belirtebilirsiniz.You can alter feeds with nuget.config, request a specific nuget.config file, or specify additional feeds with the --add-source switch. Varsayılan olarak, NuGet bağlanamayan tüm akışlar için bir hata atar.By default, NuGet throws an error for any feed that can't connect. Bayrak --ignore-failed-sources bu erişilemez kaynakları atlayabilir.The flag --ignore-failed-sources can skip these non-reachable sources.

Paket kimliği yanlışPackage ID incorrect

  • Aracın adını yanlış yazdınız.You mistyped the name of the tool.

Hatanın yaygın bir nedeni, araç adının doğru olmamasıdır.A common reason for failure is that the tool name isn't correct. Bu, yanlış yazım nedeniyle veya araç taşındığı veya küçümdelenmiş olması nedeniyle olabilir.This can happen because of mistyping, or because the tool has moved or been deprecated. NuGet.org araçlar için, adı doğru olduğundan emin olmak için bir yolu NuGet.org aracı aramak ve yükleme komutunu kopyalamaktır.For tools on NuGet.org, one way to ensure you have the name correct is to search for the tool at NuGet.org and copy the installation command.

Ayrıca bkz.See also