Opis pliku projektu
Microsoft Build Engine (MSBuild) pliki projektu znajdują się w centrum procesu kompilacji i wdrażania. Ten temat rozpoczyna się od koncepcyjnego omówienia programu MSBuild i pliku projektu. Opisuje on kluczowe składniki, które będą spotykane podczas pracy z plikami projektu, i działa na przykładzie sposobu wdrażania aplikacji rzeczywistych przy użyciu plików projektu.
Zawartość:
- Jak program MSBuild używa plików projektu MSBuild do kompilowania projektów.
- Jak program MSBuild integruje się z technologiami wdrażania, takimi jak Internet Information Services (IIS) Web Deployment Tool (Web Deploy).
- Jak zrozumieć kluczowe składniki pliku projektu.
- Jak używać plików projektu do kompilowania i wdrażania złożonych aplikacji.
MSBuild i plik projektu
Podczas tworzenia i kompilowania rozwiązań w programie Visual Studio program Visual Studio używa programu MSBuild do kompilowania każdego projektu w rozwiązaniu. Każdy projekt programu Visual Studio zawiera plik projektu MSBuild z rozszerzeniem pliku, które odzwierciedla typ projektu — na przykład projekt C# (csproj), projekt visual Basic.NET (vbproj) lub projekt bazy danych (dbproj). Aby utworzyć projekt, program MSBuild musi przetworzyć plik projektu skojarzony z projektem. Plik projektu to dokument XML zawierający wszystkie informacje i instrukcje wymagane przez program MSBuild w celu skompilowania projektu, takiego jak zawartość do uwzględnienia, wymagania dotyczące platformy, informacje o wersji, ustawienia serwera internetowego lub serwera bazy danych oraz zadania, które należy wykonać.
Pliki projektu MSBuild są oparte na schemacie XML programu MSBuild, a w rezultacie proces kompilacji jest całkowicie otwarty i przezroczysty. Ponadto nie trzeba instalować programu Visual Studio w celu korzystania z aparatu MSBuild — plik wykonywalny MSBuild.exe jest częścią .NET Framework i można go uruchomić z poziomu wiersza polecenia. Jako deweloper możesz utworzyć własne pliki projektu MSBuild przy użyciu schematu XML programu MSBuild, aby narzucić zaawansowaną i szczegółową kontrolę nad sposobem kompilowania i wdrażania projektów. Te niestandardowe pliki projektu działają dokładnie tak samo jak pliki projektu generowane automatycznie przez program Visual Studio.
Uwaga
Możesz również użyć plików projektu MSBuild z usługą Team Build w programie Team Foundation Server (TFS). Na przykład można użyć plików projektu w scenariuszach ciągłej integracji (CI), aby zautomatyzować wdrażanie w środowisku testowym po zaewidencjonowaniu nowego kodu. Aby uzyskać więcej informacji, zobacz Konfigurowanie serwera Team Foundation Server na potrzeby zautomatyzowanego wdrażania w sieci Web.
Konwencje nazewnictwa plików projektu
Podczas tworzenia własnych plików projektu możesz użyć dowolnego rozszerzenia pliku, które chcesz. Jednak aby ułatwić zrozumienie rozwiązań innym osobom, należy użyć tych wspólnych konwencji:
- Użyj rozszerzenia .proj podczas tworzenia pliku projektu, który kompiluje projekty.
- Użyj rozszerzenia .targets podczas tworzenia pliku projektu wielokrotnego użytku do importowania do innych plików projektu. Pliki z rozszerzeniem .targets zwykle nie kompilują niczego siebie, zawierają po prostu instrukcje, które można zaimportować do plików proj.
Integracja z technologiami wdrażania
Jeśli korzystasz z projektów aplikacji internetowych w programie Visual Studio 2010, takich jak ASP.NET aplikacje internetowe i ASP.NET aplikacji internetowych MVC, wiesz, że te projekty obejmują wbudowaną obsługę tworzenia pakietów i wdrażania aplikacji internetowej w środowisku docelowym. Strony Właściwości dla tych projektów obejmują karty Package/Publish Web i Package/Publish SQL , których można użyć do skonfigurowania sposobu tworzenia i wdrażania składników aplikacji. Spowoduje to wyświetlenie karty Pakiet/Publikowanie w sieci Web :
Podstawowa technologia umożliwiająca korzystanie z tych funkcji jest znana jako potok publikowania w sieci Web (WPP). Program WPP zasadniczo łączy narzędzia MSBuild i Web Deploy w celu zapewnienia kompletnego procesu kompilacji, pakietu i wdrażania aplikacji internetowych.
Dobrą wiadomością jest możliwość skorzystania z punktów integracji zapewnianych przez program WPP podczas tworzenia niestandardowych plików projektu dla projektów internetowych. Instrukcje wdrażania można uwzględnić w pliku projektu, który umożliwia tworzenie projektów, tworzenie pakietów wdrażania sieci Web i instalowanie tych pakietów na serwerach zdalnych za pomocą pojedynczego pliku projektu i pojedyncze wywołanie programu MSBuild. Możesz również wywołać wszystkie inne pliki wykonywalne w ramach procesu kompilacji. Można na przykład uruchomić narzędzie wiersza polecenia VSDBCMD.exe, aby wdrożyć bazę danych z pliku schematu. W trakcie tego tematu zobaczysz, jak można wykorzystać te możliwości, aby spełnić wymagania scenariuszy wdrażania w przedsiębiorstwie.
Uwaga
Aby uzyskać więcej informacji na temat sposobu działania procesu wdrażania aplikacji internetowej, zobacz ASP.NET Omówienie wdrażania projektu aplikacji internetowej.
Anatomia pliku projektu
Zanim przyjrzysz się bardziej szczegółowo procesowi kompilacji, warto zapoznać się z podstawową strukturą pliku projektu MSBuild. Ta sekcja zawiera omówienie bardziej typowych elementów, które napotkasz podczas przeglądania, edytowania lub tworzenia pliku projektu. W szczególności nauczysz się:
- Jak używać właściwości do zarządzania zmiennymi dla procesu kompilacji.
- Jak używać elementów do identyfikowania danych wejściowych procesu kompilacji, takich jak pliki kodu.
- Jak używać obiektów docelowych i zadań w celu udostępnienia instrukcji wykonywania w programie MSBuild przy użyciu właściwości i elementów zdefiniowanych w innym miejscu w pliku projektu.
Spowoduje to wyświetlenie relacji między kluczowymi elementami w pliku projektu MSBuild:
Element projektu
Element project jest elementem głównym każdego pliku projektu. Oprócz identyfikowania schematu XML dla pliku projektu element Project może zawierać atrybuty w celu określenia punktów wejścia dla procesu kompilacji. Na przykład w przykładowym rozwiązaniu Programu Contact Manager plik Publish.proj określa, że kompilacja powinna rozpoczynać się od wywołania elementu docelowego o nazwie FullPublish.
<Project ToolsVersion="4.0" DefaultTargets="FullPublish"
xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
</Project>
Właściwości i warunki
Plik projektu zazwyczaj musi dostarczać wiele różnych informacji, aby pomyślnie skompilować i wdrożyć projekty. Te informacje mogą obejmować nazwy serwerów, parametry połączenia, poświadczenia, konfiguracje kompilacji, ścieżki plików źródłowych i docelowych oraz wszelkie inne informacje, które mają zostać uwzględnione w celu obsługi dostosowywania. W pliku projektu właściwości muszą być zdefiniowane w elemecie PropertyGroup . Właściwości programu MSBuild składają się z par klucz-wartość. W elemecie PropertyGroup nazwa elementu definiuje klucz właściwości, a zawartość elementu definiuje wartość właściwości. Można na przykład zdefiniować właściwości o nazwie ServerName i ConnectionString, aby przechowywać statyczną nazwę serwera i parametry połączenia.
<PropertyGroup>
<ServerName>FABRIKAM\TEST1</ServerName>
<ConnectionString>
Data Source=FABRIKAM\TESTDB;InitialCatalog=ContactManager,...
</ConnectionString>
</PropertyGroup>
Aby pobrać wartość właściwości, użyj formatu $(PropertyName). Aby na przykład pobrać wartość właściwości ServerName , wpisz:
$(ServerName)
Uwaga
W dalszej części tego tematu przedstawiono przykłady użycia wartości właściwości i ich terminów.
Osadzanie informacji jako właściwości statycznych w pliku projektu nie zawsze jest idealnym podejściem do zarządzania procesem kompilacji. W wielu scenariuszach chcesz uzyskać informacje z innych źródeł lub umożliwić użytkownikowi podanie informacji z wiersza polecenia. Program MSBuild umożliwia określenie dowolnej wartości właściwości jako parametru wiersza polecenia. Na przykład użytkownik może podać wartość ServerName , gdy uruchamia MSBuild.exe z wiersza polecenia.
msbuild.exe Publish.proj /p:ServerName=FABRIKAM\TESTWEB1
Uwaga
Aby uzyskać więcej informacji na temat argumentów i przełączników, których można użyć z MSBuild.exe, zobacz Dokumentacja wiersza polecenia programu MSBuild.
Możesz użyć tej samej składni właściwości, aby uzyskać wartości zmiennych środowiskowych i wbudowanych właściwości projektu. Wiele często używanych właściwości jest definiowanych dla Ciebie i można ich używać w plikach projektu, włączając odpowiednią nazwę parametru. Aby na przykład pobrać bieżącą platformę projektu — na przykład x86 lub AnyCpu — możesz dołączyć odwołanie do właściwości $(Platform) w pliku projektu. Aby uzyskać więcej informacji, zobacz Makra poleceń i właściwości kompilacji, Właściwości projektu Common MSBuild i właściwości zarezerwowane.
Właściwości są często używane w połączeniu z warunkami. Większość elementów MSBuild obsługuje atrybut Warunek , który umożliwia określenie kryteriów, na których program MSBuild powinien ocenić element. Rozważmy na przykład tę definicję właściwości:
<PropertyGroup>
<OutputRoot Condition=" '$(OutputRoot)'=='' ">..\Publish\Out\</OutputRoot>
...
</PropertyGroup>
Gdy program MSBuild przetwarza tę definicję właściwości, najpierw sprawdza, czy jest dostępna wartość właściwości $(OutputRoot). Jeśli wartość właściwości jest pusta — innymi słowy, użytkownik nie podał wartości dla tej właściwości — warunek ma wartość true , a wartość właściwości jest ustawiona na .. \Publish\Out. Jeśli użytkownik podał wartość dla tej właściwości, warunek ma wartość false , a wartość właściwości statycznej nie jest używana.
Aby uzyskać więcej informacji na temat różnych sposobów określania warunków, zobacz Warunki programu MSBuild.
Elementy i grupy elementów
Jedną z ważnych ról pliku projektu jest zdefiniowanie danych wejściowych procesu kompilacji. Zazwyczaj te dane wejściowe są plikami — plikami kodu, plikami konfiguracji, plikami poleceń i innymi plikami, które należy przetworzyć lub skopiować w ramach procesu kompilacji. W schemacie projektu MSBuild te dane wejściowe są reprezentowane przez elementy elementu . W pliku projektu elementy muszą być zdefiniowane w elemencie ItemGroup . Podobnie jak w przypadku elementów właściwości , można jednak nazwać element Item . Należy jednak określić atrybut Include , aby zidentyfikować plik lub symbol wieloznaczny, który reprezentuje element.
<ItemGroup>
<ProjectsToBuild Include="$(SourceRoot)ContactManager-WCF.sln"/>
</ItemGroup>
Określając wiele elementów elementu o tej samej nazwie, skutecznie tworzysz nazwę listy zasobów. Dobrym sposobem, aby zobaczyć to działanie, jest przyjrzenie się jednemu z plików projektu tworzonych przez program Visual Studio. Na przykład plik ContactManager.Mvc.csproj w przykładowym rozwiązaniu zawiera wiele grup elementów, z których każdy ma kilka identycznych nazwanych elementów.
<ItemGroup>
<Reference Include="Microsoft.CSharp" />
<Reference Include="System.Runtime.Serialization" />
<Reference Include="System.ServiceModel" />
...
</ItemGroup>
<ItemGroup>
<Compile Include="Controllers\AccountController.cs" />
<Compile Include="Controllers\ContactsController.cs" />
<Compile Include="Controllers\HomeController.cs" />
...
</ItemGroup>
<ItemGroup>
<Content Include="Content\Custom.css" />
<Content Include="CreateDatabase.sql" />
<Content Include="DropDatabase.sql" />
...
</ItemGroup>
W ten sposób plik projektu nakazuje programowi MSBuild konstruowanie list plików, które muszą być przetwarzane w taki sam sposób — lista odwołań zawiera zestawy, które muszą zostać wprowadzone do pomyślnej kompilacji, lista Kompiluj zawiera pliki kodu, które muszą zostać skompilowane, a lista Zawartość zawiera zasoby, które muszą zostać skopiowane bez zmian. Przyjrzymy się, jak odwołuje się proces kompilacji i używa tych elementów w dalszej części tego tematu.
Elementy elementów mogą również zawierać elementy podrzędne ItemMetadata . Są to pary klucz-wartość zdefiniowane przez użytkownika i zasadniczo reprezentują właściwości specyficzne dla tego elementu. Na przykład wiele elementów kompiluj element w pliku projektu zawiera elementy podrzędne DependentUpon .
<Compile Include="Global.asax.cs">
<DependentUpon>Global.asax</DependentUpon>
</Compile>
Uwaga
Oprócz metadanych elementu utworzonych przez użytkownika wszystkie elementy są przypisywane różne typowe metadane podczas tworzenia. Aby uzyskać więcej informacji, zobacz Dobrze znane metadane elementu.
Elementy ItemGroup można tworzyć w elemencie Project na poziomie głównym lub w określonych elementach docelowych . Elementy ItemGroup obsługują również atrybuty Warunek , które umożliwiają dostosowanie danych wejściowych do procesu kompilacji zgodnie z warunkami, takimi jak konfiguracja projektu lub platforma.
Elementy docelowe i zadania
W schemacie MSBuild element Task reprezentuje indywidualną instrukcję kompilacji (lub zadanie). Program MSBuild zawiera wiele wstępnie zdefiniowanych zadań. Na przykład:
- Zadanie kopiowania kopiuje pliki do nowej lokalizacji.
- Zadanie Csc wywołuje kompilator języka Visual C#.
- Zadanie Vbc wywołuje kompilator Języka Visual Basic.
- Zadanie Exec uruchamia określony program.
- Zadanie Komunikat zapisuje komunikat w rejestratorze.
Uwaga
Aby uzyskać szczegółowe informacje o zadaniach, które są dostępne w całości, zobacz MSBuild Task Reference (Dokumentacja zadań programu MSBuild). Aby uzyskać więcej informacji na temat zadań, w tym sposobu tworzenia własnych zadań niestandardowych, zobacz MSBuild Tasks (Zadania programu MSBuild).
Zadania muszą być zawsze zawarte w elementach docelowych . Element docelowy to zestaw co najmniej jednego zadania, które są wykonywane sekwencyjnie, a plik projektu może zawierać wiele obiektów docelowych. Jeśli chcesz uruchomić zadanie lub zestaw zadań, należy wywołać obiekt docelowy, który je zawiera. Załóżmy na przykład, że masz prosty plik projektu, który rejestruje komunikat.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="LogMessage">
<Message Text="Hello world!" />
</Target>
</Project>
Element docelowy można wywołać z wiersza polecenia, używając przełącznika /t , aby określić element docelowy.
msbuild.exe Publish.proj /t:LogMessage
Alternatywnie możesz dodać atrybut DefaultTargets do elementu Project , aby określić elementy docelowe, które chcesz wywołać.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"
DefaultTargets="FullPublish">
<Target Name="LogMessage">
<Message Text="Hello world!" />
</Target>
</Project>
W takim przypadku nie trzeba określać elementu docelowego z wiersza polecenia. Możesz po prostu określić plik projektu, a program MSBuild wywoła element docelowy FullPublish .
msbuild.exe Publish.proj
Zarówno obiekty docelowe, jak i zadania podrzędne mogą zawierać atrybuty Warunek . W związku z tym można pominąć całe cele lub poszczególne zadania, jeśli zostaną spełnione określone warunki.
Ogólnie rzecz biorąc, podczas tworzenia przydatnych zadań i elementów docelowych należy odwołać się do właściwości i elementów zdefiniowanych w innym miejscu w pliku projektu:
- Aby użyć wartości właściwości, wpisz $(PropertyName), gdzie PropertyName jest nazwą elementu Property lub nazwą parametru.
- Aby użyć elementu, wpisz @(ItemName), gdzie ItemName jest nazwą elementu Item .
Uwaga
Pamiętaj, że jeśli tworzysz wiele elementów o tej samej nazwie, tworzysz listę. Natomiast jeśli utworzysz wiele właściwości o tej samej nazwie, podana ostatnia wartość właściwości zastąpi wszystkie poprzednie właściwości o tej samej nazwie — właściwość może zawierać tylko jedną wartość.
Na przykład w pliku Publish.proj w przykładowym rozwiązaniu przyjrzyj się celowi BuildProjects .
<Target Name="BuildProjects" Condition=" '$(BuildingInTeamBuild)'!='true' ">
<MSBuild Projects="@(ProjectsToBuild)"
Properties="OutDir=$(OutputRoot);
Configuration=$(Configuration);
DeployOnBuild=true;
DeployTarget=Package"
Targets="Build" />
</Target>
W tym przykładzie można obserwować następujące kluczowe kwestie:
Jeśli określono parametr BuildingInTeamBuild i ma wartość true, żadne z zadań w tym obiekcie docelowym nie zostanie wykonane.
Obiekt docelowy zawiera pojedyncze wystąpienie zadania MSBuild . To zadanie umożliwia tworzenie innych projektów PROGRAMU MSBuild.
Element ProjectsToBuild jest przekazywany do zadania. Ten element może reprezentować listę plików projektu lub rozwiązania, wszystkie zdefiniowane przez elementy elementu ProjectsToBuild w grupie elementów. W tym przypadku element ProjectsToBuild odwołuje się do pojedynczego pliku rozwiązania.
<ItemGroup> <ProjectsToBuild Include="$(SourceRoot)ContactManager-WCF.sln"/> </ItemGroup>Wartości właściwości przekazane do zadania MSBuild obejmują parametry o nazwach OutputRoot i Configuration. Są one ustawione na wartości parametrów, jeśli są podane, lub wartości właściwości statycznych, jeśli nie są.
<PropertyGroup> ... <Configuration Condition=" '$(Configuration)'=='' ">Release </Configuration> <OutputRoot Condition=" '$(OutputRoot)'=='' ">..\Publish\Out\ </OutputRoot> ... </PropertyGroup>
Można również zobaczyć, że zadanie MSBuild wywołuje element docelowy o nazwie Build. Jest to jeden z kilku wbudowanych obiektów docelowych, które są powszechnie używane w plikach projektów programu Visual Studio i są dostępne w niestandardowych plikach projektu, takich jak Kompilowanie, Czyszczenie, Odbudowywanie i Publikowanie. Więcej informacji na temat używania elementów docelowych i zadań do kontrolowania procesu kompilacji oraz o zadaniu programu MSBuild znajdziesz w dalszej części tego tematu.
Uwaga
Aby uzyskać więcej informacji na temat obiektów docelowych, zobacz MSBuild Targets (Cele programu MSBuild).
Dzielenie plików projektu w celu obsługi wielu środowisk
Załóżmy, że chcesz mieć możliwość wdrożenia rozwiązania w wielu środowiskach, takich jak serwery testowe, platformy przejściowe i środowiska produkcyjne. Konfiguracja może się znacznie różnić między tymi środowiskami — nie tylko pod względem nazw serwerów, parametrów połączenia itd., ale także potencjalnie w zakresie poświadczeń, ustawień zabezpieczeń i wielu innych czynników. Jeśli musisz to zrobić regularnie, nie jest to naprawdę celowe edytowanie wielu właściwości w pliku projektu za każdym razem, gdy przełączasz środowisko docelowe. Nie jest to idealne rozwiązanie, które wymaga nieograniczonej listy wartości właściwości, które mają być udostępniane procesowi kompilacji.
Na szczęście istnieje alternatywa. Program MSBuild umożliwia podzielenie konfiguracji kompilacji na wiele plików projektu. Aby zobaczyć, jak to działa, w przykładowym rozwiązaniu zwróć uwagę, że istnieją dwa niestandardowe pliki projektu:
- Publish.proj, który zawiera właściwości, elementy i obiekty docelowe, które są wspólne dla wszystkich środowisk.
- Env-Dev.proj, która zawiera właściwości specyficzne dla środowiska deweloperskiego.
Teraz zwróć uwagę, że plik Publish.proj zawiera element Import bezpośrednio pod otwierającym się tagiem project .
<Import Project="$(TargetEnvPropsFile)"/>
Element Import służy do importowania zawartości innego pliku projektu MSBuild do bieżącego pliku projektu MSBuild. W tym przypadku parametr TargetEnvPropsFile zawiera nazwę pliku projektu, który chcesz zaimportować. Wartość tego parametru można podać podczas uruchamiania programu MSBuild.
msbuild.exe Publish.proj /p:TargetEnvPropsFile=EnvConfig\Env-Dev.proj
W ten sposób zawartość tych dwóch plików jest scalona z pojedynczym plikiem projektu. Korzystając z tego podejścia, można utworzyć jeden plik projektu zawierający uniwersalną konfigurację kompilacji i wiele dodatkowych plików projektu zawierających właściwości specyficzne dla środowiska. W związku z tym po prostu uruchomienie polecenia z inną wartością parametru umożliwia wdrożenie rozwiązania w innym środowisku.
Dzielenie plików projektu w ten sposób jest dobrym rozwiązaniem do zastosowania. Umożliwia ona deweloperom wdrażanie w wielu środowiskach przez uruchomienie jednego polecenia, jednocześnie unikając duplikowania uniwersalnych właściwości kompilacji w wielu plikach projektu.
Uwaga
Aby uzyskać wskazówki dotyczące dostosowywania plików projektu specyficznych dla środowiska dla własnych środowisk serwerowych, zobacz Konfigurowanie właściwości wdrożenia dla środowiska docelowego.
Podsumowanie
W tym temacie przedstawiono ogólne wprowadzenie do plików projektu MSBuild i wyjaśniono, jak można tworzyć własne pliki projektów niestandardowych w celu kontrolowania procesu kompilacji. Wprowadzono również koncepcję dzielenia plików projektu na uniwersalne instrukcje kompilacji i właściwości kompilacji specyficzne dla środowiska, aby ułatwić kompilowanie i wdrażanie projektów w wielu miejscach docelowych.
W następnym temacie Understanding the Build Process (Omówienie procesu kompilacji) przedstawiono bardziej szczegółowe informacje na temat sposobu używania plików projektu do kontrolowania kompilacji i wdrażania, przechodząc przez proces wdrażania rozwiązania z realistycznym poziomem złożoności.
Dalsze informacje
Aby uzyskać bardziej szczegółowe wprowadzenie do plików projektu i programu WPP, zobacz Inside the Microsoft Build Engine: Using MSBuild and Team Foundation Build by Sayed Ibrahim Hashimi and William Bartholomew, ISBN: 978-0-7356-4524-0.