📦 .NET 라이브러리 개발과 NuGet 패키지 배포 관리 시스템 완전 정복

1. NuGet이 대체 뭔데? 🤔

NuGet은 .NET 생태계의 공식 패키지 관리자야. JavaScript에 npm, Python에 pip가 있다면 .NET엔 NuGet이 있는 거지. 2010년경 처음 등장했고, 지금은 Visual Studio와 .NET SDK(dotnet CLI)에 기본으로 녹아 있어.

핵심은 아주 단순해. NuGet 패키지(.nupkg)는 사실 ZIP 파일이야. 진짜로 확장자를 .zip으로 바꿔서 열어보면 안에 컴파일된 DLL, 메타데이터가 담긴 .nuspec 파일, README, 아이콘 등이 들어 있어. 별거 없어 보이지? 근데 이 "별거 없는 ZIP"이 버전 관리, 의존성 해석, 타깃 프레임워크 선택까지 다 해주니까 엄청난 거야.

참고로 nuget.org에는 수십만 개의 고유 패키지가 등록돼 있고, 누적 다운로드는 수천억 회 수준이야. 우리가 매일 쓰는 Newtonsoft.Json, Serilog, Dapper, xunit 다 여기서 내려받는 거야.

2. 라이브러리 프로젝트, 첫 단추부터 제대로 🧵

먼저 클래스 라이브러리를 만들어 보자. CLI 한 줄이면 끝나.

dotnet new classlib -n Jaenung.StringKit
cd Jaenung.StringKit

그럼 SDK 스타일 .csproj가 생겨. 예전 .NET Framework 시절의 장황한 csproj와 달리 엄청 짧아졌지. 여기에 패키지 정보를 바로 적을 수 있다는 게 포인트야. 예전처럼 .nuspec을 따로 손으로 쓸 필요가 거의 없어졌어.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFrameworks>netstandard2.0;net8.0</TargetFrameworks>
    <LangVersion>latest</LangVersion>
    <Nullable>enable</Nullable>

    <!-- 패키지 메타데이터 -->
    <PackageId>Jaenung.StringKit</PackageId>
    <Version>1.0.0</Version>
    <Authors>YourName</Authors>
    <Description>문자열 처리를 편하게 해주는 유틸리티 모음</Description>
    <PackageTags>string;utility;korean</PackageTags>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
    <PackageReadmeFile>README.md</PackageReadmeFile>
    <PackageIcon>icon.png</PackageIcon>
    <RepositoryUrl>https://github.com/you/StringKit</RepositoryUrl>

    <!-- 품질 옵션 -->
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
  </PropertyGroup>

  <ItemGroup>
    <None Include="README.md" Pack="true" PackagePath="\" />
    <None Include="icon.png" Pack="true" PackagePath="\" />
  </ItemGroup>

</Project>

3. 타깃 프레임워크, 뭘 골라야 해? 🎯

라이브러리 개발자가 제일 많이 고민하는 부분이야. "netstandard2.0? net8.0? 둘 다?"

마이크로소프트 공식 라이브러리 가이드의 권장은 대략 이래: .NET Framework 사용자까지 품고 싶으면 netstandard2.0을 포함하고, 최신 기능이 필요하면 net8.0 같은 최신 타깃을 같이 넣어라. 즉 멀티 타기팅이 정석이야. NuGet은 설치하는 쪽 프로젝트에 가장 잘 맞는 DLL을 자동으로 골라줘.

타깃별로 코드를 다르게 하고 싶으면 전처리기 기호를 쓰면 돼.

public static int CountChars(string text, char target)
{
#if NET8_0_OR_GREATER
    return text.AsSpan().Count(target);   // 최신 API
#else
    int n = 0;
    foreach (var c in text) if (c == target) n++;
    return n;
#endif
}

4. 버전 번호, 대충 올리면 큰일 나 🔢

NuGet은 SemVer 2.0(시맨틱 버저닝)을 따라. MAJOR.MINOR.PATCH 형식이고 규칙은 이래.

여기서 많이들 헷갈리는 게 .NET에 버전이 여러 개 있다는 거야.

사용하는 쪽에서는 버전 범위도 지정할 수 있어. Version="1.2.0"은 사실 "1.2.0 이상"이라는 뜻이야(최소 버전). 정확히 고정하려면 [1.2.0], 범위는 [1.0,2.0)처럼 수학 구간 표기를 써. 그리고 NuGet은 의존성 해석 시 조건을 만족하는 가장 낮은 버전을 고르는 게 기본 규칙이야. npm처럼 "최신 걸로 줄게~" 방식이 아니라서, 예상치 못한 업그레이드가 덜 일어나.

5. 좋은 라이브러리의 품격 ✨

패키지를 만드는 건 쉬워. 근데 "남들이 믿고 쓰는" 패키지를 만드는 건 좀 다른 얘기야. 꼭 챙길 것들 정리해볼게.

<EnablePackageValidation>true</EnablePackageValidation>

Package Validation 설정 예시는 이래.

<PropertyGroup>
  <EnablePackageValidation>true</EnablePackageValidation>
  <PackageValidationBaselineVersion>1.0.0</PackageValidationBaselineVersion>
  <ContinuousIntegrationBuild Condition="'$(GITHUB_ACTIONS)' == 'true'">true</ContinuousIntegrationBuild>
</PropertyGroup>

6. 포장하고 맛보기: pack과 로컬 테스트 🍱

이제 진짜 포장해보자.

dotnet pack -c Release -o ./artifacts

그럼 artifacts 폴더에 Jaenung.StringKit.1.0.0.nupkg와 .snupkg가 생겨. 바로 nuget.org에 올리고 싶겠지만 잠깐! 🛑 nuget.org는 같은 ID·버전을 다시 올릴 수 없어. 실수하면 버전을 새로 올려야 해. 그러니까 로컬에서 먼저 맛을 보자.

# 로컬 폴더를 피드로 등록
dotnet nuget add source ./artifacts -n LocalTest

# 테스트 프로젝트에서 설치해보기
dotnet add package Jaenung.StringKit --version 1.0.0

그리고 NuGet Package Explorer(오픈소스 GUI 도구)로 nupkg를 열어보면 어떤 파일이 어떤 폴더(lib/netstandard2.0, lib/net8.0)에 들어갔는지, README나 아이콘이 잘 들어갔는지 눈으로 확인할 수 있어. 첫 배포 전에 꼭 해봐.

7. 배포의 무대: 어디에 올릴까? 🏪

회사에서는 보통 "사내 공통 라이브러리는 비공개 피드에, 외부 오픈소스는 nuget.org에서"라는 구조를 써. 이때 여러 피드를 섞어 쓰게 되는데, 여기서 무서운 보안 이슈가 하나 있어.

🔐 의존성 혼동(Dependency Confusion) 공격

2021년 보안 연구자 Alex Birsan이 공개해서 화제가 된 공격이야. 사내 패키지 이름이 MyCorp.Auth인데, 누군가 nuget.org(공개 저장소)에 같은 이름으로 더 높은 버전의 악성 패키지를 올리면? 설정이 허술한 빌드 서버가 공개 쪽 걸 받아버릴 수 있어. 😱

NuGet의 대응책은 두 가지야.

① 패키지 소스 매핑 (Package Source Mapping) - NuGet 6.0부터 지원. "어떤 패키지 이름 패턴은 어떤 피드에서만 받는다"를 명시해.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="company" value="https://pkgs.dev.azure.com/mycorp/_packaging/main/nuget/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="company">
      <package pattern="MyCorp.*" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

더 구체적인 패턴(MyCorp.*)이 우선 적용되니까, MyCorp로 시작하는 패키지는 무조건 사내 피드에서만 오게 돼. 이 nuget.config를 저장소 루트에 커밋해두면 팀 전체가 같은 규칙을 따라.

② ID 접두사 예약 (Prefix Reservation) - nuget.org에서 MyCorp. 같은 접두사를 신청해 예약하면 남이 그 접두사로 패키지를 못 올려. 예약된 접두사 패키지에는 파란 체크 표시도 붙어서 신뢰도도 올라가지.

8. 패키지 관리 시스템: 중앙에서 버전 다스리기 🎛️

프로젝트가 30개쯤 되는 솔루션에서 Serilog 버전이 프로젝트마다 제각각이면? 그거 진짜 악몽이야. 그래서 나온 게 중앙 패키지 관리(Central Package Management, CPM)야. NuGet 6.2부터 정식 지원돼.

솔루션 루트에 Directory.Packages.props 파일 하나를 만들어.

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="Serilog" Version="4.0.0" />
    <PackageVersion Include="xunit" Version="2.9.0" />
  </ItemGroup>
</Project>

그러면 각 프로젝트에서는 버전 없이 이름만 쓰면 돼.

<PackageReference Include="Serilog" />

버전 업그레이드는 이제 파일 하나만 고치면 끝! 🎉 여기에 공통 메타데이터(Authors, License, RepositoryUrl 등)는 Directory.Build.props에 몰아넣으면 여러 라이브러리를 한 저장소에서 관리하는 모노레포 구조가 깔끔해져.

9. 자동 배포 파이프라인 만들기 🤖

손으로 dotnet nuget push 하는 것도 몇 번은 괜찮아. 근데 결국 사람은 실수를 해. 버전 올리는 거 까먹고, 테스트 안 돌리고 올리고... 그러니까 CI/CD로 자동화하자.

GitHub Actions 예시를 보자. Git 태그 v1.2.0을 푸시하면 그 버전으로 패키지를 만들어 배포하는 흐름이야.

name: publish

on:
  push:
    tags: [ 'v*' ]

permissions:
  contents: read
  id-token: write   # Trusted Publishing(OIDC)용

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Test
        run: dotnet test -c Release

      - name: Pack
        run: |
          VERSION=${GITHUB_REF_NAME#v}
          dotnet pack -c Release -o out -p:Version=$VERSION

      - name: Push
        run: dotnet nuget push "out/*.nupkg" --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate

포인트 몇 개 짚어볼게.

• ${GITHUB_REF_NAME#v} : 태그 이름에서 앞의 v를 떼서 버전으로 써. 버전의 "진실의 원천"이 Git 태그가 되는 거지.
• --skip-duplicate : 이미 같은 버전이 있으면 에러 대신 건너뛰어. 재실행할 때 편해.
• .nupkg를 푸시하면 같은 폴더의 .snupkg도 함께 올라가.

🏷️ 버전 자동 계산 도구

태그 방식 말고도 버전을 자동으로 계산해주는 도구들이 있어.

10. 출시 이후의 삶: 운영과 관리 🌿

배포했다고 끝이 아니야. 오히려 그때부터 진짜 관리 시작이지.

그리고 신뢰의 끝판왕은 패키지 서명이야. nuget.org는 업로드된 모든 패키지에 저장소 서명(repository signature)을 자동으로 붙여. 여기에 작성자가 코드 서명 인증서로 작성자 서명(author signature)을 추가하면 "이 패키지는 확실히 내가 만든 것"이라는 걸 증명할 수 있지. dotnet nuget sign과 dotnet nuget verify 명령으로 다룰 수 있어.

11. 한눈에 정리하는 체크리스트 ✅

마무리: 코드를 '나누는' 기술 🤝

라이브러리를 만들고 NuGet으로 배포한다는 건, 결국 내 코드를 다른 사람이 믿고 쓸 수 있게 만드는 일이야. 복붙하던 유틸 클래스가 버전이 붙고, 문서가 생기고, 자동으로 배포되고, 보안 경고까지 받는 "제품"이 되는 거지. 처음엔 설정할 게 많아 보이지만, 한 번 템플릿을 잡아두면 다음 라이브러리부터는 dotnet new 한 줄로 시작하는 기분일 거야.

이렇게 쌓은 C# 라이브러리 설계 경험은 그 자체로 훌륭한 포트폴리오가 돼. 재능넷 같은 재능 공유 플랫폼에서 "사내 공통 모듈 패키지화", "NuGet 배포 파이프라인 구축" 같은 작업을 의뢰받거나 노하우를 나누는 개발자도 꽤 많아. 오늘 배운 걸로 일단 작은 패키지 하나 nuget.org에 올려봐. 내 패키지 다운로드 수가 1에서 2로 바뀌는 순간, 그 짜릿함은 진짜 못 잊어 😎

#NuGet #.NET #C# #라이브러리설계 #CI/CD