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. Tüm Visual Studio NuGet seçenekleri hakkında ayrıntılı bilgi için bkz. Visual Studio'da NuGet Seçenekleri.

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	✅ Mevcut	❌ Yok	❌ Yok
17,5	✅ Mevcut	✅ Mevcut	❌ Yok
17.7 Önizleme 3	✅ Mevcut	✅ Mevcut	✅ Görüntülenen durum
17.8	✅ Mevcut	✅ Mevcut	✅ PackageReference otomatik olarak eşlemeler oluşturur

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

Eski araçlar, Paket Kaynağı Eşleme yapılandırmasını dikkate almaz. 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.

Video rehberi

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 bir nuget.config'in olması en iyi uygulama olarak kabul edilir. Daha fazla bilgi edinmek için nuget.config belgelerine bakın.

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

Çözümünüzü Visual Studio'da açın.
"Package Source Mappings Seçenekler Penceresi'ne 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'da seçili bir paketi gösteren NuGet Paket Yöneticisi penceresi ve Yapılandır düğmesiyle

Visual Studio Seçenekleri Penceresinden

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

NuGet paket kaynağı eşlemelerini yönetme hakkında ayrıntılı bilgi için bkz. Visual Studio'da NuGet Seçenekleri.

NuGet Paket Yöneticisi penceresi yenilenir ve seçilen paketin kaynak eşlemelerinin yeni durumunu yansıtır. Visual Studio'daki NuGet Paket Yöneticisi penceresi, Yapılandır düğmesiyle

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>

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

Paket Yöneticisi kullanıcı arabirimiyle yükleme

Visual Studio 17.8 veya daha yeni sürümlerden itibaren, aşağıdaki ölçütler karşılandığında Paket Yöneticisi kullanıcı arabirimi, Yükleme veya Güncelleştirme özelliklerini kullanırken, yüklenen paket kimlikleri (en üst düzey ve bağımlı paketler) için otomatik olarak paket kaynağı eşlemeleri oluşturmayı dener.

Bunun otomatik olarak gerçekleşmesi için ölçütler karşılandığında aşağıdaki ileti gösterilir:

Paket kaynağı eşlemesi oluşturulur.

Şu anda kaynak eşlemeleri oluşturma işlemi yalnızca aşağıdaki durumlarda otomatik olarak gerçekleştirilir:

Proje PackageReference kullanıyor.
Paket kaynağı eşlemesi zaten etkin (zaten bir eşleme eklediniz veya NuGet.Config'inizde bir bölüm oluşturdunuz).
Açılan listede tek bir paket kaynağı seçilir (diğer bir ifadeyle, hangi kaynağın eşlenmesi gerektiği belirsiz olduğundan paket kaynakları için "Tümü" seçilmesi desteklenmez).

Paket Yöneticisi kullanıcı arabiriminde Newtonsoft.Json paketi seçilir ve

Genel Paketler Klasörünüzdeki bir bağımlılığın geçerli çözümünüzde etkinleştirilmemiş bir paket kaynağından geldiği tespit edilen işlem NU1110 ile başarısız olabilir. Bu sorunu çözmenin yolları için hata kodu belgelerine bakın.

"Önizleme penceresini göster" seçeneği seçildiğinde, oluşturulan yeni paket kaynağı eşlemeleri listelenir.

Kaynak eşlemeleri için istediğiniz önizleme değilse, yüklemeyi iptal edin ve Yükleme/Güncelleştirme işlemini gerçekleştirmeden önce ilgili kaynak eşlemelerini el ile yapılandırın.

Örneğin, paketin Polly yüklenmesi hem hem de Polly bağımlılığının Polly.Core otomatik olarak seçilen paket kaynağına eşlenmesiyle sonuçlanır nuget.org. Microsoft bağımlı paketleri mevcut paket kaynağı eşlemeleri kullanılarak yükleniyor.

Uygula, Kopyala ve İptal düğmesiyle

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 Deseni 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 üzereher 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 Şablon Söz Dizimi

Desen	Örnek söz dizimi	Description
Paket ön eki deseni	``, `NuGet.`	Bir `` ile bitmeli ve burada `` 0 veya daha fazla karakterle eşleşmelidir. `*` izin verilen en kısa ön ek düzenidir ve tüm paket kimlikleriyle eşleşir.
Paket Kimliği Kalıbı	`NuGet.Common`, `Contoso.Contracts`	Kesin paket kimliği.

Paket Deseni öncelik sırası

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.

Paket Şablonu Öncelik Sırası Örnekleri

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.

Uyarı

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

Get started

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

El ile ekleme

Elle kurulum için aşağıdaki adımları takip edebilirsiniz:

Deponuz için yeni bir genel paketler klasörü bildirin.
Bağımlılıkları geri yüklemek için dotnet restore komutunu çalıştırın.
Çö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.
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.
Genel paketler dizinini temizlemek için dotnet nuget locals global-packages -c komutunu çalıştırın.
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.
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.

Araç kullanarak otomatik işe alım

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.