Paket Kaynağı Eşlemesi

Paket Kaynağı Eşlemesi, özellikle genel ve özel paket kaynaklarının bir karışımını kullanıyorsanız tedarik zinciri güvenliğinizi geliştirmek için kullanılabilecek bir araçtır.

Varsayılan olarak NuGet, bir paketi indirmesi gerektiğinde yapılandırılmış tüm paket kaynaklarını arar. Bir paket birden çok kaynakta mevcut olduğunda, paketin hangi kaynaktan indirileceği belirlenemeyebilir. Paket Kaynağı Eşlemesi ile paket başına nuGet'in hangi kaynakları arayacağını filtreleyebilirsiniz.

Ayrıca, tedarik zincirinizi saldırılara karşı güçlendirmenize yardımcı olacak diğer en iyi yöntemlere yönelik önerilerimiz de vardır.

Paket Kaynağı Eşlemesi NuGet 6.0'a eklendi. Visual Studio 17.5'den başlayarak, Visual Studio Seçenekleri İletişim Kutusu ile Paket Kaynağı Eşlemeleri ekleyebilir ve kaldırabilirsiniz.

Visual Studio desteği

Visual Studio	Paket Kaynağı Eşlemesi	Araçlarda Destek -> Seçenekler	Paket Yöneticisi kullanıcı arabiriminde destek
17.0 - 17.4	✅ Kullanılabilir	❌ Yok	❌ Yok
17.5	✅ Kullanılabilir	✅ Kullanılabilir	❌ Yok
17.7 Önizleme 3	✅ Kullanılabilir	✅ Kullanılabilir	✅ Görüntülenen durum

Bu özellik tüm NuGet tümleşik araçlarda kullanılabilir.

• Visual Studio 2022 ve üzeri
• .NET SDK 6.0.100 ve üzeri
• nuget.exe 6.0.0 ve üzeri

Eski araçlar Paket Kaynağı Eşleme yapılandırmasını yoksayar. Bu özelliği kullanmak için tüm derleme ortamlarınızın uyumlu araç sürümlerini kullandığına emin olun.

Uyumlu araçlar kullanıldığı sürece Paket Kaynağı Eşlemeleri .NET Framework de dahil olmak üzere tüm proje türlerine uygulanır.

Görüntülü kılavuz

Paket Kaynağı Eşleme özelliğine video tabanlı bir genel bakış için YouTube'da Paket Kaynağı Eşlemesi ile NuGet paketlerinizin güvenliğini sağlama videosunu izlemeyi göz önünde bulundurun.

Paket Kaynağı Eşlemesini Etkinleştirme

Bu özelliği kabul etmek için bir nuget.config dosyanız olmalıdır. Deponuzun kökünde tek nuget.config bir tane olması en iyi yöntem olarak kabul edilir. Daha fazla bilgi edinmek için nuget.config belgelerine bakın.

Visual Studio Seçenekleri İletişim Kutusunu kullanarak etkinleştirme

1. Çözümünüzü Visual Studio’da açın.
2. Seçenekler İletişim Kutusu'na Package Source Mappings gidin.

Paket Yöneticisi kullanıcı arabiriminden

• Ayrıntılar Bölmesi'nde göstermek için listeden bir paket seçin.
• Configure Paket Kaynağı Eşlemeleri seçenekleri sayfasını açmak için düğmeye basın.

Visual Studio Seçenekleri İletişim Kutusundan

• Ana Visual Studio araç çubuğundaki menüye Tools gidin ve - öğesini>Package Manager Settings seçin NuGet Package Manager .
• Package Source Mappings sayfasına gidin.

3. İletişim kutusunu Add açmak için sayfadaki düğmeye Add Package Source Mappings basınPackage Source Mappings.

4. Bir Paket Kimliği veya Paket Deseni girin ve istediğiniz kaynakların onay kutusunu açarak bir veya daha fazla paket kaynağı seçin.

5. Seçenekler Package Source Mapping sayfasında yeni oluşturulan kaynak eşleme gösterilir.

6. İlgili nuget.configüzerinde yapılan değişiklikleri kaydetmek için Seçenekler İletişim Kutusu'na basınOK.
7. NuGet Paket Yöneticisi penceresi yenilenir ve seçilen paketin kaynak eşlemelerinin yeni durumunu yansıtır.

El ile düzenleyerek etkinleştirme nuget.config

• dosyanızda nuget.config istediğiniz paket kaynaklarını bildirin.
• Kaynak bildirimlerinizin ardından, her kaynak için istenen eşlemeleri belirten bir <packageSourceMapping> öğe ekleyin.
• Kullanımdaki her kaynak için tam olarak bir packageSource öğe bildirin.
  • Gerektiği kadar desen ekleyin.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <!-- Define the package sources, nuget.org and contoso.com. -->
  <!-- `clear` ensures no additional sources are inherited from another config file. -->
  <packageSources>
    <clear />
    <!-- `key` can be any identifier for your source. -->
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso.com" value="https://contoso.com/packages/" />
  </packageSources>
  
  <!-- Define mappings by adding package patterns beneath the target source. -->
  <!-- Contoso.* packages and NuGet.Common will be restored from contoso.com,
       everything else from nuget.org. -->
  <packageSourceMapping>
    <!-- key value for <packageSource> should match key values from <packageSources> element -->
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="contoso.com">
      <package pattern="Contoso.*" />
      <package pattern="NuGet.Common" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Çeşitli düzeylerde (makine düzeyinde, kullanıcı düzeyinde, depo düzeyinde) birden çok nuget.config dosya mevcut olduğunda, Paket Kaynağı Eşleme ayarları nuget.config öncelik kurallarına göre uygulanır.

Paket Kaynağı Eşleme kuralları

Maksimum esneklik ve denetim için NuGet, tüm paketlerin iyi tanımlanmış bir öncelik aracılığıyla bir paket deseni ile eşleşmesini gerektirir.

Paket Düzeni gereksinimleri

İstenen tüm paketler, tanımlı bir paket desenini eşleştirerek bir veya daha fazla kaynağa eşlenmelidir. Başka bir deyişle, bir packageSourceMapping öğe tanımladıktan sonra geçişli paketler de dahil olmak üzere her paketin hangi kaynaklardan geri yükleneceği açıkça tanımlamalısınız.

• Hem üst düzey hem de geçişli paketler tanımlı desenler ile eşleşmelidir. En üst düzey paketin ve bağımlılıklarının aynı kaynaktan gelmesi gerekmez.
• Aynı kimlik deseni birden çok kaynakta tanımlanabilir ve eşleşen paket kimliklerinin deseni tanımlayan akışlardan geri yüklenmesine olanak sağlar. Ancak, geri yükleme öngörülebilirliği üzerindeki etkisi nedeniyle bu önerilmez (belirli bir paket birden çok kaynaktan gelebilir). İlgili tüm kaynaklara güveniyorsanız bu geçerli bir yapılandırma olabilir.

Paket Deseni Söz Dizimi

Desen	Örnek söz dizimi	Açıklama
Paket ön eki deseni	*, NuGet.*	0 veya daha fazla karakterle eşleşen bir ** ile bitmelidir. * izin verilen en kısa ön ek düzenidir ve tüm paket kimlikleriyle eşleşir.
Paket Kimliği deseni	NuGet.Common, Contoso.Contracts	Tam paket kimliği.

Paket Deseni önceliği

Birden çok benzersiz desen bir paket kimliğiyle eşleştiğinde, en özel desen tercih edilir. Paket kimliği desenleri her zaman en yüksek önceliğe sahipken, genel * her zaman en düşük önceliğe sahiptir. Paket ön eki desenleri için en uzun önceliklidir.

Varsayılan kaynakları ayarlama

Desen * , bir de-facto varsayılan kaynağı bildirmek için kullanılabilir; başka bir deyişle, belirtilen diğer desenlere uymayan tüm paketler hata oluşturmadan bu kaynaktan geri yüklenir. Bu yapılandırma, öncelikle örneğinden nuget.orggelen paketleri kullanıyorsanız ve yalnızca birkaç iç paketiniz varsa veya gibi Contoso.*tüm iç paketler için standart ön ekleri kullanıyorsanız avantajlıdır.

Ekibiniz yüklemeden önce iç paket kimlikleri veya veteriner nuget.org paketleri için standart ön ekleri kullanmıyorsa, özel kaynağı varsayılan yapmak gereksinimlerinize daha uygun olacaktır.

Not

İstenen paket genel paketler klasöründe zaten mevcut olduğunda, kaynak arama gerçekleşmez ve eşlemeler yoksayılır. Bu özelliğin tüm güvenlik avantajlarından yararlanmak için deponuz için genel paketler klasörü bildirmeyi göz önünde bulundurun. Bir sonraki yineleme için varsayılan genel paketler klasörüyle deneyimi geliştirmek için çalışma yapılması planlanıyor. Paket yüklemesinin nasıl çalıştığı hakkında daha fazla bilgi edinmek için kavramsal belgeye bakın .

Kullanmaya başlayın

Deponuzu el ile veya NuGet.PackageSourceMapper aracını kullanarak tam olarak eklemenin 2 yolu vardır.

El ile ekleme

El ile ekleme için aşağıdaki adımları uygulayabilirsiniz:

1. Deponuz için yeni bir genel paketler klasörü bildirin.
2. Bağımlılıkları geri yüklemek için dotnet restore komutunu çalıştırın.
3. Çözümünüzdeki tüm üst düzey ve geçişli paketleri görüntülemek için komutunu çalıştırın dotnet list package --include-transitive .
   • kullanan packages.configpackages.config .NET framework projeleri için, dosya tüm doğrudan ve geçişli paketlerin düz bir listesine sahip olur.
4. Geçişli paketler de dahil olmak üzere çözümünüzdeki her paket kimliğinin hedef kaynak için bir desenle eşleşmesi için eşlemeler tanımlayın.
5. Genel paketler dizinini temizlemek için dotnet nuget locals global-packages -c komutunu çalıştırın.
6. Eşlemelerinizi doğru yapılandırdığınızdan doğrulamak için geri yüklemeyi çalıştırın. Eşlemeleriniz çözümünüzdeki her paket kimliğini tam olarak kapsamazsa hata iletileri sorunu belirlemenize yardımcı olur.
7. Geri yükleme başarılı olduğunda işiniz biter! İsteğe bağlı olarak aşağıdakileri göz önünde bulundurun:
   • Daha geniş paket kimliği ön eklerini kullanarak veya mümkün olduğunca varsayılan bir kaynak ayarlayarak yapılandırmayı daha az bildirime basitleştirme.
   • Genel paketler klasöründeki meta veri dosyalarını denetleyerek veya geri yükleme günlüklerini gözden geçirerek her paketin geri yüklendiği kaynağı doğrulama.

Aracı kullanarak otomatik ekleme

Birçok depoda çok sayıda paket vardır ve işi el ile yapmak zaman alabilir. NuGet.PackageSourceMapper aracı, projenizin bilinen paketlerine ve kaynaklarına göre sizin için otomatik olarak bir NuGet.config oluşturabilir.

Paket kaynak eşleyici aracı, ilgili paketlerinizi ve kaynaklarınızı nasıl eşlediğinize en iyi şekilde anlamak için derlemenizin bir parçası olarak oluşturulan her ilgili .nupkg.metadata dosyayı okuyacağı başarılı bir paket geri yükleme işlemini tamamlamanızı gerektirir. Araç yalnızca en önemli bağımlılıkları kapsamaz, eşleme oluştururken tüm geçişli bağımlılıkları da dikkate alır.

Araç, ihtiyacınıza bağlı olarak eşleme deseni oluşturma konusunda çeşitli seçeneklere sahiptir. Daha fazla ayrıntı için lütfen blog gönderisine ve aracın benioku yönergesine bakın.

Kaynak eşlemelerinizin nasıl görünebileceği hakkında bir fikir edinmek için örnek depomuza bakın.

Not

• Paket kaynağı eşleme yapılandırmasını yönetmek için nuget.exe veya dotnet.exe komutu yok, bkz . NuGet/Home#10735.
• Paket yükleme zamanında paketleri eşlemek için bir yol yoktur, bkz . NuGet/Home#10730.
• Azure Pipelines görevini kullanırken DotNetCoreCLI@2 kaynak eşleme yapılandırmanızda ön ekleri kullanarak feed- geçici bir sınırlama vardır. Ancak kimlik doğrulama gereksinimleriniz için kullanmanız NuGetAuthenticate ve dotnet cli'yi doğrudan bir betik görevinden çağırmanız önerilir. Bkz. microsoft/azure-pipelines-tasks#15542.