masoodafar-web
360 lines
11 KiB
Markdown
360 lines
11 KiB
Markdown
# مدیریت Package های Proto در FourSat با GitLab Registry
|
|
|
|
> **تاریخ**: December 6, 2025
|
|
> **NuGet Server**: GitLab Package Registry (Afrino)
|
|
> **URL**: `https://git.afrino.co/api/packages/FourSat/nuget/index.json`
|
|
|
|
---
|
|
|
|
## 📊 معماری فعلی
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────┐
|
|
│ LAYER 1: CMS Proto (Base) │
|
|
│ CMSMicroservice.Protobuf │
|
|
│ Version: 0.0.142 → Auto-push به GitLab │
|
|
└─────────────────┬──────────────────────────────────┘
|
|
│ PackageReference
|
|
▼
|
|
┌────────────────────────────────────────────────────┐
|
|
│ LAYER 2: BFF Protos │
|
|
│ BackOffice.BFF.*.Protobuf (14 packages) │
|
|
│ FrontOffice.BFF.*.Protobuf (8 packages) │
|
|
│ → Depend on: CMS Proto v0.0.x │
|
|
└─────────────────┬──────────────────────────────────┘
|
|
│ PackageReference
|
|
▼
|
|
┌────────────────────────────────────────────────────┐
|
|
│ LAYER 3: UI Applications │
|
|
│ BackOffice UI → BackOffice.BFF Protos │
|
|
│ FrontOffice UI → FrontOffice.BFF Protos │
|
|
└────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 تنظیمات فعلی در csproj
|
|
|
|
شما از قبل این Target را دارید:
|
|
|
|
```xml
|
|
<Target Name="PushToFoursatNuget" AfterTargets="Pack">
|
|
<PropertyGroup>
|
|
<NugetPackagePath>$(PackageOutputPath)$(PackageId).$(Version).nupkg</NugetPackagePath>
|
|
<PushCommand>dotnet nuget push **/*.nupkg --source https://git.afrino.co/api/packages/FourSat/nuget/index.json --api-key 061a5cb15517c6da39c16cfce8556c55ae104d0d --skip-duplicate && del "$(NugetPackagePath)"</PushCommand>
|
|
</PropertyGroup>
|
|
<Exec Command="$(PushCommand)" />
|
|
</Target>
|
|
```
|
|
|
|
✅ **مزیت**: خودکار push میشه
|
|
⚠️ **نیاز**: فقط Version افزایش پیدا کنه
|
|
|
|
---
|
|
|
|
## 🚀 Workflow پیشنهادی
|
|
|
|
### حالت 1️⃣: Development (Local)
|
|
|
|
```xml
|
|
<!-- Debug Mode: استفاده از ProjectReference -->
|
|
<ItemGroup Condition="'$(Configuration)' == 'Debug'">
|
|
<ProjectReference Include="..\..\..\CMS\src\CMSMicroservice.Protobuf\CMSMicroservice.Protobuf.csproj" />
|
|
</ItemGroup>
|
|
```
|
|
|
|
**مزایا**:
|
|
- تغییرات بلافاصله اعمال میشود
|
|
- نیازی به build/pack/push نیست
|
|
- سرعت توسعه بالا
|
|
|
|
### حالت 2️⃣: Production (Release)
|
|
|
|
```xml
|
|
<!-- Release Mode: استفاده از PackageReference -->
|
|
<ItemGroup Condition="'$(Configuration)' == 'Release'">
|
|
<PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="0.0.142" />
|
|
</ItemGroup>
|
|
|
|
<!-- Auto-Push Target -->
|
|
<Target Name="PushToFoursatNuget" AfterTargets="Pack" Condition="'$(Configuration)' == 'Release'">
|
|
<!-- ... همان کدی که دارید -->
|
|
</Target>
|
|
```
|
|
|
|
**مزایا**:
|
|
- استقلال پروژهها
|
|
- Version control دقیق
|
|
- امکان Rollback
|
|
|
|
---
|
|
|
|
## 📝 مثال کامل csproj
|
|
|
|
### CMSMicroservice.Protobuf.csproj
|
|
|
|
```xml
|
|
<Project Sdk="Microsoft.NET.Sdk">
|
|
|
|
<PropertyGroup>
|
|
<TargetFramework>net9.0</TargetFramework>
|
|
<ImplicitUsings>enable</ImplicitUsings>
|
|
<Nullable>enable</Nullable>
|
|
|
|
<!-- Package Info -->
|
|
<PackageId>Foursat.CMSMicroservice.Protobuf</PackageId>
|
|
<Version>0.0.142</Version> <!-- 👈 این خط را با script تغییر میدهیم -->
|
|
<Authors>FourSat Team</Authors>
|
|
<Company>Afrino</Company>
|
|
<Description>gRPC Protobuf contracts for CMS Microservice</Description>
|
|
<RepositoryUrl>https://git.afrino.co/FourSat/cms</RepositoryUrl>
|
|
</PropertyGroup>
|
|
|
|
<!-- Dependencies -->
|
|
<ItemGroup>
|
|
<PackageReference Include="Google.Protobuf" Version="3.23.3" />
|
|
<PackageReference Include="Grpc.Core.Api" Version="2.54.0" />
|
|
<PackageReference Include="Grpc.Tools" Version="2.55.1">
|
|
<PrivateAssets>all</PrivateAssets>
|
|
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
|
|
</PackageReference>
|
|
</ItemGroup>
|
|
|
|
<!-- Proto Files -->
|
|
<ItemGroup>
|
|
<Protobuf Include="Protos\*.proto" ProtoRoot="Protos\" GrpcServices="Both" />
|
|
</ItemGroup>
|
|
|
|
<!-- Auto-Push به GitLab (فقط در Release mode) -->
|
|
<Target Name="PushToFoursatNuget" AfterTargets="Pack" Condition="'$(Configuration)' == 'Release'">
|
|
<PropertyGroup>
|
|
<NugetPackagePath>$(PackageOutputPath)$(PackageId).$(Version).nupkg</NugetPackagePath>
|
|
<PushCommand>dotnet nuget push "$(NugetPackagePath)" --source https://git.afrino.co/api/packages/FourSat/nuget/index.json --api-key 061a5cb15517c6da39c16cfce8556c55ae104d0d --skip-duplicate</PushCommand>
|
|
</PropertyGroup>
|
|
<Exec Command="$(PushCommand)" />
|
|
<!-- پاک کردن فایل بعد از push موفق -->
|
|
<Delete Files="$(NugetPackagePath)" />
|
|
</Target>
|
|
|
|
</Project>
|
|
```
|
|
|
|
### BackOffice.BFF.Products.Protobuf.csproj
|
|
|
|
```xml
|
|
<Project Sdk="Microsoft.NET.Sdk">
|
|
|
|
<PropertyGroup>
|
|
<TargetFramework>net9.0</TargetFramework>
|
|
<PackageId>Foursat.BackOffice.BFF.Products.Protobuf</PackageId>
|
|
<Version>1.0.0</Version> <!-- 👈 این را با script تغییر میدهیم -->
|
|
</PropertyGroup>
|
|
|
|
<!-- gRPC Dependencies -->
|
|
<ItemGroup>
|
|
<PackageReference Include="Google.Protobuf" Version="3.28.3" />
|
|
<PackageReference Include="Grpc.Core.Api" Version="2.70.0" />
|
|
<PackageReference Include="Grpc.Tools" Version="2.68.1">
|
|
<PrivateAssets>all</PrivateAssets>
|
|
</PackageReference>
|
|
</ItemGroup>
|
|
|
|
<!-- 🔧 Development: ProjectReference -->
|
|
<ItemGroup Condition="'$(Configuration)' == 'Debug'">
|
|
<ProjectReference Include="..\..\..\CMS\src\CMSMicroservice.Protobuf\CMSMicroservice.Protobuf.csproj" />
|
|
</ItemGroup>
|
|
|
|
<!-- 🚀 Production: PackageReference -->
|
|
<ItemGroup Condition="'$(Configuration)' == 'Release'">
|
|
<PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="0.0.142" />
|
|
</ItemGroup>
|
|
|
|
<!-- Proto Files -->
|
|
<ItemGroup>
|
|
<Protobuf Include="Protos\products.proto" ProtoRoot="Protos\" GrpcServices="Both" />
|
|
</ItemGroup>
|
|
|
|
<!-- Auto-Push به GitLab -->
|
|
<Target Name="PushToFoursatNuget" AfterTargets="Pack" Condition="'$(Configuration)' == 'Release'">
|
|
<PropertyGroup>
|
|
<NugetPackagePath>$(PackageOutputPath)$(PackageId).$(Version).nupkg</NugetPackagePath>
|
|
<PushCommand>dotnet nuget push "$(NugetPackagePath)" --source https://git.afrino.co/api/packages/FourSat/nuget/index.json --api-key 061a5cb15517c6da39c16cfce8556c55ae104d0d --skip-duplicate</PushCommand>
|
|
</PropertyGroup>
|
|
<Exec Command="$(PushCommand)" />
|
|
<Delete Files="$(NugetPackagePath)" />
|
|
</Target>
|
|
|
|
</Project>
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 فرآیند Release جدید
|
|
|
|
### مرحله 1: افزایش Version
|
|
|
|
```bash
|
|
# افزایش Patch version (0.0.142 → 0.0.143)
|
|
./bump-version.sh patch
|
|
|
|
# افزایش Minor version (0.0.142 → 0.1.0)
|
|
./bump-version.sh minor
|
|
|
|
# افزایش Major version (0.0.142 → 1.0.0)
|
|
./bump-version.sh major
|
|
|
|
# افزایش version یک پروژه خاص
|
|
./bump-version.sh patch /path/to/Project.csproj
|
|
```
|
|
|
|
### مرحله 2: Build & Pack (Auto-Push)
|
|
|
|
```bash
|
|
# Build & Pack CMS Proto (Layer 1)
|
|
cd /home/masoud/Apps/project/FourSat/CMS/src/CMSMicroservice.Protobuf
|
|
dotnet pack -c Release
|
|
|
|
# ✅ بعد از Pack، خودکار push میشه به GitLab!
|
|
```
|
|
|
|
### مرحله 3: Update BFF Dependencies
|
|
|
|
```bash
|
|
# بعد از push CMS Proto، version جدید را در BFF ها update کنید:
|
|
# BackOffice.BFF.Products.Protobuf.csproj:
|
|
|
|
<ItemGroup Condition="'$(Configuration)' == 'Release'">
|
|
<PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="0.0.143" /> <!-- ⬅️ Update -->
|
|
</ItemGroup>
|
|
```
|
|
|
|
### مرحله 4: Build & Pack BFF Protos (Layer 2)
|
|
|
|
```bash
|
|
# Build & Pack همه BackOffice.BFF Protos
|
|
cd /home/masoud/Apps/project/FourSat/BackOffice.BFF/src/Protobufs
|
|
|
|
for dir in BackOffice.BFF.*.Protobuf; do
|
|
cd "$dir"
|
|
dotnet pack -c Release # ✅ Auto-push میشه
|
|
cd ..
|
|
done
|
|
```
|
|
|
|
### مرحله 5: Update UI Dependencies
|
|
|
|
```bash
|
|
# BackOffice.csproj:
|
|
|
|
<ItemGroup Condition="'$(Configuration)' == 'Release'">
|
|
<PackageReference Include="Foursat.BackOffice.BFF.Products.Protobuf" Version="1.0.1" /> <!-- ⬅️ Update -->
|
|
<!-- ... other protos -->
|
|
</ItemGroup>
|
|
```
|
|
|
|
---
|
|
|
|
## 🛠️ Scripts خودکار
|
|
|
|
### 1. `bump-version.sh` - افزایش Version
|
|
|
|
```bash
|
|
# همه Proto projects
|
|
./bump-version.sh patch
|
|
|
|
# یک پروژه خاص
|
|
./bump-version.sh minor CMS/src/CMSMicroservice.Protobuf/CMSMicroservice.Protobuf.csproj
|
|
```
|
|
|
|
### 2. `release-proto.sh` - Release کامل
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
|
|
# 1. Bump version
|
|
./bump-version.sh patch
|
|
|
|
# 2. Build & Pack (Auto-push)
|
|
cd CMS/src/CMSMicroservice.Protobuf
|
|
dotnet pack -c Release
|
|
|
|
# 3. Commit changes
|
|
git add .
|
|
git commit -m "chore: bump proto version"
|
|
git push
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 Version Strategy
|
|
|
|
```
|
|
0.0.142 → Current CMS Proto version
|
|
│ │ │
|
|
│ │ └── PATCH: Bug fixes, compatible changes
|
|
│ └───── MINOR: New features, compatible
|
|
└────── MAJOR: Breaking changes
|
|
```
|
|
|
|
**مثال**:
|
|
- اضافه کردن فیلد جدید → **PATCH** (0.0.143)
|
|
- اضافه کردن RPC جدید → **MINOR** (0.1.0)
|
|
- تغییر signature RPC → **MAJOR** (1.0.0)
|
|
|
|
---
|
|
|
|
## 🔍 بررسی Packages روی GitLab
|
|
|
|
```bash
|
|
# اضافه کردن GitLab source
|
|
dotnet nuget add source https://git.afrino.co/api/packages/FourSat/nuget/index.json \
|
|
--name foursat-gitlab \
|
|
--username YOUR_USERNAME \
|
|
--password 061a5cb15517c6da39c16cfce8556c55ae104d0d \
|
|
--store-password-in-clear-text
|
|
|
|
# جستجو
|
|
dotnet nuget search Foursat --source foursat-gitlab
|
|
|
|
# نصب
|
|
dotnet add package Foursat.CMSMicroservice.Protobuf --version 0.0.142 --source foursat-gitlab
|
|
```
|
|
|
|
---
|
|
|
|
## ⚙️ nuget.config (Optional)
|
|
|
|
```xml
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<configuration>
|
|
<packageSources>
|
|
<clear />
|
|
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
|
|
<add key="foursat-gitlab" value="https://git.afrino.co/api/packages/FourSat/nuget/index.json" />
|
|
</packageSources>
|
|
|
|
<packageSourceCredentials>
|
|
<foursat-gitlab>
|
|
<add key="Username" value="foursat" />
|
|
<add key="ClearTextPassword" value="061a5cb15517c6da39c16cfce8556c55ae104d0d" />
|
|
</foursat-gitlab>
|
|
</packageSourceCredentials>
|
|
</configuration>
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 خلاصه
|
|
|
|
✅ **Development** → Debug build → `ProjectReference` → سرعت بالا
|
|
✅ **Production** → Release build → `PackageReference` → استقلال
|
|
✅ **Auto-Push** → بعد از Pack خودکار به GitLab میره
|
|
✅ **Version Bump** → با `bump-version.sh` خودکار
|
|
✅ **Rollback** → برگشت به version قبلی ساده
|
|
|
|
---
|
|
|
|
**تاریخ**: December 6, 2025
|
|
**NuGet Registry**: GitLab (Afrino)
|
|
**Current CMS Version**: 0.0.142
|