.NET aracı kullanım sorunlarını giderme

Genel bir araç veya yerel bir araç olabilecek bir .NET aracını yüklemeye veya çalıştırmaya çalışırken sorunlarla karşılaşabilirsiniz. Bu makalede yaygın kök nedenler ve bazı olası çözümler açıklanmaktadır.

Yüklü .NET aracı çalıştırılamıyor

Bir .NET aracı çalıştırılamıyorsa, büyük olasılıkla aşağıdaki sorunlardan biriyle karşılaştınız:

• Aracın yürütülebilir dosyası bulunamadı.
• .NET çalışma zamanının doğru sürümü bulunamadı.

Yürütülebilir dosya bulunamadı

Yürütülebilir dosya bulunamazsa aşağıdakine benzer bir ileti görürsünüz:

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.

Yürütülebilir dosyanın adı, aracı nasıl çağırabileceğinizi belirler. Aşağıdaki tabloda biçimi açıklanmaktadır:

Yürütülebilir ad biçimi	Çağırma biçimi
dotnet-<toolName>.exe	dotnet <toolName>
<toolName>.exe	<toolName>

Genel araçlar

Genel araçlar varsayılan dizine veya belirli bir konuma yüklenebilir. Varsayılan dizinler şunlardır:

OS	Path
Linux/macOS	$HOME/.dotnet/tools
Windows	%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çerip içermediğini ve yürütülebilir dosyanın bu yolda olup olmadığını denetleyin.

.NET CLI, ilk kullanımında PATH ortam değişkenine varsayılan konumu eklemeye çalışır. Ancak, konumun PATH'e otomatik olarak eklenmeyebileceği bazı senaryolar vardır:

• Linux kullanıyorsanız ve .NET SDK'sını apt-get veya rpm değil de .tar.gz dosyalarını kullanarak yüklediyseniz.
• macOS 10.15 "Catalina" veya sonraki sürümleri kullanıyorsanız.
• macOS 10.14 "Mojave" veya önceki sürümleri kullanıyorsanız ve .pkg değil .tar.gz dosyalarını kullanarak .NET SDK'sını yüklediyseniz.
• .NET Core 3.0 SDK'sını yüklediyseniz ve ortam değişkenini DOTNET_ADD_GLOBAL_TOOLS_TO_PATH olarak falseayarladıysanız.
• .NET Core 2.2 SDK'sını veya önceki sürümleri yüklediyseniz ve ortam değişkenini DOTNET_SKIP_FIRST_TIME_EXPERIENCE olarak trueayarladıysanız.

Bu senaryolarda veya bir dotnet aracı yüklerken seçeneği belirttiyseniz--tool-path, PATH makinenizdeki ortam değişkeni otomatik olarak genel aracı yüklediğiniz yolu içermez. Bu durumda, kabuğunuzun ortam değişkenlerini güncelleştirmek için sağladığı yöntemi kullanarak araç konumunu (örneğin, $HOME/.dotnet/tools) PATH ortam değişkenine ekleyin. Daha fazla bilgi için bkz . .NET araçları.

Yerel araçlar

Yerel bir araç çalıştırmaya çalışıyorsanız, geçerli dizinde veya üst dizinlerinden herhangi birinde dotnet-tools.json adlı bir bildirim dosyası olduğunu doğrulayın. Bu dosya, kök klasör yerine proje klasörü hiyerarşisinde herhangi bir yerde .config adlı bir klasör altında da bulunabilir. dotnet-tools.json varsa açın ve çalıştırmaya çalıştığınız aracı denetleyin. Dosya için "isRoot": truebir girdi içermiyorsa, ek araç bildirim dosyaları için dosya hiyerarşisini de gözden geçirin.

Belirtilen bir yol ile yüklenmiş bir .NET aracını çalıştırmaya çalışıyorsanız, aracı kullanırken bu yolu eklemeniz gerekir. Araç yolu yüklü bir araç kullanma örneği:

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

Çalışma zamanı bulunamadı

.NET araçları çerçeveye bağımlı uygulamalardır; bu da makinenizde yüklü bir .NET çalışma zamanına bağımlı oldukları anlamına gelir. Beklenen çalışma zamanı bulunamazsa, aşağıdakiler gibi normal .NET çalışma zamanı ileri sarma kurallarını izler:

• Bir uygulama, belirtilen ana ve ikincil sürümün en yüksek düzeltme eki sürümüne iletir.
• Eşleşen bir ana ve ikincil sürüm numarasına sahip eşleşen bir çalışma zamanı yoksa, sonraki daha yüksek ikincil sürüm kullanılır.
• İleri sarma, çalışma zamanının önizleme sürümleri arasında veya önizleme sürümleri ile sürüm sürümleri arasında gerçekleşmez. Bu nedenle, önizleme sürümleri kullanılarak oluşturulan .NET araçlarının yazar tarafından yeniden oluşturulması ve yeniden yayımlanması gerekir.

İki yaygın senaryoda ileri sarma varsayılan olarak gerçekleşmez:

• Çalışma zamanının yalnızca daha düşük sürümleri kullanılabilir. İleri sarma, çalışma zamanının yalnızca sonraki sürümlerini seçer.
• Çalışma zamanının yalnızca daha yüksek ana sürümleri kullanılabilir. İleri sarma, ana sürüm sınırlarını aşmaz.

Bir uygulama uygun bir çalışma zamanını bulamazsa, çalıştırılamaz ve bir hata bildirir.

Aşağıdaki komutlardan birini kullanarak makinenize hangi .NET çalışma zamanlarının yüklendiğini öğrenebilirsiniz:

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ştiremediğini görebilirsiniz. Araç paketlerini nuGet'e güncelleştirilmiş bir sürüm numarasıyla yeniden derleyip yeniden yayımladıktan sonra, kopyanızı güncelleştirebilirsiniz. Bu gerçekleşmese de, sizin için en hızlı çözüm çalıştırmaya çalıştığınız araçla çalışacak bir çalışma zamanı sürümü yüklemektir. Belirli bir .NET çalışma zamanı sürümünü indirmek için .NET indirme sayfasını ziyaret edin.

.NET SDK'sını varsayılan olmayan bir konuma yüklerseniz ortam değişkenini DOTNET_ROOT yürütülebilir dosyayı içeren dotnet dizine ayarlamanız gerekir.

.NET aracı yüklemesi başarısız oluyor

.NET genel veya yerel aracının yüklenmesinin başarısız olmasının çeşitli nedenleri vardır. Araç yüklemesi başarısız olduğunda aşağıdakine benzer bir ileti görürsünüz:

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

Bu hataları tanılamaya yardımcı olmak için NuGet iletileri, önceki iletiyle birlikte doğrudan kullanıcıya gösterilir. NuGet iletisi sorunu belirlemenize yardımcı olabilir.

• Paket adlandırma zorlaması
• Önizleme sürümleri
• Paket bir .NET aracı değildir
• NuGet akışına erişilemiyor
• Paket kimliği yanlış
• 401 (Yetkisiz)

Paket adlandırma zorlaması

Microsoft, araçlar için Paket Kimliği kılavuzunda değişiklik yaparak tahmin edilen adla bir dizi araç bulunamadı. Yeni kılavuz, tüm Microsoft araçlarının ön ekinin "Microsoft" olarak belirlenmiş olmasıdır. Bu ön ek ayrılmıştır ve yalnızca Microsoft yetkili sertifikasıyla imzalanan paketler için kullanılabilir.

Geçiş sırasında bazı Microsoft araçları paket kimliğinin eski biçimine, diğerleri ise yeni forma sahip olur:

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. Basitleştirilmiş araç adına sahip paketler kullanım dışı bırakılacaktır.

Önizleme sürümleri

• Bir önizleme sürümü yüklemeye çalışıyorsunuz ve sürümü belirtmek için seçeneğini kullanmadınız --version .

Önizleme aşamasında olan .NET araçları, önizleme aşamasında olduklarını belirtmek için adın bir bölümüyle belirtilmelidir. Önizlemenin tamamını eklemeniz gerekmez. Sürüm numaralarının beklenen biçimde olduğunu varsayarsak, aşağıdaki örneğe benzer bir şey kullanabilirsiniz:

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

Paket bir .NET aracı değildir

• Bu ada sahip bir NuGet paketi bulundu, ancak bir .NET aracı değildi.

.NET aracı değil de normal bir NuGet paketi olan bir NuGet paketi yüklemeye çalışırsanız, aşağıdakine benzer bir hata görürsünüz:

NU1212: için <toolName>geçersiz proje paketi bileşimi. DotnetToolReference proje stili yalnızca DotnetTool türünün başvurularını içerebilir.

NuGet akışına erişilemiyor

• Gerekli NuGet akışına, belki de İnternet bağlantısı sorunu nedeniyle erişilemiyor.

Araç yüklemesi, araç paketini içeren NuGet akışına erişim gerektirir. Akış kullanılamıyorsa başarısız olur. ile nuget.configakışları değiştirebilir, belirli nuget.config bir dosya isteyebilir veya anahtarla --add-source ek akışlar belirtebilirsiniz. Varsayılan olarak, NuGet bağlanamıyor herhangi bir akış için bir hata oluşturur. bayrağı --ignore-failed-sources bu ulaşılamayan kaynakları atlayabilir.

Paket kimliği yanlış

• Aracın adını yanlış yazdınız.

Hatanın yaygın nedenlerden biri, araç adının doğru olmadığıdır. Bunun nedeni yanlış şekillendirme veya aracın taşınmış veya kullanım dışı bırakılmış olması olabilir. NuGet.org araçları için doğru ada sahip olduğunuzdan emin olmak için NuGet.org'da aracı aramak ve yükleme komutunu kopyalamak gerekir.

401 (Yetkisiz)

Büyük olasılıkla alternatif bir NuGet akışı belirttiniz ve bu akış için kimlik doğrulaması gerekiyor. Bunu çözmenin birkaç farklı yolu vardır:

• --ignore-failed-sources Özel akıştan hatayı atlamak için parametresini ekleyin ve genel Microsoft akışını kullanın.

  Microsoft NuGet akışından bir araç yüklüyorsanız, Microsoft'un NuGet akışı sonuç döndürmeden önce özel akışınız bu hatayı döndürüyordur. Hata, microsoft'un NuGet akışı olabilecek diğer bekleyen akış isteklerini iptal ederek isteği sonlandırır. seçeneğinin --ignore-failed-sources eklenmesi komutun bu hatayı uyarı olarak kabul etmesine neden olur ve diğer akışların isteği işlemesine izin verir.

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

• Parametresiyle --add-source Microsoft NuGet akışını zorlama.

  Genel veya yerel NuGet yapılandırma dosyasında genel Microsoft NuGet akışı eksik olabilir. Hatalı akışı önlemek ve genel Microsoft akışına güvenmek için ve --ignore-failed-sources parametrelerinin bir bileşimini --add-source kullanın.

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

• Özel bir NuGet yapılandırması, --configfile <FILE> parametresi kullanın.

  Yalnızca genel Microsoft NuGet akışıyla yerel bir nuget.config dosyası oluşturun ve bu dosyaya --configfile parametresiyle başvurun:

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

  Aşağıda örnek bir yapılandırma dosyası verilmişti:

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

  Daha fazla bilgi için bkz. nuget.config başvurusu

• Yapılandırma dosyasına gerekli kimlik bilgilerini ekleyin.

  Paketin yapılandırılan akışta var olduğunu biliyorsanız NuGet yapılandırma dosyasında oturum açma kimlik bilgilerini sağlayın. Nuget yapılandırma dosyasındaki kimlik bilgileri hakkında daha fazla bilgi için nuget.config başvurusunun packageSourceCredentials bölümüne bakın.

Ayrıca bkz.

• .NET araçları